06.1.1.1 REST 资源建模与 HTTP 语义
所属:全栈开发面试题库 / 06 后端框架与工程实践 / 06.1 通用后端工程 / 06.1.1 API 设计与契约
本节要解决的问题
- 业务对象如何映射成 URL 上的资源?
- HTTP 方法与状态码各自表达什么语义?
- 路径、查询参数、响应结构如何保持一致?
06.1.1.1-001 RESTful API 如何做资源建模?
一句话结论
把业务领域中的名词抽象成资源(集合 + 单项),URL 只表达资源标识,动作用 HTTP 方法表达,不把动作写进路径。
概念解释
REST(Representational State Transfer,表述性状态转移)的核心是:服务器把资源的表述(JSON/XML)返回给客户端,客户端通过表述上的链接和方法转移状态。资源是名词,例如订单、用户、商品;动作是动词,例如创建、读取、更新、删除。
原理流程
- 从领域模型中识别实体:订单
orders、订单项order-items、用户users。 - 集合用复数路径:
/orders;单项用标识:/orders/{id}。 - 动作交给 HTTP 方法:
GET读取、POST创建、PUT/PATCH更新、DELETE删除。 - 关联资源通过路径层级表达:
/orders/{id}/items。
示例
GET /orders?status=paid&page=2 # 订单集合
GET /orders/1001 # 单个订单
POST /orders # 创建订单
PATCH /orders/1001 # 局部更新订单
DELETE /orders/1001 # 删除订单
常见误区
- 把 RPC 动作写进 URL:
/orders/1001/cancel不是典型 REST 风格;取消可建模为状态迁移,用PATCH修改status,或在确有业务动作语义时接受 POST 子资源。 - 集合用单数
/order或中英文混用,破坏路径一致性。
追问
- 什么时候允许路径里出现动作?当操作无法映射为资源状态变更(如导出报表、发起审批流)时,可使用动词子资源或任务资源,例如
/reports/export,但要在团队规范内统一。 - 资源建模和数据库表一一对应吗?不必须;面向 API 的资源可以是聚合视图,与内部表结构解耦。
06.1.1.1-002 HTTP 方法与资源动作怎么对应?
一句话结论
GET 读取、POST 创建/非幂等处理、PUT 全量替换、PATCH 局部更新、DELETE 删除;方法语义必须与服务端行为一致。
概念解释
HTTP 方法在 HTTP 规范中带有固定语义,包括是否安全(不改变服务器状态)、是否幂等(多次调用结果相同)、是否可缓存。客户端、网关、缓存和代理都依赖这些语义做行为推断。
对比
| 方法 | 语义 | 安全 | 幂等 | 典型用途 |
|---|---|---|---|---|
| GET | 获取资源表述 | 是 | 是 | 查询集合/单项 |
| POST | 提交处理请求 | 否 | 否 | 创建资源、触发动作 |
| PUT | 全量替换资源 | 否 | 是 | 整体覆盖更新 |
| PATCH | 局部更新 | 否 | 否(通常) | 字段级变更 |
| DELETE | 删除资源 | 否 | 是 | 删除单项 |
常见误区
- 用
GET做创建或修改:会被浏览器预取、CDN 缓存、日志记录触发,造成副作用。 - 用
POST代替所有写操作:失去 PUT/DELETE 的幂等语义,缓存与重试行为不可预测。
追问
- POST 一定不幂等吗?HTTP 语义上 POST 不保证幂等;业务上可以配合幂等键做到重复提交结果一致,但方法本身仍按非幂等对待。
- PATCH 一定不幂等吗?常见实现是局部合并,重复提交相同补丁结果通常一致,但规范未声明幂等,设计时不要依赖这一点。
06.1.1.1-003 PUT 与 PATCH 的区别是什么?
一句话结论
PUT 用客户端提供的完整表示替换目标资源;PATCH 只提交一组针对资源的局部变更指令。
概念解释
PUT 的请求体是资源的完整新状态,服务端据此整体替换;缺失字段通常视为置空或按规则处理。PATCH 的请求体是差异集合(JSON Patch 或 JSON Merge Patch),只描述要改的字段。
示例
# PATCH:只改状态
PATCH /orders/1001
{ "status": "cancelled" }
# PUT:提交完整订单表示
PUT /orders/1001
{ "id": 1001, "status": "cancelled", "amount": 99.00, "items": [ ... ] }
常见误区
- PUT 只传要改的字段:与全量替换语义冲突,未传字段可能被清空。
- 把 PATCH 当 PUT 用:服务端按整体覆盖处理,局部更新语义丢失。
追问
- 新建资源能否用 PUT?可以:客户端指定资源标识时,
PUT /orders/1001可用于 upsert,但前提是标识由客户端决定。 - JSON Patch 与 Merge Patch 怎么选?JSON Patch(RFC 6902)用操作数组精确改路径;Merge Patch(RFC 7386)用合并对象表达变更,实现更简单,复杂删除语义受限。
06.1.1.1-004 常用 HTTP 状态码语义如何选用?
一句话结论
状态码表达结果类别:2xx 成功、3xx 重定向、4xx 客户端错误、5xx 服务端错误;在类别内按精确语义选择,不要一律返回 200 或 500。
概念解释
状态码是机器可读的结果分类,客户端可以按类别决定重试、提示或告警。4xx 表示请求问题,不应自动重试(除 429);5xx 表示服务端瞬时问题,可谨慎重试。
对比
| 状态码 | 含义 | 典型场景 |
|---|---|---|
| 200 | 请求成功 | 查询成功、更新成功 |
| 201 | 已创建 | POST 创建资源成功,Location 指向新资源 |
| 204 | 无内容 | DELETE 成功、无返回体 |
| 301/302 | 永久/临时重定向 | 资源迁移、登录跳转 |
| 304 | 未修改 | 条件请求缓存命中 |
| 400 | 请求格式错误 | 报文无法解析 |
| 401 | 未认证 | 缺少/无效凭证 |
| 403 | 已认证但禁止 | 有身份但无权限 |
| 404 | 资源不存在 | 标识不存在或无权查看(防枚举) |
| 409 | 状态冲突 | 版本冲突、唯一键冲突 |
| 422 | 语义错误 | 格式合法但业务校验不通过 |
| 429 | 限流 | 触发速率限制 |
| 500 | 服务端内部错误 | 未捕获异常 |
| 503 | 服务不可用 | 超载、维护中 |
常见误区
- 业务失败也返回 200,错误放在 body 的 code 里:客户端无法按状态码类别处理,网关/监控也无法按 4xx/5xx 统计。
- 403 与 401 混用:401 是「没登录/凭证无效」,403 是「登录了但没权限」。
追问
- 404 与 403 在防枚举时怎么选?对无权访问的资源,可统一返回 404,避免泄露资源是否存在。
- 201 响应需要带什么?通常在
Location响应头放新资源 URL,body 可返回创建后的表示。
06.1.1.1-005 201/204/301/302/304/409/422/429 各自适用什么场景?
一句话结论
这些状态码各有明确用途:201 表示创建、204 表示成功无返回、301/302 表示跳转、304 表示缓存未变、409 表示冲突、422 表示业务语义不通过、429 表示限流。
概念解释
- 201 Created:资源已创建,通常配合
Location。 - 204 No Content:成功但无返回体,DELETE 或无内容的更新常用。
- 301 Moved Permanently:永久迁移,浏览器/缓存会记忆;302 Found:临时跳转。
- 304 Not Modified:条件请求下资源未变,客户端用本地缓存。
- 409 Conflict:与资源当前状态冲突,如乐观锁版本不符。
- 422 Unprocessable Content:语法合法但语义校验失败。
- 429 Too Many Requests:限流,应携带
Retry-After。
示例
HTTP/1.1 201 Created
Location: /orders/1001
HTTP/1.1 204 No Content
HTTP/1.1 409 Conflict
{ "code": "VERSION_CONFLICT", "message": "订单版本已过期" }
常见误区
- 删除成功返回 200 并带空对象:204 更准确。
- 用 400 表达业务校验失败:参数格式错误用 400,语义不满足用 422。
追问
- 301 与 302 对缓存的影响?301 会被浏览器长期缓存,改回原地址需要清缓存;临时切换用 302(或 307 保持方法)。
- 429 为什么适合自动重试?它明确表达「稍后再试」,响应可带
Retry-After秒数。
06.1.1.1-006 路径命名与层级设计有什么原则?
一句话结论
路径用小写复数名词、短横线分词;层级表达资源归属,控制在两到三层;标识放在末级,过滤/排序/分页走查询参数。
概念解释
- 命名:小写、连字符分隔单词;避免驼峰、下划线、动词;标识作为路径参数。
- 层级:
/orders/{id}/items/{itemId}表达从属关系;过深层级会形成难以复用的定制路径。 - 横切能力:过滤、排序、分页、字段裁剪属于查询参数,不进路径。
示例
GET /customer-orders?status=paid&sort=-createdAt&page=2&pageSize=20
GET /orders/1001/items/50
常见误区
- 路径层级无限嵌套:
/a/{id}/b/{id}/c/{id}导致跨资源查询困难。 - 把查询条件写进路径:
/orders/paid/2026不如/orders?status=paid&from=2026-...灵活。
追问
- 资源名用复数还是集合名?团队内统一即可,主流规范(如 Microsoft REST 指南)多用复数。
- 多词资源怎么分隔?用连字符
customer-orders,避免/customerOrders或/customer_orders混用。
06.1.1.1-007 查询参数、过滤、排序怎么设计?
一句话结论
集合接口用统一的查询参数约定:过滤按字段名、排序用 sort、分页用 page/pageSize 或游标;参数命名与文档一致。
概念解释
- 过滤:
?status=paid&userId=123,等值过滤为主;复杂条件由后端限定支持的字段。 - 排序:
sort=-createdAt,name,减号表示降序;白名单允许排序字段。 - 分页:页码模式
page/pageSize;大数据量用游标(cursor/lastId)避免深分页。 - 字段裁剪:
fields=id,status,amount减少传输。
示例
GET /orders?status=paid&sort=-createdAt&page=2&pageSize=20&fields=id,amount
GET /orders?cursor=eyJpZCI6MTAwMX0&pageSize=20
常见误区
- 开放任意字段排序:可被用于排序未建索引的字段,拖垮数据库。
- 深分页用
offset翻到几千页:数据库扫描成本高,应改游标分页。
追问
- 游标分页与页码分页怎么选?小数据量、可跳转页码用 offset;大数据量、无限滚动用游标。
- 过滤参数类型不匹配返回什么?400 或 422,说明参数类型要求。
06.1.1.1-008 为什么不要用 GET 修改数据?
一句话结论
GET 被定义为安全方法,浏览器预取、代理缓存、爬虫、日志与历史记录都可能自动发起 GET;用它做写操作会被意外重复触发。
概念解释
HTTP 中间件(浏览器、CDN、网关)基于方法语义缓存和重试 GET。GET 请求还会进入访问日志、浏览器历史、Referer,参数可能暴露在 URL 中。任何具有副作用的操作都必须用 POST/PUT/PATCH/DELETE。
常见误区
- 「后端在 GET 里改库也能跑」:单次测试可用,但线上预取、刷新重试、CDN 回源都会触发副作用。
- 用 GET 传递敏感参数:URL 会被记录在日志与历史中。
追问
- 邮件里的退订链接为什么用 GET?这是历史遗留的非浏览器场景;严格做法是链接到确认页,再由 POST 提交。
- GET 带 body 可以吗?规范不鼓励,多数代理/网关会丢弃 GET body,参数应放 query。
06.1.1.1-009 响应包裹结构 code/message/data 怎么定?
一句话结论
二选一保持统一:要么纯资源表述 + 状态码,要么统一包裹 code/message/data/traceId;不要两套并存,错误细节与调试信息分层返回。
概念解释
纯 REST 风格直接返回资源,错误由状态码 + 错误对象表达;国内常见统一包裹:业务码 code、提示 message、数据 data、链路 traceId。统一包裹便于前端兜底,但要让 HTTP 状态码与业务码保持一致语义,避免全 200。
示例
{
"code": 0,
"message": "ok",
"data": { "id": 1001, "status": "paid" },
"traceId": "7f3a91c2"
}
常见误区
code与 HTTP 状态码各说各话:HTTP 200 但 code 为业务错误,监控按状态码统计会失真。- 响应里直接带堆栈、SQL、内部主机名:泄露实现细节,应只在日志保留。
追问
- 错误响应体应包含哪些字段?稳定错误码、可读提示、字段级校验错误、traceId;堆栈不返回客户端。
- 列表数据怎么包?
data: { "items": [...], "page": 2, "pageSize": 20, "total": 128 },分页元数据与条目分开。
06.1.1.1-010 嵌套资源到什么深度合适?
一句话结论
路径层级表达强从属关系,一般不超过两到三层;跨聚合的查询用顶层资源 + 过滤参数,而不是深嵌套路径。
概念解释
深嵌套路径把查询绑定在某个父资源下,复用性差:查「某商品的所有评论」不能只从商品路径走。聚合内部的从属关系适合嵌套,跨聚合关系用过滤参数表达。
示例
# 合理:订单从属其订单项
GET /orders/1001/items
# 跨聚合:按商品过滤评论,走顶层资源
GET /comments?productId=88
常见误区
- 为了贴合数据库外键层级建三层以上路径。
- 嵌套路径上再挂聚合动作,路径语义迅速失控。
追问
- 子资源可以被独立访问吗?可以,但要做归属校验:访问
/orders/1001/items/50时确认 50 属于 1001,防水平越权。 - 嵌套资源的更新走哪条路径?子资源自身有独立标识时,可暴露
/items/50;仅从属展示时挂在父路径下操作。
06.1.1.1-011 哪些 HTTP 方法是幂等的,为什么?
一句话结论
GET、HEAD、PUT、DELETE 是幂等方法;POST、PATCH 不保证幂等。幂等指多次相同请求的服务器状态与首次一致。
概念解释
幂等性让客户端在网络超时后可以安全重试。GET 不改变状态;PUT 每次用同一完整表示替换,结果相同;DELETE 重复删除同一资源结果都是「不存在」。POST 每次提交可能创建多条记录;PATCH 的重复应用语义不被规范保证。
常见误区
- 「DELETE 第二次调用返回 404 就不幂等」:资源最终状态相同(不存在),即满足幂等;404 只是响应差异。
- 把业务幂等等同于方法幂等:POST 可借助幂等键实现业务幂等,但 HTTP 方法语义仍按非幂等处理。
追问
- 重试只对幂等方法安全吗?对非幂等方法,必须先实现业务幂等(幂等键/唯一约束)再重试。
- HEAD 是做什么的?只返回 GET 的响应头,不返回 body,常用于探测资源是否存在与大小。
06.1.1.1-012 什么是 REST 的无状态约束,对后端意味着什么?
一句话结论
每个请求自包含足够信息完成处理,服务器不保存上一次请求的会话上下文;可伸缩性来自请求之间互不依赖。
概念解释
无状态约束要求会话状态留在客户端(如令牌),服务端任意实例都能处理任意请求。这与「服务端 Session」不矛盾:Session 是把会话状态外置到存储,请求携带 sessionId,服务端不把状态留在内存进程里。
常见误区
- 无状态等于不能用 Session:Session 是外部存储,进程本身不保存上下文,仍然符合约束。
- 把用户状态挂在服务本地内存(实例内缓存):多实例部署后请求落到别的实例就读不到。
追问
- 哪些状态必须留服务端?授权、黑名单、会话记录;客户端只携带引用标识或令牌。
- 无状态对横向扩展的好处?实例无本地粘性,可任意增减、负载均衡。
06.1.1.1-013 集合接口与单条接口的返回约定是什么?
一句话结论
集合返回条目数组加分页元数据;单项返回资源对象;创建返回 201 + 新表示;删除返回 204;字段命名、时间格式、空值表达全接口一致。
概念解释
- 集合:
{ "items": [], "total": 128, "page": 2, "pageSize": 20 },不要直接返回裸数组导致后续无法加元数据。 - 单项:资源对象本身;不存在返回 404。
- 命名:字段用 camelCase 或 snake_case 全接口统一;时间用 ISO 8601 UTC 字符串。
示例
// 集合
{ "items": [{ "id": 1001 }], "total": 128, "page": 2, "pageSize": 20 }
// 单项
{ "id": 1001, "createdAt": "2026-11-18T03:20:00Z" }
常见误区
- 集合直接返回数组:后续加 total/分页字段会破坏客户端解析。
- 时间戳混用:接口之间有的返回秒级时间戳,有的返回 ISO 字符串。
追问
- 空集合返回
[]还是null?返回空数组,避免客户端判空异常。 - 金额怎么表达?用最小单位整数(分)或带精度的 decimal/字符串,不用浮点数。
06.1.1.1-014 异步任务接口怎么设计?
一句话结论
长耗时任务用「提交任务 → 返回任务标识 → 轮询或回调查询状态」的模式;先返回 202 Accepted,任务状态机可查。
概念解释
同步等待长任务会占满连接与线程。异步模式:提交后服务端受理,返回任务资源 /tasks/{id},客户端轮询状态(pending/running/succeeded/failed),或完成后 WebHook 回调。
示例
POST /imports
202 Accepted
Location: /tasks/88
GET /tasks/88
{ "status": "succeeded", "resultUrl": "/exports/88.xlsx" }
常见误区
- 同步接口里跑几分钟批处理:连接超时、线程池耗尽。
- 任务状态不持久化:服务重启后进行中任务丢失且无法恢复。
追问
- 轮询与 WebHook 怎么选?内部/简单场景轮询;外部系统、长任务用 WebHook 加签名验签。
- 任务失败如何表达?任务状态
failed,带错误码与可重试标记;不要在提交时就返回最终结果。
06.1.1.1-015 空集合、null 与字段省略如何表达?
一句话结论
空集合返回空数组;可空字段按约定返回 null 或省略二选一;不返回空字符串冒充无值;响应示例与文档说明一致。
概念解释
- 集合无数据:
items: []。 - 标量可空:字段存在且值为
null;若采用省略策略,则不返回该字段。 - 两种策略不可在同一资源上混用,否则客户端解析歧义。
常见误区
- 空集合返回
null:客户端需要判空后再遍历。 - 把未提供的可选字段写成空字符串
"":与真实空值混淆。
追问
- 日期字段未设置返回什么?按约定
null或省略,不要返回1970-01-01。 - 嵌套对象为空如何表达?对象
null还是{},取决于字段语义并在文档固定。
06.1.1.1-016 时间、货币、分页等通用字段有什么约定?
一句话结论
时间统一 ISO 8601 带 UTC 偏移;货币用币种 + 最小单位整数或定点数;分页字段名全接口一致;枚举值用稳定字符串标识。
概念解释
- 时间:
2026-11-18T03:20:00Z,服务器存 UTC,展示由客户端本地化。 - 货币:
{ "currency": "CNY", "amount": 9900 }(分),避免二进制浮点误差。 - 分页:
page/pageSize或cursor/pageSize;枚举:status: "paid"而非魔法数字。
常见误区
- 金额用
double:累计与四舍五入出现误差。 - 时间戳用本地时区不带偏移:跨时区调用理解错误。
追问
- 为什么时间推荐存 UTC?多地域部署与夏令时切换下,UTC 无歧义。
- 枚举字段要补描述吗?接口返回稳定标识;文案由前端按标识映射,便于多语言。
06.1.1.1-017 资源 URL 中不得不放动作时怎么处理?
一句话结论
把动作建模为子资源或任务资源,用 POST 发起;路径保持名词化,动作语义在文档中说明,避免 /doXxx 风格的 RPC 堆砌。
概念解释
取消、审批、导出等行为若不能表达为资源状态字段,可作为子资源:/orders/{id}/cancellation、/reports/exports,POST 提交。这样路径仍是资源标识,方法表达发起动作。
示例
POST /orders/1001/cancellation
{ "reason": "用户申请" }
POST /reports/exports
{ "reportType": "monthly" }
常见误区
- 一个动作一个动词路径,逐渐退化为 RPC 风格且无统一约束。
- 动作子资源不做幂等与归属校验。
追问
- 状态迁移能用 PATCH 吗?能:把
status作为资源字段提交;需要附带原因、审批记录时再用动作子资源。 - 动作子资源返回什么?201/202 + 新资源或任务标识。
06.1.1.1-018 HATEOAS 要不要用?
一句话结论
HATEOAS(超媒体作为应用状态引擎)通过响应中的链接引导客户端跳转;主流业务 API 很少强制使用,内部固定客户端通常不必引入。
概念解释
HATEOAS 在资源响应里带 links:self、cancel、refund 等关系链接,客户端按关系名访问,而不是拼接 URL。它降低客户端与 URL 结构的耦合,但增加响应体积与文档复杂度。
示例
{
"id": 1001,
"status": "paid",
"links": [
{ "rel": "self", "href": "/orders/1001" },
{ "rel": "refund", "href": "/orders/1001/refund", "method": "POST" }
]
}
常见误区
- 把 HATEOAS 当作 REST 必选项:成熟度模型中它是更高层级,多数团队停在资源层级即可。
- 链接关系名不固定:
rel没有标准字典,客户端仍需约定。
追问
- 什么场景适合超媒体?开放平台、多客户端、需要引导状态流转的 API。
- 不用 HATEOAS 如何解耦?OpenAPI 文档 + 稳定资源路径 + 版本兼容。
06.1.1.1-019 RPC 风格与 REST 风格怎么取舍?
一句话结论
REST 面向资源、通用缓存友好;RPC 面向动作、函数语义直接;内部高性能调用可选 gRPC 等 RPC,对外开放多用 REST/HTTP API。
概念解释
RPC 风格以方法为中心:/getOrder、/cancelOrder,语义直接但资源抽象弱;REST 以资源为中心,方法语义由 HTTP 承担。实际工程常混合:对外资源接口 REST,内部服务调用走 RPC。
对比
| 维度 | REST 风格 | RPC 风格 |
|---|---|---|
| 中心 | 资源名词 | 动作方法 |
| 缓存 | HTTP 缓存友好 | 多为不可缓存 |
| 类型契约 | JSON 松散 | 强类型 IDL 常见 |
| 适用 | 对外开放、资源查询 | 内部命令式调用 |
常见误区
- 把 REST 当政治正确:复杂命令流程下 RPC 表达更清晰,无需强行资源化。
- 内部调用沿用浏览器可调试的 HTTP JSON:高并发内部服务可用二进制 RPC。
追问
- 一个系统能否两种并存?可以:边界对外 REST,内部服务间 RPC,但跨边界要做协议转换。
- RPC 失去资源语义后如何治理?靠 IDL 契约、版本与错误码规范。
06.1.1.1-020 API 设计中如何避免泄露内部实现?
一句话结论
对外资源是聚合视图,不映射数据库表结构;标识可重映射;错误与响应不暴露表名、SQL、内部主机、框架堆栈。
概念解释
- 字段命名面向业务,不直接暴露列名(如
passwordHash、internalId)。 - 自增 ID 可映射为对外标识或加混淆,减少枚举风险。
- 异常响应只给业务错误码与提示,堆栈进入服务端日志。
常见误区
- 直接把 ORM 实体序列化返回:敏感字段、关联表结构一并泄露。
- 错误信息里拼 SQL 或表名:帮助攻击者定位注入点。
追问
- 对外 ID 用自增还是 UUID?内部高频自增,对外暴露敏感资源时可用 UUID 或不可枚举标识。
- DTO 与实体分离的意义?隔离内部结构,控制字段暴露与序列化时机。
本节自检
- [ ] 能把一组业务实体映射为集合/单项路径并选择正确方法
- [ ] 能在 400/401/403/404/409/422/429/500/503 间做准确选择
- [ ] 能说明幂等方法清单及 GET 不能写数据的原因
- [ ] 能写出集合、单项、异步任务三类响应约定
- [ ] 能列出避免内部实现泄露的具体做法