RESTful 是 Web API 主流架构风格，核心思想是以资源为中心，使用 HTTP 方法表达动作。很多项目伪 REST，URL 写大量动词，方法滥用 GET/POST。本文系统讲解 REST 核心原则、URL 命名、HTTP 方法语义、状态码使用、统一返回体、分页、排序、嵌套资源、版本控制，附带正反案例、开发踩坑清单，适合团队接口规范制定、复习。
前言
REST 全称 Representational State Transfer（表述性状态转移），由 Roy Fielding 提出。REST 不是一个协议，是一套架构设计风格 ，基于 HTTP 协议特性。 REST 核心思想：一切皆资源，URL 代表资源，HTTP 方法代表对资源的操作动作。
反模式：
/getUser、/deleteOrder，URL 里面带动词，这不是 REST 风格。
一、REST 核心设计原则
-
资源使用名词，推荐复数 URL 描述资源集合，不要描述动作。
推荐
GET /users 获取用户列表
GET /users/100 获取id=100单个用户
POST /users 创建用户
PUT /users/100 全量更新用户
PATCH /users/100 局部更新用户字段
DELETE /users/100 删除用户错误示范
GET /getUserList
POST /createUser
DELETE /deleteUser -
正确使用 HTTP 方法，遵守语义、幂等、安全特性
方法 含义 幂等 安全 适用场景 GET 查询资源 是 是 只读查询，不修改数据 POST 新建资源 否 否 新增记录 PUT 全量替换资源 是 否 完整覆盖更新，不存在则新建 PATCH 局部更新 否 否 只更新部分字段 DELETE 删除资源 是 否 删除资源 -
无状态 每个请求包含全部信息，服务端不保存客户端会话状态；认证信息（Token）放在请求头。
-
资源可以嵌套（父子资源）
GET /users/100/orders 获取用户100的订单列表
POST /users/100/orders 为用户100创建订单
嵌套层级建议最多 2 层，不要无限嵌套。
二、URL 规范细节
-
全部小写，横线
-分隔单词，禁止下划线、驼峰；/user-address而不是/userAddress、/user_address -
根路径增加 api 前缀区分业务接口：
/api/users -
查询参数放 queryString，用于过滤、分页、排序
GET /api/users?page=1&size=10&status=1&sort=createTime,desc
三、HTTP 状态码合理使用
不要全部接口统一返回 200，业务错误放在 code 字段，这是很多项目的伪 REST。
- 查询成功：200 OK
- 创建资源成功：201 Created，响应头 Location 返回资源地址
- 删除成功无返回体：204 No Content
- 参数错误：400 Bad Request
- 未登录 / Token 无效：401 Unauthorized
- 权限不足：403 Forbidden
- 资源不存在：404 Not Found
- 请求方法不支持：405 Method Not Allowed
- 参数校验失败：422 Unprocessable Entity
- 服务异常：500 Internal Server Error
现实开发折中方案：很多团队仍然统一返回 200，业务自定义 code。面试时区分标准 REST 和企业落地折中方案。
四、统一返回体设计（企业落地最常用）
标准 REST 推荐直接返回资源实体；国内项目为方便前端，一般封装统一 JSON 结构。
{
"code": 200,
"msg": "success",
"data": {
"id": 100,
"name": "张三"
}
}- code：业务码，200 成功；4xxx 客户端业务错误；5xxx 服务异常
- msg：可读提示信息
- data：业务数据，查询返回实体 / 数组；删除成功可以为 null
分页返回示例：
{
"code":200,
"msg":"success",
"data":{
"records":[],
"total":100,
"current":1,
"size":10
}
}五、附加规范：版本控制、排序、过滤、搜索
- API 版本控制 （推荐路径版本）
/api/v1/users，新增不兼容接口升级 v2。不推荐 Header 放版本。 - 过滤：query 参数，
?status=1&gender=0 - 排序：
?sort=field,asc?sort=createTime,desc - 字段裁剪：按需返回字段
?fields=id,name
六、REST 常见误区 & 踩坑
- 所有接口只用 GET 和 POST，PUT/DELETE 不使用；
- URL 大量动词，
/api/updateUser； - GET 请求做数据修改操作（违反安全原则，缓存会误触发）；
- 幂等接口没有保证幂等，重试产生脏数据；
- 状态码滥用，全部返回 200，业务异常全部用自定义 code；
- 嵌套层级太深，可读性变差。
七、问答
Q1：RESTful 是什么？核心原则？
A：REST 是基于 HTTP 的资源导向架构风格。核心：一切是资源，URL 标识资源，HTTP 方法代表动作，无状态，合理使用状态码。
Q2：PUT 和 PATCH 区别？
A：PUT 全量替换资源；PATCH 局部更新部分字段。
Q3：幂等性是什么？哪些 HTTP 方法天然幂等？
A：多次请求，服务端结果和一次请求相同。GET、PUT、DELETE 天然幂等；POST 非幂等。
Q4：如何做 API 版本管理？
A：路径版本/api/v1/users，Header 版本，参数版本；项目推荐路径版本，简单直观。
结语
RESTful 接口设计的本质，是充分利用 HTTP 原生语义，让接口语义自描述。实际开发不必追求完全严格 REST（Richardson 成熟度模型 Level3），优先保证团队统一、前后端沟通简单。合理的接口规范，降低对接成本，方便使用 Apifox/Postman 调试。