API 返回数据结构设计怎么做

看看腾讯或者阿里的开发文档，腾讯的接口习惯把数据打平，直接返回字段，错误信息放在errmsg, errcode 字段里面

我们习惯把数据和附属信息分开，大概是这样的：

interface CommonResponse<T> {
  data: T;          // 返回具体数据结构
  paging: {
    next: string;   // 用于 cursor base 分页
    prev: string;   // 用于 cursor base 分页
    size: number;   // 用于 offset,size 分页
    offset: number; // 用于 offset,size 分页
  };
  error: {
    code: number;   // 错误码
    message: string;// 详细错误信息
  };
}

大同小异，code 和 message 字段每次都会返回，包括请求成功的时候：返回 200, "OK" 之类的信息，方便前端统一处理

interface R<T> {
    data: T;         // 请求数据，可以是对象或者数组
    code: number;    // 错误码
    message: string; // 错误信息，提示信息
    extra: any;      // 额外信息，全局信息等等
}

facebook 的错误信息是这么做的：Handling Errors

{
  "error": {
    "message": "Message describing the error", 
    "type": "OAuthException", 
    "code": 190,
    "error_subcode": 460,
    "error_user_title": "A title",
    "error_user_msg": "A message",
    "fbtrace_id": "EJplcsCHuLu"
  }
}

单独一个字段 error 出来比较方便拓展错误信息。

twitter 错误信息用的 errors 这样能够返回多个错误信息，参考：Error Messages，其他数据用 data、meta 字段返回

{
    "errors":[
        { "message":"Sorry, that page does not exist","code":34}
    ]
}

有一些标准定义可以参考：

• Json API：不止包含返回数据结构，还有 hateoas 相关信息
• odata-json-format：比较全面的一套 API 通用接口设计
• jSend：简单返回规范
• Google json guide：谷歌的 json 接口规范，和二楼的回答比较相似
• HAL：超文本应用语言，更接近 hateoas 规范，spring boot 的返回数据结构很多就长这样，如下图：

不过讲真的，hateoas 想法很美好，实际很少公司会做到完整的 hateoas 规范，如果真的需要这些表述状态转移信息，不如直接上 graphql 自定义能力更强。

instagram 的做法，和 twitter 有点像

{
    "meta": {
         "error_type": "OAuthException",
         "code": 400,
         "error_message": "..."
    }
    "data": {
         ...
    },
    "pagination": {
         "next_url": "...",
         "next_max_id": "13872296"
    }
}