RESTful API 设计最佳实践

核心原则

1. 使用正确的 HTTP 方法

• GET：获取资源
• POST：创建资源
• PUT：更新资源（完整替换）
• PATCH：部分更新
• DELETE：删除资源

2. 资源命名规范

# ✅ 好
GET /users
GET /users/123
POST /users

# ❌ 不好
GET /getUsers
POST /createUser

规则：

• 使用名词，不用动词
• 复数形式表示集合
• 小写字母，连字符分隔

状态码使用

状态码	含义	使用场景
200	OK	成功获取/更新
201	Created	资源创建成功
204	No Content	删除成功
400	Bad Request	请求参数错误
401	Unauthorized	未认证
403	Forbidden	无权限
404	Not Found	资源不存在
500	Server Error	服务器错误

版本控制

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

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

响应格式

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123,
    "name": "John"
  },
  "timestamp": 1703275200
}

分页与过滤

GET /users?page=1&limit=20&sort=-created_at
GET /users?status=active&role=admin

好的 API 设计让开发者爱不释手！