RESTful API 设计规范：资源、状态码与版本管理
前后端分离的项目里，接口设计直接决定协作效率。RESTful 不是必须遵守的法律，但它是一套经过验证的约定，按它设计，团队沟通成本最低。这篇讲核心几个点。
资源用名词，不用动词
REST 的核心思想是把数据当作"资源"，URL 只描述资源，动作交给 HTTP 方法：
| 方法 | URL | 含义 |
|---|---|---|
| GET | /api/users | 获取用户列表 |
| GET | /api/users/12 | 获取单个用户 |
| POST | /api/users | 创建用户 |
| PUT | /api/users/12 | 整体更新 |
| PATCH | /api/users/12 | 部分更新 |
| DELETE | /api/users/12 | 删除用户 |
常见的错误写法是 /api/getUser、/api/deleteUser。方法已经表达了动作，URL 里再放动词就重复了。
集合用复数，嵌套别太深
资源集合统一用复数：/api/users 而不是 /api/user。嵌套关系最多两层：
/api/users/12/orders # 用户的订单
/api/orders/5/items # 订单的商品超过两层说明资源划分有问题，考虑把深层资源独立出来。
状态码要表达清楚
接口返回的 HTTP 状态码直接说明结果，前端不用猜：
- 200：成功；201：创建成功（POST 用）；
- 400：参数错误；401：未登录；403：无权限；404：资源不存在；
- 422：业务校验不通过（比如邮箱格式错）；
- 500：服务器内部错误。
错误时响应体里给人类可读的信息：
{
"code": 422,
"message": "邮箱格式不正确",
"errors": {"email": ["格式错误"]}
}分页、过滤、排序
列表接口一律分页，用统一的查询参数：
GET /api/users?page=2&per_page=20&status=active&sort=-created_at响应里带上分页信息，前端才好做翻页：
{
"data": [...],
"pagination": {"page": 2, "per_page": 20, "total": 156}
}版本管理
接口迟早要变。推荐把版本放进 URL：/api/v1/users、/api/v2/users。旧版本保留一段时间，给客户端迁移时间，不要直接改掉旧接口让线上应用崩掉。
安全底线
接口设计得再规范，安全不过关也白搭：所有写操作要校验权限；对外接口做限流；敏感字段（密码、token）永远不进响应体；输入一律校验长度和类型。RESTful 解决的是"怎么组织"，安全是另一条不能省的红线。