REST API 设计与统一返回体规范

路径与资源命名

• 使用名词复数形式表示资源，例如 /users、/orders
• 使用层级关系表达资源从属关系，例如 /users/{id}/orders
• 避免在路径中加入动词，动作由 HTTP 方法表达

HTTP 方法约定

• GET：查询资源或资源集合
• POST：创建资源或触发非幂等操作
• PUT：整体更新资源
• PATCH：部分更新资源
• DELETE：删除资源

状态码使用

• 200：请求成功，返回正常数据
• 201：资源创建成功
• 204：请求成功但无返回体
• 400：请求参数错误或校验失败
• 401：未认证
• 403：无权限
• 404：资源不存在
• 409：资源冲突
• 500：服务器内部错误

统一返回体结构

• 统一返回 JSON 结构：

{
  "code": "0",
  "msg": "操作成功",
  "data": {}
}

• code：业务状态码，字符串类型
• msg：对用户或调用方友好的提示信息
• data：业务数据载体，无数据时可以为 null 或省略

分页、排序与过滤约定

• 分页参数统一为 page 与 size，从一开始计数
• 排序参数统一为 sort，格式为 field,asc 或 field,desc
• 过滤条件通过查询参数表达，命名清晰表达字段含义

幂等性与安全性

• 对外暴露的写操作接口在设计时优先考虑幂等性
• 接口入参与出参对象中不返回敏感字段
• 在接口层统一校验权限与认证信息