API设计需规范状态码、数据结构和错误信息，确保响应格式统一，明确字段含义，提供完整文档说明，支持版本兼容，保障调用方解析效率与
API 设计返回规范
通用返回结构
所有 API 响应均采用统一的 JSON 结构，包含以下字段：
| 字段名 | 类型 | 必填 | 描述 |
|---|---|---|---|
status |
Number | 是 | HTTP 状态码（如 200、400、500） |
message |
String | 是 | 状态描述（如 “OK”、”Bad Request”） |
data |
Object | 否 | 业务数据（成功时返回） |
errorCode |
String | 否 | 业务错误码（失败时返回，如 “PARAMS_ERROR”） |
traceId |
String | 否 | 请求追踪 ID（用于分布式链路追踪） |
典型场景返回示例
成功响应（带数据）
{
"status": 200,
"message": "OK",
"data": {
"userId": 123,
"username": "example_user"
},
"traceId": "abc-123-xyz"
}
客户端错误
{
"status": 400,
"message": "Invalid parameters",
"errorCode": "PARAMS_ERROR",
"traceId": "abc-123-xyz"
}
服务端错误
{
"status": 500,
"message": "Internal server error",
"errorCode": "SERVER_ERROR",
"traceId": "abc-123-xyz"
}
分页数据返回规范
适用于列表查询接口,需包含分页元信息：
| 字段名 | 类型 | 必填 | 描述 |
|---|---|---|---|
total |
Number | 是 | 总记录数 |
pageSize |
Number | 是 | 每页大小 |
pageNum |
Number | 是 | 当前页码 |
list |
Array | 是 | 当前页数据数组 |
示例：
{
"status": 200,
"message": "OK",
"data": {
"total": 100,
"pageSize": 10,
"pageNum": 2,
"list": [/* 数据项 */]
}
}
复杂嵌套数据结构
对于多层嵌套数据,建议采用以下规范：
| 字段名 | 类型 | 必填 | 描述 |
|---|---|---|---|
results |
Array | 是 | 主数据数组 |
metadata |
Object | 否 | 附加元信息（如统计信息、关联数据） |
示例：
{
"status": 200,
"message": "OK",
"data": {
"results": [/* 主数据项 */],
"metadata": {
"totalComments": 50,
"relatedTopics": ["topic1", "topic2"]
}
}
}
文件下载特殊场景
对于文件下载类接口,需通过 HTTP Header 传递元信息：
| Header 属性 | 描述 |
|---|---|
Content-Type |
根据文件类型设置（如 application/pdf） |
Content-Disposition |
控制浏览器行为（如 attachment; filename="file.pdf"） |
Content-Length |
文件大小（单位：字节） |
X-File-Checksum |
文件校验和（如 MD5） |
相关问题与解答
Q1：如何区分业务错误和系统错误？
A：通过 errorCode 字段区分：
- 业务错误：
errorCode为预定义的业务逻辑错误（如 “USER_NOT_FOUND”） - 系统错误：
errorCode为通用错误（如 “SERVER_ERROR”），且日志中会记录详细堆栈信息
Q2：分页接口是否需要返回总页数？
A：不建议直接返回总页数，原因如下：
- 总页数 =
total / pageSize，前端可自行计算 total可能动态变化（如数据被删除）- 避免接口频繁修改（如 pageSize 调整时需同步修改总页数
小伙伴们，上文介绍了“api 设计 返回”的内容，你了解清楚吗？希望对你有所帮助，任何问题可以给我留言，让我们下期再见吧。
【版权声明】：本站所有内容均来自网络，若无意侵犯到您的权利，请及时与我们联系将尽快删除相关内容!
