REST API 设计

REST 由 Fielding 论文定义的约束集合构成：客户端与服务端分离，接口统一（资源标识、通过表述操作资源、自描述消息、HATEOAS）；无状态请求，每个请求自带全部上下文，服务端不保存会话，利于水平扩展与重试；可缓存，响应通过头声明可缓存性；分层系统，中间代理与网关对两端透明；按需代码可选（返回脚本扩展客户端）。实践中多数「RESTful API」只做到统一接口的资源化，HATEOAS 常被省略，严格派与务实派之争可以作为讨论点。答题时先列约束再点出无状态与统一接口对扩展性和一致性的意义，并说明表述通常用 JSON 而资源以 URI 标识，能提到 Fielding 原文批评「HTTP 加 JSON 不等于 REST」是加分项。

幂等指同一请求执行一次与执行多次效果相同。PUT 是全量替换：客户端提交完整资源表述，服务端整体覆盖，天然幂等，重复提交结果一致；PATCH 是部分更新：只发变更字段（JSON Merge Patch 或 JSON Patch 格式），语义上不保证幂等，例如「余额加 100」这类增量操作重复执行会叠加，若 PATCH 定义为设置目标值则幂等。相关对照：GET 与 DELETE 幂等（DELETE 第二次通常 404 但状态未变），POST 不幂等故用于创建与触发动作。设计要点：创建用 POST 返回 201 加 Location；更新整体用 PUT、部分用 PATCH 且字段语义用「设置」而非「增量」可保幂等；并发更新配 If-Match 与 ETag 做乐观锁防丢失更新。能举增量 PATCH 破坏幂等的反例即完整。

按语义分层记忆。2xx 成功：200 通用成功并带体；201 已创建（POST 建资源）配 Location；202 已受理异步任务；204 无内容（DELETE 成功或 PUT 无返回体）。3xx 重定向：301 永久（SEO 权重转移）、302 临时、304 缓存有效（配 If-None-Match 协商）、307 与 308 保持方法重定向。4xx 客户端错误：400 语义错误、401 未认证、403 已认证但无权限、404 不存在、409 冲突（版本或唯一约束）、410 已下线、412 前置条件失败、422 校验不过、429 限流要配 Retry-After。5xx 服务端错误：500 兜底、502 上游坏响应、503 暂不可用（维护或过载）、504 上游超时。反模式是全站 200 加业务码放 body，丢失 HTTP 语义让网关与缓存无法工作，正确做法是状态码加业务错误体双层表达。

常见方案：URI 路径版本（/v1/users）直观、路由与日志清晰，最普及；请求头版本（Accept 加 profile）更「 REST 正统」但调试麻烦；查询参数版本不推荐用于公开 API。演进原则上先做不破坏变更：加可选字段、加新端点、宽容读取多余字段；破坏性变更（删字段、改语义、改类型）才升主版本，旧版本设弃用时间表，用 Deprecation 与 Sunset 头公告，网关与监控双版本灰度分流。配套实践：OpenAPI 契约先行与 diff 检测防止无意破坏；移动端弱升级环境需要长周期多版本共存，服务端按版本适配器转换。答题给出选型对比加一个「加字段不破坏、删字段走新版本」的具体例子，并提 Sunset 头规范即显专业。

按场景选型。API Key 最简单，适合服务间低敏感调用与公开配额控制，缺点是无用户粒度且泄露即全权。Session 加 Cookie 适合浏览器同源应用，配 SameSite 与 CSRF 防护，跨域与移动端别扭。JWT 无状态令牌：服务端签名不存储，载荷带声明与过期时间，适合微服务与分布式；痛点是吊销难（需黑名单或短有效期加 refresh token 轮换）与令牌体积，且.jwt 不能放敏感明文。OAuth2 加 OIDC 是授权框架与认证层组合：授权码模式加 PKCE 是公开客户端标准，适合第三方登录与开放平台，内部系统直接用 client credentials 做服务间授权。安全通用项：全程 TLS、令牌不过 URL、短时效加刷新、最小 scope。能对比 JWT 与 session 的吊销差异并说清 PKCE 解决什么即优秀。