课程中的API 数据响应格式不统一是不是不规范呢?如何修改?

大家好!我参考课程把工作中的接口都做完了,现在感觉不是统一的,感到十分困惑。

以用户登录为例

登录成功返回
{
“access_token”: “eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9jZ2VkdS50ZXN0XC9hcGlcL3YxXC9hdXRob3JpemF0aW9ucyIsImlhdCI6MTYwMzE4MDkwMCwiZXhwIjoxNjAzMTg0NTAwLCJuYmYiOjE2MDMxODA5MDAsImp0aSI6IjVRMTRWa1o4Rm1oZEpjTVUiLCJzdWIiOjEsInBydiI6Ijg3ZTBhZjFlZjlmZDE1ODEyZmRlYzk3MTUzYTE0ZTBiMDQ3NTQ2YWEifQ.Bbc-nZZjxiNJL1w63TLMSn3c2kulz4ZWK2jtqVkbRO0”,
“token_type”: “Bearer”,
“expires_in”: 3600
}
返回是三个字段:access_token,token_type, expires_in。

登录失败返回

{
“message”: “用户名或密码错误”
}
返回是一个字段:message。

又举例:
获取分类列表:

返回一个字段:data

获取贴子列表:

返回三个字段:data, links, meta

等等。

因为最近在看另一个课程,
他的接口返回数据全部是这样的格式:
都有两个字段:data,meta
这样前端接收时,就先判断meta中的status,再接收数据,比较方便。

{
    "data": {
        "total": 5,
        "pagenum": 1,
        "users": [
            {
                "id": 25,
                "username": "tige117",
                "mobile": "18616358651",
                "type": 1,
                "email": "tige112@163.com",
                "create_time": "2017-11-09T20:36:26.000Z",
                "mg_state": true, // 当前用户的状态
                "role_name": "某管理员"
            }
        ]
    },
    "meta": {
        "msg": "获取成功",
        "status": 200
    }
}

前面有一个贴子讲到 自定义数据返回格式,问答:dingo API 自定义数据响应格式?
是不是他们的这些才是规范的?

现在我感到很困惑,到底要不要一个个去修改?

请问大家是怎么做的呢?
感谢大家!

《L02 从零构建论坛系统》
以构建论坛项目 LaraBBS 为线索,展开对 Laravel 框架的全面学习。应用程序架构思路贴近 Laravel 框架的设计哲学。
《G01 Go 实战入门》
从零开始带你一步步开发一个 Go 博客项目,让你在最短的时间内学会使用 Go 进行编码。项目结构很大程度上参考了 Laravel。
最佳答案

首先你要明确一点,接口开发出来是给谁用的,明确了这一点之后,一般为了规范化,开发前就应当协定好统一的接口数据返回格式,例如laravel可以使用 return response()->json(array[])来自定义你们自己协定的数据格式,array[]部分一般情况下也就包括 'status','code','message','data',基本上已经可以完全满足绝大对部分的需求。
最后,所谓规范是相对的,不是绝对的,你所说的另一个课程也好,帖子也好,他们的规范都只是目前比较适用的能被大多数人接受的规范模型罢了。只要你们自己开发内部协定好,那对你们来说就是规范的,何必纠结于哪种更规范。
最后的最后,如果你已经像课程一样编写了自己的正式业务代码,还是尽快趁代码量迭代起来之前挨个统一改一下吧,后续开发也遵循自己协定好的规范就行了

3年前 评论
讨论数量: 7

首先你要明确一点,接口开发出来是给谁用的,明确了这一点之后,一般为了规范化,开发前就应当协定好统一的接口数据返回格式,例如laravel可以使用 return response()->json(array[])来自定义你们自己协定的数据格式,array[]部分一般情况下也就包括 'status','code','message','data',基本上已经可以完全满足绝大对部分的需求。
最后,所谓规范是相对的,不是绝对的,你所说的另一个课程也好,帖子也好,他们的规范都只是目前比较适用的能被大多数人接受的规范模型罢了。只要你们自己开发内部协定好,那对你们来说就是规范的,何必纠结于哪种更规范。
最后的最后,如果你已经像课程一样编写了自己的正式业务代码,还是尽快趁代码量迭代起来之前挨个统一改一下吧,后续开发也遵循自己协定好的规范就行了

3年前 评论
liyu001989

通过状态码区分,错误数据里面有message 用于统一的提示。数据区,单个资源是个对象,集合中一定有 data,data是个 数组,分页 会有data 数组,以及分页信息

3年前 评论

非常谢谢 @寻梦 , 我明白了,你的回答帮助了我。

3年前 评论

非常谢谢@liyu001989 ,我明白了,原来课程中的返回格式也是有规则的。

3年前 评论

@寻梦,@liyu001989 你们好!可否再请教,如果我想把状态码写在 返回的数据里,数据格式统一写为 :code,message, data
而data里就是现在的data,单个资源是个对象,集合中再包含 data,
应该怎么改写呢?我看看代码,不知道状态码是在哪里生成的,应该写在哪里呢?
非常谢谢!

现在的代码是:以分类为例:
Controller文件

class CategoryController extends Controller
{
    public function index(Category $category){
        $categories = $category->getAllCached();
        CategoryResource::wrap('data');
        return CategoryResource::collection($categories);
    }
}

Resource文件

<?php

namespace App\Http\Resources;

use Illuminate\Http\Resources\Json\JsonResource;

class CategoryResource extends JsonResource
{
    /**
     * Transform the resource into an array.
     *
     * @param  \Illuminate\Http\Request  $request
     * @return array
     */
    public function toArray($request)
    {
        $this->resource->addHidden(['parent_id', 'created_at', 'updated_at', 'order']);
        return parent::toArray($request);
    }
}

现在返回的是:

{
    "data": [
        {
            "id": 1,
            "title": "全部",
            "desc": "简介",
            "cover": "http://cdn-media.yyii.info/image/course_01.jpg"
        }
     ]
}

希望改为:

{
"code": 200,
"message": "返回成功",
"data": {
    "data": [
        {
            "id": 1,
            "title": "全部",
            "desc": "简介",
            "cover": "http://cdn-media.yyii.info/image/course_01.jpg"
        }
     ]
 }
}
3年前 评论

@phpervip 可以自定义一个公共函数,然后不管什么接口返回数据时都调用该公共函数然后把实际要返回的数据当作参数传入。

if (! function_exists('requestFail')) {
    function requestFail($code, $msg, $data = [])
    {
        return response()->json([
            'status' => false,
            'code' => $code,
            'message' => $msg,
            'data' => $data,
        ]);
    }
}

类似这种方式,所有失败的请求都调用该函数返回就可以了,code、message、data都是参数,调用时再根据不同接口情况传递不同参数然后直接

return requestFail(404,'资源未找到',$data);

就可以了啊。成功的请求也是同理。 至于状态码,当然是根据实际接口情况传入不同的code,这个code可以是定义好的类常量、公共的变量,都可以,看实际需求

3年前 评论
phpervip (楼主) 3年前

讨论应以学习和精进为目的。请勿发布不友善或者负能量的内容,与人为善,比聪明更重要!