响应结构应包含 status/code、message/msg、data 三个字段。1. status 或 code 表示请求结果的状态码；2. message 或 msg 描述状态，用于提示或调试；3. data 包含真正的数据内容。合理使用状态码应以标准 http 状态码为基础，如 200 表示成功，404 表示资源不存在，401 表示未授权等，同时可在响应体中加入自定义业务错误码，如登录失败 code: 1001，参数错误 code: 1002，避免所有错误都返回 200。设计通用错误信息时要清晰明确，不模糊也不暴露系统细节，并可扩展支持多语言或多字段错误反馈。保持响应结构一致性，无论成功或失败，data 字段可以为空但不能省略，不返回多余字段，分页信息可单独封装在 data 内部。
在开发JSON API的时候，规范的数据返回结构和状态码不仅能提升接口的可读性，还能让前后端协作更顺畅。一个清晰、统一的响应格式能帮助开发者快速定位问题，减少沟通成本。
响应结构应该包含哪些字段？
一个标准化的JSON API响应通常包括以下几个关键字段：
-
status或code：表示请求结果的状态码，通常是整数 -
message或msg：对当前状态的描述，用于提示或调试 -
data：真正的数据内容，可以是对象、数组或空值
举个例子，一个常见的成功响应可能是这样的：
{
"code": 200,
"message": "请求成功",
"data": {
"id": 1,
"name": "张三"
}
}对于失败的情况，也保持同样的结构，只是改变 code 和 message 的值即可：
{
"code": 404,
"message": "资源不存在",
"data": null
}这样前后端都很容易处理，也方便统一封装逻辑。
状态码该怎么用才合理？
HTTP状态码本身已经定义了一套标准，但实际开发中往往需要结合业务逻辑自定义错误码。这里有几个建议：
- 使用标准HTTP状态码作为基础：比如200表示成功，404表示资源不存在，401表示未授权等
-
自定义业务错误码放在响应体中：例如登录失败返回
code: 1001，参数错误返回code: 1002 -
避免滥用200：有些开发习惯把所有错误都返回200，再靠
code字段判断，这会让日志分析和监控变得困难
常见状态码参考：
- 200 OK：请求成功
- 201 Created：资源创建成功（如POST新增）
- 400 Bad Request：客户端发送的请求有误
- 401 Unauthorized：身份验证失败
- 403 Forbidden：权限不足
- 404 Not Found：资源不存在
- 500 Internal Server Error：服务器内部错误
如何设计通用的错误信息？
错误信息要清晰明确，不能太模糊也不能暴露太多系统细节。比如不要写“系统出错”，而应该写“用户ID不能为空”或者“手机号格式不正确”。
一般错误响应结构如下：
{
"code": 400,
"message": "手机号格式不正确",
"data": null
}如果需要支持多语言或详细错误字段，可以扩展成这样：
{
"code": 400,
"message": "参数校验失败",
"errors": [
{ "field": "phone", "message": "手机号格式不正确" },
{ "field": "email", "message": "邮箱地址不能为空" }
],
"data": null
}这种方式更适合复杂表单提交或批量操作时的错误反馈。
小细节别忽略
- 保持一致性：无论成功还是失败，结构尽量统一，前端更容易解析
- data字段可以为空：当没有数据返回时，设为null而不是省略这个字段
- 不要返回多余字段：比如debug信息、堆栈信息等，除非是测试环境
-
分页数据单独封装：可以把分页信息放在data里，比如
{ data: [...], page: 1, total: 100 }
基本上就这些，规范不一定非要复杂，但统一和清晰是关键。
