服务端 API 设计规范

相关错误码的设计内容，参考： 错误码规范 MD 指南。

1. 设计目标

• 统一接口风格
• 提高可读性与可维护性
• 降低前后端沟通成本
• 支持长期演进
• 保证安全与稳定

2. 基本原则

• RESTful 风格
• 资源导向（名词，不是动词）
• 接口幂等
• 向后兼容
• 统一响应格式
• 明确错误码
• 文档即接口

3. URL 规范

3.1 命名规则

• 小写
• 复数名词
• 使用 - 分隔

/api/users
/api/orders
/api/order-items

禁止：

/api/getUser
/api/createOrder

3.2 资源层级

/api/users/{userId}/orders
/api/orders/{orderId}/items

4. HTTP 方法

操作	方法
查询	GET
新建	POST
更新	PUT / PATCH
删除	DELETE

• PUT：整体更新
• PATCH：部分更新

5. API 版本管理

必须有版本号：

/api/v1/users
/api/v2/orders

6. 请求参数规范

6.1 Path 参数

• 用于资源标识
• 必须校验合法性

6.2 Query 参数

• 用于过滤、分页、排序

?page=1&pageSize=20&sort=created_at,desc

6.3 Body 参数

• JSON 格式
• 不超过 3 层嵌套
• 必须校验

7. 统一响应格式

成功

{
  "code": 0,
  "message": "success",
  "data": {}
}

失败

{
  "code": 20001,
  "message": "用户不存在",
  "data": null
}

字段说明：

字段	含义
code	业务状态码
message	提示信息
data	返回数据

8. 错误码规范

• 一个错误码对应一个业务语义
• 分模块管理
• 不直接返回异常堆栈
• 错误码文档化

示例：

10000 系统错误
20001 用户不存在
30001 订单不存在
40001 无权限

9. HTTP 状态码规范

场景	HTTP
成功	200 / 201
参数错误	400
未登录	401
无权限	403
不存在	404
限流	429
系统错误	500

10. 分页规范

请求：

GET /api/users?page=1&pageSize=20

响应：

{
  "list": [],
  "page": 1,
  "pageSize": 20,
  "total": 100
}

11. 排序与过滤

GET /api/orders?status=paid&sort=created_at,desc

规则：

• sort=字段,asc|desc
• filter 使用 query 参数

12. 幂等性

适用接口：

• 下单
• 支付
• 表单提交

方案：

Header: Idempotency-Key

13. 认证与授权

• Token / JWT / OAuth2
• Header：

Authorization: Bearer token

• RBAC 权限控制

14. 安全规范

• HTTPS
• 参数校验
• 防 SQL 注入 / XSS / CSRF
• 限流
• 防重放

15. 文件上传

POST /api/files/upload
Content-Type: multipart/form-data

返回：

{
  "url": "https://xxx.com/file.png"
}

16. 批量操作

POST /api/users/batch

Body：

{
  "ids": [1, 2, 3]
}

17. 接口变更规范

• 不删除字段
• 新增字段向后兼容
• 废弃接口标记 deprecated
• 破坏性变更升级版本号

18. 接口文档规范

必须包含：

• URL
• Method
• 参数说明
• 示例请求
• 示例响应
• 错误码说明

推荐工具：

• Swagger / OpenAPI
• Apifox / Postman

19. 日志与追踪

• 每个请求生成 requestId

• 日志包含：

  • requestId
  • userId
  • api
  • error

20. 性能规范

• 单接口响应 < 200ms
• 避免 N+1 查询
• 返回必要字段
• 支持缓存

21. 禁止行为

❌ 动词型 URL
❌ 无版本号 API
❌ 返回格式不统一
❌ 无错误码
❌ 无文档接口
❌ 不校验参数
❌ 直接抛异常

22. 推荐工具

• Swagger / OpenAPI
• JWT
• API Gateway
• Nginx 限流
• SonarQube