REST（Representational State Transfer，表述性状态转移）是一套架构风格，不是协议、不是标准，RESTful 就是遵循这套风格设计出来的 API。核心思想：把一切资源作为核心，通过 HTTP 语义来操作资源。
一句话概括：用 URL 定位资源，用 HTTP Method 描述动作，用 HTTP Status Code 表达结果状态
1. 资源（Resource）为核心，名词优先，少用动词
URL 代表资源，尽量使用名词复数，不要把操作动作写在路径里。 ✅ 好：
GET /users // 获取用户列表
GET /users/123 // 获取id=123的单个用户
POST /users // 新建用户
PUT /users/123 // 全量更新用户
PATCH /users/123 // 局部更新用户
DELETE /users/123 // 删除用户
❌ 不好（URL 里放动词）：
/getUser /addUser /updateUser /deleteUser
关联资源嵌套（表达从属关系）：
GET /users/123/orders // 123号用户的订单列表
GET /users/123/orders/456
2. 正确使用 HTTP Method（方法语义）
幂等：同一个请求执行多次，效果和执行一次一样。
3. 使用 HTTP 状态码表达结果，不要全部返回 200
状态码用来告诉客户端本次请求结果，业务错误信息放返回体。 常用：
200 OK：成功（GET/PUT/PATCH）201 Created：POST 创建成功，建议带上 Location 指向新资源地址204 No Content：成功但无返回内容（常用 DELETE）400 Bad Request：参数错误、请求格式不对401 Unauthorized：未登录 / 认证失败403 Forbidden：已登录，但没有权限404 Not Found：资源不存在409 Conflict：资源冲突（比如唯一键重复）422 Unprocessable Entity：参数格式对，但业务校验不通过500 Internal Server Error：服务端异常
❌ 反模式：永远返回 200，靠 code: -1 判断失败。
4. 统一资源表述（Representation），推荐 JSON
前后端默认用 JSON；
通过
Content-Type、Accept协商格式；返回结构尽量统一，例如：
{
"code": 200,
"data": {...},
"message": "success"
}
注意：REST 本身不强制这个包装结构，很多极简 REST 直接返回资源本体；但业务项目一般统一包装方便前端处理。
5. 无状态（Stateless）【非常核心】
每个请求必须自带所有需要的信息，服务器不保存客户端会话状态。
服务端不存 session；认证信息放在请求头（Token / JWT）
每一次请求都是独立的 优点：容易水平扩展、负载均衡、集群部署； 代价：每次请求都要携带身份凭证。
6. 可缓存（Cacheable）
GET 请求资源应该支持缓存，通过 HTTP 缓存头控制： Cache-Control、ETag、Last-Modified 客户端可以缓存资源，减少重复请求。
7. 分层系统（Layered System）
客户端不知道是直连后端，还是经过网关、负载均衡、缓存代理； 中间层（网关、Nginx）可以做鉴权、限流、缓存，不改动客户端。
8. HATEOAS（可选，REST 最高约束，实际很少严格落地）
Hypermedia As The Engine Of Application State，超媒体驱动状态。 返回资源时附带相关操作链接，客户端不需要硬编码 URL：
{
"id": 123,
"name": "张三",
"_links": {
"self": "/users/123",
"orders": "/users/123/orders",
"delete": "/users/123"
}
}
绝大多数企业接口只做到 “REST-like”，不会严格实现 HATEOAS。
配套的工程实践约定（行业通用，不属于 REST 原始约束）
版本控制：放在路径或者 Header
/v1/users（最常用）
过滤、分页、排序用 query 参数，不要写进路径
/users?page=1&size=20&sort=createTime,desc&status=active
命名：小写 + 短横线 kebab-case，不用下划线、驼峰
/user-address而不是/userAddress、/user_address
资源集合分页、过滤、搜索都用
?参数
区分：RESTful ≠ HTTP CRUD
REST 是架构风格，CRUD 只是最常见的落地形式； 很多复杂业务动作（审批、下单）不好硬套 CRUD，这时可以：
方案 A：设计子资源
/orders/100/approve+ POST方案 B：接受部分接口是 RPC 风格（行业妥协，不要强行硬凹 REST）
简单总结
REST 五大核心约束（原始论文）：
资源标识（URL 定位资源）
通过资源表述操作资源
自描述消息（Header、状态码说明请求）
无状态
超媒体驱动（HATEOAS）
本文原创作者：易君召，详见：https://www.yijunzhao.cn/authors/yijunzhao，转载请注明出处。
原文链接
欢迎访问 小易撩挨踢