好的 API 设计让前后端协作效率翻倍。从 URL 命名到状态码选择，从版本管理到文档生成，一套可落地的规范。

一、RESTful 的核心原则

  • 1.1 资源导向——URL 是名词而非动词
  • 1.2 HTTP 方法语义——GET / POST / PUT / DELETE / PATCH
  • 1.3 状态码的正确使用
  • 1.4 无状态——每个请求包含全部信息

二、URL 命名规范

  • 2.1 复数形式——/users 而非 /user
  • 2.2 层级关系——/users/{id}/orders
  • 2.3 避免深层嵌套——最多 3 层
  • 2.4 使用短线分隔——/user-addresses 而非 /user_addresses
  • 2.5 常见设计示例

三、HTTP 状态码的选择

  • 3.1 2xx——200 OK / 201 Created / 204 No Content
  • 3.2 3xx——301 Moved Permanently / 304 Not Modified
  • 3.3 4xx——400 Bad Request / 401 Unauthorized / 403 Forbidden / 404 Not Found / 409 Conflict / 422 Unprocessable Entity
  • 3.4 5xx——500 Internal Error / 502 Bad Gateway / 503 Service Unavailable
  • 3.5 状态码使用决策树

四、统一响应格式

  • 4.1 { code, message, data, timestamp, traceId }
  • 4.2 分页响应——{ data, total, pageNo, pageSize }
  • 4.3 错误码体系——模块编号 + 错误序号

五、API 版本管理

  • 5.1 URL 路径版本——/v1/users、/v2/users
  • 5.2 请求头版本——Accept: application/vnd.api+json;version=2
  • 5.3 查询参数版本——/users?version=2
  • 5.4 推荐路径版本——最直观

六、接口文档管理

  • 6.1 Swagger 3（OpenAPI 3）基本注解
  • 6.2 Knife4j——Swagger 的增强 UI
  • 6.3 Apifox / YApi——文档 + Mock + 测试
  • 6.4 文档先行 vs 代码先行

七、总结

  • RESTful 不是银弹——复杂业务操作可适度使用 RPC 风格
  • 好的 API 规范应该让调用方”不需要看文档”