如何标准化API的成功与错误响应？

本文目录导读：

1. 核心原则
2. 推荐的标准响应结构
3. 成功响应的标准化
4. 错误响应的标准化
5. 特殊场景处理
6. 最佳实践总结
7. 一个完整的代码示例（伪代码）

标准化API的成功与错误响应是提升系统可维护性、降低前后端协作成本的关键，目前业界最通用且成熟的规范是 JSON:API 或基于 RESTful 风格的自定义规范。

以下是推荐的标准化方案,结合了RFC 7807（Problem Details for HTTP APIs）和常见的最佳实践。

核心原则

1. 统一结构：无论是成功还是错误，响应体都遵循相同的顶层字段结构。
2. HTTP状态码 + 业务码：HTTP状态码表示传输层状态（如200, 400, 500），业务码（code）表示业务逻辑状态（如1000表示成功，2001表示用户不存在）。
3. 自描述性：错误信息要足够具体，能帮助调用方确定问题所在。

推荐的标准响应结构

采用一个通用的ApiResponse对象，包含四个关键字段：

字段名	类型	是否必须	说明
success	boolean	是	业务处理是否成功。true 或 false。
code	string/int	是	业务状态码，成功时固定（如"OK"或1000），失败时为具体错误码。
message	string	是	对本次响应的简短、人类可读的描述。
data	object/null	是	承载实际数据的容器，成功时必须包含数据；失败时为null或错误详情。
errors	array	推荐	（新增字段） 详细错误列表，用于表单验证等场景。

成功响应的标准化

HTTP状态码：200 OK、201 Created、204 No Content。

示例1：获取单个资源（200）

{
  "success": true,
  "code": "OK",
  "message": "用户信息查询成功",
  "data": {
    "id": 123,
    "name": "张三",
    "email": "zhangsan@example.com",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "errors": null
}

示例2：创建资源成功（201）

{
  "success": true,
  "code": "CREATED",
  "message": "订单创建成功",
  "data": {
    "order_id": "ORD-20241015-0001",
    "status": "pending"
  },
  "errors": null
}

示例3：列表查询（200）

建议在data中包含分页元信息，而非平铺。

{
  "success": true,
  "code": "OK",
  "message": "查询成功",
  "data": {
    "items": [
      { "id": 1, "title": "文章1" },
      { "id": 2, "title": "文章2" }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 58,
      "total_pages": 3
    }
  },
  "errors": null
}

错误响应的标准化

核心原则：区分系统级错误（如数据库连接失败）和业务级错误（如余额不足、参数校验失败）。

通用错误结构（遵循 RFC 7807 风格）

{
  "success": false,
  "code": "PARAM_INVALID",
  "message": "请求参数校验失败",
  "data": null,
  "errors": [
    {
      "field": "email",
      "type": "invalid_format",
      "message": "邮箱格式不正确"
    },
    {
      "field": "age",
      "type": "range_error",
      "message": "年龄必须在18-60之间"
    }
  ]
}

常见HTTP状态码与业务码映射

场景	HTTP状态码	业务码 (code)	示例 message
请求成功	200/201	OK / CREATED	处理成功
参数错误	400	PARAM_INVALID	请求参数验证失败
未授权	401	UNAUTHORIZED	令牌无效或已过期
无权限	403	FORBIDDEN	当前用户无操作权限
资源未找到	404	NOT_FOUND	用户ID 123 不存在
请求冲突	409	RESOURCE_CONFLICT	邮箱已被注册
依赖失败	422	UNPROCESSABLE_ENTITY	业务规则不满足（如余额不足）
请求频次超限	429	RATE_LIMIT_EXCEEDED	请求过于频繁，请稍后重试
服务器内部错误	500	INTERNAL_ERROR	服务器内部异常，请联系管理员
服务不可用	503	SERVICE_UNAVAILABLE	服务维护中

注意：永远不要将服务器内部异常栈（如Java StackTrace）暴露给客户端！使用通用message代替。

特殊场景处理

分页与列表

• 错误案例：把分页信息放在errors里。
• 正确做法：如上文，分页元数据放在data.pagination内。

文件上传

• 成功：返回文件URL和元数据。
• 失败：返回具体的字段错误，如file.too_large、type.unsupported。

异步操作（202 Accepted）

对于耗时操作,可以返回202 Accepted状态码：

{
  "success": true,
  "code": "ACCEPTED",
  "message": "任务已提交，正在处理",
  "data": {
    "task_id": "task_abc123",
    "status_url": "/tasks/task_abc123/status"
  },
  "errors": null
}

最佳实践总结

1. 一致性：整个API的所有端点必须遵循同一结构，不允许成功返回data，失败返回error这种不一致的设计。
2. 拒绝裸数组：永远不要在顶层直接返回一个数组 ，顶层必须是data对象。
3. 统一错误码管理：建立中心化的错误码字典（如枚举或常量类），避免散落在代码各处。
4. 国际化：message字段建议支持占位符，并预留多语言切换的能力（可通过Accept-Language头部或统一管理）。
5. 日志链路：在errors或根层级中，可以附加一个trace_id用于内部排障，但不向外暴露堆栈。
6. 框架集成：

• Spring Boot：使用@ControllerAdvice + ResponseEntityExceptionHandler 全局处理。
• Django：使用django-rest-framework的exception_handler + 自定义响应格式化。
• Node.js (Express)：使用中间件统一包装res.success()和res.fail()。

一个完整的代码示例（伪代码）

# Python / Flask 示例
def success_response(data=None, message="操作成功", code="OK", http_status=200):
    return {
        "success": True,
        "code": code,
        "message": message,
        "data": data,
        "errors": None
    }, http_status
def error_response(message="请求失败", code="ERROR", errors=None, http_status=400):
    if errors is None:
        errors = []
    return {
        "success": False,
        "code": code,
        "message": message,
        "data": None,
        "errors": errors
    }, http_status
# 使用
@app.route('/users', methods=['POST'])
def create_user():
    try:
        user = create_user_service(request.json)
        return success_response(data=user, message="用户创建成功", code="CREATED", http_status=201)
    except ValidationError as e:
        return error_response(message="参数校验失败", code="PARAM_INVALID", errors=e.errors, http_status=400)
    except Exception:
        return error_response(message="服务器内部错误", code="INTERNAL_ERROR", http_status=500)

通过以上标准化方案,你的API将具备高度的可预测性、可调试性和兼容性，能够很好地支持前端、移动端和第三方调用的需求。