REST API 设计十条军规

设计 API 是后端最频繁的决策点。这几条原则是我从无数次的改接口中总结出来的。

1. 用名词，不用动词

✅ GET  /users/{id}
❌ GET  /getUser?id=1

2. 资源层级要反映归属

GET /users/{uid}/posts/{pid}

3. HTTP 方法语义要准

4. 状态码要有意义

• 200 成功、201 创建、204 无内容
• 400 参数错、401 未登录、403 无权限、404 不存在
• 500 服务端错误、503 依赖不可用

5. 统一错误结构

{ "error": { "code": "USER_NOT_FOUND", "message": "用户不存在" } }

6. 分页是标配

{ "items": [...], "page": 1, "pageSize": 20, "total": 137 }

7~10. 其他要点

1. 版本号进 URL（/v1/）
2. 时间统一 ISO 8601
3. 敏感字段永远不返回明文
4. 文档和代码同步更新

结论

API 设计没有银弹，但一致的命名 + 正确的状态码 + 清晰的错误就能解决 80% 的协作问题。