REST API 设计与实现：从资源建模到可观测 API

0. 元信息

• 主题路径：docs/topics/rest-api-design/README.md
• 主分类：Web 与后端
• 辅助分类：工程技术
• 适合对象：会写后端 handler、SQL 和 HTTP 请求的开发者
• 建议周期：4～6 周（每周 8～10 小时）
• 前置知识：network、http-1-2-3、db-and-sql
• 最终目标：能设计并实现带 OpenAPI、鉴权、限流、版本化、缓存和 tracing 的生产 API

1. 学习路线

资源与 URL → 方法语义 → 状态码与 problem+json → 分页/过滤 → 认证授权 → 限流配额 → 缓存/ETag → 版本化 → OpenAPI → CORS/Webhook → 可观测与发布

2. 阶段周数分配

3. 九阶段表

4. 第一周任务

Day 1 约定：OpenAPI 3.1；JSON；UTF-8；时间用 RFC 3339 UTC；金额用整数最小货币单位；命令用 curl。

可运行契约片段：

openapi: 3.1.0
info: {title: Shop API, version: 1.0.0}
paths:
  /products/{productId}:
    get:
      parameters:
        - {name: productId, in: path, required: true, schema: {type: string}}
      responses:
        '200':
          description: Product
          headers:
            ETag: {schema: {type: string}}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/Product'}
        '404':
          description: Not found
          content:
            application/problem+json:
              schema: {type: object}
components:
  schemas:
    Product:
      type: object
      required: [id, name]
      properties:
        id: {type: string}
        name: {type: string}

5. 阶段通用验收

1. 契约经 lint 且示例可被 curl 重放；2. 正常、非法、未认证、越权、冲突、超限路径都有测试；3. 写清 method、状态码和 header 的理由；4. 日志不泄露 token/PII；5. 变更前后做兼容检查；6. 指标能区分 client/server error；7. 第三方能只看 OpenAPI 完成调用。

6. 最终验收

• 至少 12 个 endpoint、20 个契约测试、10 个错误案例；
• OpenAPI 3.1 可 lint、可渲染、可生成客户端；
• 演示 OAuth2/JWT、对象授权、rate-limit、版本迁移、ETag、idempotency 和 trace；
• 能用 15 分钟讲清资源边界、兼容策略与运行证据。

7. 综合项目

首选：设计并实现一个完整的电商商品 / 订单 API，含 OpenAPI 文档、鉴权、限流、版本化、可观测。

必须含商品、订单、订单项、库存；cursor 分页；problem+json；ETag/If-Match；Idempotency-Key；OAuth2/JWT；429；Webhook 签名和重试；trace id；兼容迁移说明。

备选：将一套遗留 RPC 接口重构为 REST API 并保留向后兼容。交付 adapter、映射表、双写/影子流量策略和弃用时间线。

8. 推荐开源资料

9. 学习资料汇聚（v0.3 自包含）

9.1 背景与动机

REST 是 Fielding 在 2000 年论文中总结的网络软件架构风格。它强调 client-server、stateless、cache、uniform interface、layered system，可选 code-on-demand。工程里的“REST API”常只取资源和 HTTP 语义。我们要区分架构约束、团队风格和工具默认值。

9.2 概念地图

flowchart LR
  Resource[资源/URL] --> Method[HTTP method]
  Method --> Status[状态码/problem+json]
  Resource --> Query[分页/过滤]
  Auth[OAuth2/JWT] --> Authorization[RBAC/ABAC/对象授权]
  Gateway[API Gateway] --> Rate[rate-limit/quota]
  Method --> Cache[Cache-Control/ETag]
  Contract[OpenAPI/JSON Schema] --> Client[SDK/Postman/curl]
  Version[版本化] --> Contract
  Contract --> Runtime[实现]
  Runtime --> Trace[日志/指标/tracing]
  Runtime --> Webhook[Webhook/异步]

资源契约决定请求形状。安全、流控、缓存和兼容约束它的运行行为。OpenAPI 连接设计、实现、测试和客户端。trace 证明请求在同步与异步链路中发生了什么。

9.3 基础知识讲解

9.3.1 论文 / 规范

• Roy Fielding, Architectural Styles and the Design of Network-Based Software Architectures：REST 起源。
• RFC 9110, HTTP Semantics：方法、状态码、缓存语义。
• RFC 7807, Problem Details for HTTP APIs：统一错误对象。

9.3.2 书

• Leonard Richardson, Mike Amundsen, Sam Ruby, RESTful Web APIs。
• Arnaud Lauret, The Design of Web APIs。
• JJ Geewax, API Design Patterns。

9.3.3 博客 / 文档

• Stripe API 文档：idempotency、分页、错误风格。
• Microsoft REST API Gui：兼容与一致性。
• Google API Design Guide：资源导向设计。
• Apigee 文档 与 AWS API Gateway 文档：网关、配额、部署。

9.3.4 人物

• Roy Fielding：REST 与 HTTP 架构。
• Tim Berners-Lee：Web、URI、HTTP。
• Darrel Miller：OpenAPI Initiative 技术治理与工具生态。

9.3.5 方法

• Contract-first：先写 OpenAPI 和示例，再写 handler。
• Consumer-driven review：从调用方任务检查命名、错误和兼容。
• Single-variable test：一次只改变 method、header、身份或并发量。
• Compatibility budget：发布前列出 breaking change 与迁移期。

9.4 经典问题与经典案例

9.5 学习难点

• 概念难点：REST 约束、HTTP 语义和 CRUD 映射常被混成一件事。先逐条核对 Fielding 与 RFC 9110，再做资源案例。
• 思维难点：API 设计是给未知客户端长期使用。每个字段都问删除、重试、并发、兼容时发生什么。
• 工程难点：网关、应用、数据库、消息系统各持一部分状态。用 trace、idempotency store、outbox 和契约测试把边界变成可检查结果。

9.6 技术标准与接口

9.6.1 Entity

9.6.2 Scope

OpenAPI 描述 HTTP API；JSON Schema 描述数据约束；JSON:API 与 HAL 约定表示和链接；Problem Details 约定机器可读错误。它们不替代业务授权、事务设计或运行时保护。

9.6.3 Structure

OpenAPI 必会 paths、operations、parameters、requestBody、responses、components、securitySchemes；JSON Schema 必会 type、required、properties、组合与引用；Problem Details 必会 type/title/status/detail/instance。

9.6.4 Ecosystem

实现与工具包括 Swagger UI、Redoc、Spectral、OpenAPI Generator、Postman、Insomnia、Bruno、httpie、curl。API gateway 常用 Apigee、AWS API Gateway、Kong、Envoy。工具默认值不是规范。

9.6.5 Depth Tiers

本计划目标：L3。

9.6.6 Source

• OpenAPI Initiative 仓库：OpenAPI 3.1 原文与版本历史。
• IETF RFC Editor：RFC 9110、7807/9457、6585 等原文。
• JSON Schema 2020-12 与 JSON:API 1.1。
• 引用快照：2026-07-30。实施前检查更新、勘误与废止关系。

10. 常见误区

• 把 REST 等同 JSON over HTTP
• URL 里堆 /createOrder
• POST 重试不做 idempotency
• 所有错误返回 200
• 只做 endpoint 级认证，不做对象授权
• JWT 放敏感信息或永不过期
• offset 分页用于高写入大表
• ETag 生成不稳定
• 429 不返回重试信息
• 为每次小改动升版本
• OpenAPI 与实现各写一份后漂移
• CORS 当认证
• Webhook 无签名、去重和重试
• 日志记录 token/完整个人数据
• 只看平均延迟。

11. 所有知识点分类（统一规则）

1. 编程语言 2. 数据结构与算法 3. 计算机基础 4. 工程技术 5. Web 与后端 6. 前端与客户端 7. 数据与人工智能 8. 项目与职业能力 9. 安全与可靠性

本计划归属：Web 与后端 主 + 工程技术 辅。