API 设计规范：RESTful 风格的最佳实践指南

前言

一个好的 API 设计，能让前后端协作效率翻倍；一个烂的 API，能让所有人都痛苦不堪。本文总结 RESTful API 设计的最佳实践，帮你写出规范、好用的接口。

一、URL 设计

1. 用名词，不用动词

# 好的
GET    /users        # 获取用户列表
POST   /users        # 创建用户
GET    /users/123    # 获取单个用户
PUT    /users/123    # 更新用户
DELETE /users/123    # 删除用户

# 不好的
GET    /getUsers
POST   /createUser
GET    /getUserById?id=123

2. 层级要清晰

# 获取某篇文章的评论
GET /users/123/articles/456/comments

3. 用复数名词

# 好的
/users

# 不好的
/user

二、HTTP 方法语义

方法	语义	幂等	安全
GET	获取资源	是	是
POST	创建资源	否	否
PUT	更新完整资源	是	否
PATCH	更新部分资源	否	否
DELETE	删除资源	是	否

幂等：同一个请求发多次，结果一样。
安全：请求不会修改服务器数据。

三、HTTP 状态码

200 OK                # 成功
201 Created           # 创建成功
204 No Content        # 删除成功，无返回内容

400 Bad Request       # 参数错误
401 Unauthorized      # 未登录
403 Forbidden         # 无权限
404 Not Found         # 资源不存在
429 Too Many Requests # 请求太频繁

500 Internal Server Error # 服务器错误

四、统一响应格式

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 123,
    "name": "张三"
  }
}

列表响应

{
  "code": 0,
  "message": "success",
  "data": {
    "list": [...],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}

错误响应

{
  "code": 10001,
  "message": "用户名或密码错误",
  "data": null
}

五、参数设计

1. 查询参数用 query string

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

2. 创建/更新用 body

POST /users
{
  "name": "张三",
  "email": "zhangsan@example.com"
}

3. 路径参数用 path

GET /users/123/articles/456

六、分页、排序、过滤

# 分页
GET /users?page=1&page_size=20

# 排序
GET /users?sort=created_at&order=desc

# 过滤
GET /users?status=active&role=admin

七、版本控制

API 要加版本号，方便升级不影响老用户。

# 在 URL 里加版本
/api/v1/users
/api/v2/users

# 或者在 Header 里加版本
Accept: application/vnd.myapi.v1+json

八、认证与授权

# 请求头带 Token
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

不要把 token 放在 URL 里，会泄露。

九、接口文档

好的 API 一定要有文档：

• Swagger / OpenAPI：自动生成接口文档
• Postman：方便调试和分享
• 示例：每个接口都要有请求和响应示例

十、常见坑

1. GET 请求带 body：不规范，浏览器和代理可能会忽略
2. 状态码乱用：别什么错都返回 200
3. 返回格式不统一：有的接口直接返回数据，有的包一层 code
4. 命名不规范：一会儿驼峰，一会儿下划线
5. 接口粒度太粗：一个接口干所有事，灵活性很差

总结

RESTful API 设计的核心思路：

1. URL 用名词，用 HTTP 方法表达操作
2. 状态码要正确，别什么都返回 200
3. 响应格式统一，成功失败都一个结构
4. 参数位置要合理，查询用 query，操作用 body
5. 一定要有文档，不然没人会用你的接口

掌握这些，你的 API 设计水平就能超过 80% 的后端开发者了。