Sublime开发JSON API数据返回结构规范_标准化响应格式与状态码

在Sublime开发JSON API时，设计标准化的数据返回结构与状态码需遵循以下规范，以提升接口可读性并降低协作成本：

响应体必须包含以下三个核心字段，且无论成功或失败均需保持结构一致：

1. status 或 code

   表示请求结果的状态码，类型为整数。

   基础规范：优先使用标准HTTP状态码（如200、404、500）。

   扩展规范：可在响应体中自定义业务错误码（如登录失败code: 1001），但需避免与HTTP状态码冲突。

   示例：{ "code": 200, "message": "请求成功", "data": {...} }

2. message 或 msg

   对请求结果的文字描述，用于提示或调试。

   设计原则：

   清晰明确，避免模糊表述（如“系统错误”）。

   不暴露系统内部细节（如数据库错误、文件路径）。

   多语言支持：可通过扩展字段实现（如message_en、message_zh）。

   示例：{ "code": 400, "message": "手机号格式不正确", "data": null }

3. data

   承载实际返回的数据，类型可为对象、数组或null。

   关键规则：

   不可省略：即使无数据也需返回null（如"data": null）。

   分页封装：分页信息需嵌套在data中，例如：{ "code": 200, "message": "成功", "data": { "list": [...], "page": 1, "total": 100 }}

1. 基础HTTP状态码

   必须遵循标准定义，常见场景如下：

   200 OK：请求成功。

   201 Created：资源创建成功（如POST请求）。

   400 Bad Request：客户端请求参数错误。

   401 Unauthorized：未授权（如Token失效）。

   403 Forbidden：权限不足。

   404 Not Found：资源不存在。

   500 Internal Server Error：服务器内部错误。

2. 自定义业务错误码

   设计目的：补充HTTP状态码的语义，快速定位业务问题。

   实现方式：在响应体中通过code字段返回，例如：

   登录失败：code: 1001

   参数缺失：code: 1002

   避免滥用200：禁止将所有错误返回200后通过code区分，这会干扰日志分析。

1. 基础错误结构

   { "code": 400, "message": "手机号格式不正确", "data": null }

2. 复杂错误反馈

   适用场景：表单校验、批量操作等需要多字段错误提示时。

   扩展字段：通过errors数组返回具体字段的错误信息，例如：{ "code": 400, "message": "参数校验失败", "errors": [ { "field": "phone", "message": "手机号格式不正确" }, { "field": "email", "message": "邮箱地址不能为空" } ], "data": null }

1. 一致性

   成功与失败响应的结构需完全一致，仅修改code和message的值。

   示例对比：

   成功响应：{ "code": 200, "message": "成功", "data": {...} }

   失败响应：{ "code": 404, "message": "资源不存在", "data": null }

2. 字段精简

   禁止返回调试信息、堆栈跟踪等非必要字段（测试环境除外）。

3. 分页数据封装

   分页参数（如page、total）需嵌套在data中，而非与code、message平级。

1. 成功响应

   { "code": 200, "message": "请求成功", "data": { "id": 1, "name": "张三" }}

2. 失败响应（资源不存在）

   { "code": 404, "message": "资源不存在", "data": null }

3. 复杂错误响应

   { "code": 400, "message": "参数校验失败", "errors": [ { "field": "username", "message": "用户名长度需大于6" } ], "data": null }

通过统一响应结构、合理使用状态码、设计清晰的错误信息，可显著提升API的易用性和可维护性。