1. URL 命名规范#

建议：

• 全部小写
• 单词之间用中划线 ”-”
• 使用名词，不用动词
• 不要在 URL 中出现文件扩展名

示例：

• /user-profiles
• /order-items

2. 请求方法规范#

GET
用于查询，不应修改数据。

1
GET /users/123

POST
用于新增资源。

1
POST /users
2
Content-Type: application/json
3
{
4
  "name": "Tom",
5
  "email": "tom@example.com"
6
}

PUT
用于完整更新。通常是“把整个资源替换掉”。

1
PUT /users/123
2
{
3
  "name": "Tom",
4
  "email": "new@example.com",
5
  "age": 20
6
}

PATCH
用于部分更新。

1
PATCH /users/123
2
{
3
  "email": "new@example.com"
4
}

DELETE
用于删除资源。

1
DELETE /users/123

3. 状态码规范#

2xx 成功

• 200 OK：查询成功、更新成功
• 201 Created：创建成功
• 204 No Content：删除成功且无返回体

4xx 客户端错误

• 400 Bad Request：请求参数错误
• 401 Unauthorized：未认证
• 403 Forbidden：已认证但无权限
• 404 Not Found：资源不存在
• 409 Conflict：资源冲突
• 422 Unprocessable Entity：参数格式对，但业务校验失败

5xx 服务端错误

• 500 Internal Server Error：服务器内部错误
• 502 Bad Gateway
• 503 Service Unavailable

4.返回数据规范#

通常返回 JSON，或者更 REST 一点，直接返回资源本身。

5. 查询、过滤、分页、排序#

这些一般通过 query 参数 实现。

1
GET /users?status=active&page=1&page_size=20&sort=-created_at

6. 版本控制#

常见方式：

1.放 URL 中

1
/api/v1/users
2
/api/v2/users

这是最常见、最直观的。

2.放请求头中

1
Accept: application/vnd.company.v1+json

更 REST，但实现和使用都更复杂。

通常中小团队直接用 URL 版本号即可。

7. 幂等性#

幂等性指：同样的请求调用一次和调用多次，结果一致。

一般理解：

• GET、PUT：幂等
• DELETE：通常设计为幂等
• POST：通常不幂等

例如：

• 连续执行多次 GET /users/1，结果一样
• 连续执行多次 PUT /users/1 更新为同一个内容，结果一样
• 连续执行多次 DELETE /users/1，第一次删除成功，后面可以返回 404 或 204，但资源状态应一致