罗罗编程学习记录
本页内容 展开查看

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)返回给客户端,客户端通过表述上的链接和方法转移状态。资源是名词,例如订单、用户、商品;动作是动词,例如创建、读取、更新、删除。

原理流程

  1. 从领域模型中识别实体:订单 orders、订单项 order-items、用户 users。
  2. 集合用复数路径:/orders;单项用标识:/orders/{id}。
  3. 动作交给 HTTP 方法:GET 读取、POST 创建、PUT/PATCH 更新、DELETE 删除。
  4. 关联资源通过路径层级表达:/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 不能写数据的原因
  • [ ] 能写出集合、单项、异步任务三类响应约定
  • [ ] 能列出避免内部实现泄露的具体做法