RESTful API 设计的 7 个黄金法则

法则一：使用名词作为资源名

# ❌ 动词在 URL 中
GET /api/getUsers
POST /api/createUser

# ✅ 名词表示资源
GET /api/users
POST /api/users

法则二：正确使用 HTTP 方法

方法	用途	幂等性
GET	获取资源	是
POST	创建资源	否
PUT	更新资源（全量）	是
PATCH	更新资源（部分）	是
DELETE	删除资源	是

法则三：使用复数名词

# ✅ 一致性好
/users
/articles
/comments

法则四：嵌套资源表达关系

# 获取用户的所有文章
GET /users/123/articles

# 获取文章的评论
GET /articles/456/comments

法则五：使用查询参数过滤和分页

# 过滤
GET /articles?category=tech&status=published

# 分页
GET /articles?page=2&limit=20

# 排序
GET /articles?sort=-created_at

法则六：返回合适的状态码

• 200：成功
• 201：创建成功
• 400：请求错误
• 401：未授权
• 403：禁止访问
• 404：资源不存在
• 500：服务器错误

法则七：版本控制

# URL 版本（推荐）
GET /api/v1/users

# 或 Header 版本
Accept: application/vnd.api.v1+json

结语

好的 API 设计让开发者用得舒服，减少沟通成本。