RESTful API 设计:容易被忽略的细节
目录
资源命名使用名词复数
URL 应表示资源,而非操作。推荐使用名词复数:
GET /users # 获取用户列表
GET /users/123 # 获取单个用户
POST /users # 创建用户
PUT /users/123 # 全量更新
PATCH /users/123 # 部分更新
DELETE /users/123 # 删除用户
正确使用 HTTP 状态码
状态码是 API 语义的一部分,恰当地使用能让调用方更容易处理:
200 OK—— 请求成功201 Created—— 资源创建成功,响应头应包含Location204 No Content—— 成功但无响应体,常见于删除操作400 Bad Request—— 请求参数有误401 Unauthorized—— 未认证403 Forbidden—— 已认证但无权限404 Not Found—— 资源不存在429 Too Many Requests—— 触发限流500 Internal Server Error—— 服务端内部错误
版本管理
将版本放入 URL 路径是最直观的做法:
/api/v1/users
/api/v2/users
分页设计
对于列表接口,推荐统一的分页响应结构:
| |
小结
良好的 API 设计应当一致、可预测、自描述。约定优于配置,一旦确立规范就应在整个系统内保持一致。