Appearance
REST 的起源与官方规范
本章导读：REST 不是一种可以"下载"的技术，它的权威定义来自一篇博士论文和一组 IETF 发布的 RFC 文档。学规范，先要认识规范的"出处地图"。本章梳理 REST 相关的官方文档，并说明哪些是"必须遵守的协议标准"、哪些是"社区最佳实践"。
1. REST 的起源：Fielding 博士论文
2000 年，Roy Thomas Fielding（伊利诺伊大学厄巴纳-香槟分校）完成了博士论文：
《Architectural Styles and the Design of Network-based Software Architectures》 （架构风格与基于网络的软件架构设计）
这篇论文同时是 HTTP/1.1 规范的设计说明书——Fielding 是 HTTP/1.0（RFC 1945）、HTTP/1.1（RFC 2068/2616）和 URI 规范的主要作者。论文第 5 章系统阐述了 REST 的六大架构约束（详见REST 六大约束一章）。
从论文中可以直接引用 REST 的定义：
"REST 架构视图组件的抽象状态是：资源的集合。资源是信息的抽象化，而不是保存信息的实体。……资源的具体表现形式是字节流，被称为资源的表示（representation）。" —— Fielding, 5.2.1 Resource
关键认知：REST 的先辈不是 Web Service（SOAP/WSDL），而是 HTTP 协议本身。 所以"学 RESTful 规范"约等于"把 HTTP 的语义学透"。
2. 官方规范地图
下面是本教程会反复引用的 RFC 清单（截至 2026 年的最新版本），建议收藏：
2.1 HTTP 语义层（REST 的地基）
| 规范 | 标题 | 与 REST 的关系 |
|---|---|---|
| RFC 9110 | HTTP Semantics（2022，取代 RFC 7231 等） | 定义方法、状态码、头部、内容协商——REST 统一接口的协议基础 |
| RFC 9112 | HTTP/1.1（消息语法） | 报文格式 |
| RFC 9111 | HTTP Caching | 缓存约束的实现依据（Cache-Control、ETag） |
| RFC 9113/9114 | HTTP/2、HTTP/3 | 传输层，不影响 API 设计语义 |
| RFC 5789 | PATCH Method for HTTP | 局部更新方法的官方定义 |
| RFC 7231 §3.1（已并入 9110） | 媒体类型注册 | application/json 等的注册机制 |
2.2 URI 与资源标识层
| 规范 | 标题 | 要点 |
|---|---|---|
| RFC 3986 | URI: Generic Syntax | URI 语法（scheme/authority/path/query/fragment）、保留字符、百分号编码 |
| RFC 3987 | IRI | 国际化 URI（路径尽量不用中文的基础依据） |
| RFC 8288 | Web Linking | Link 响应头与关系类型（分页 rel="next"、HATEOAS 的协议载体） |
2.3 数据与错误层
| 规范 | 标题 | 要点 |
|---|---|---|
| RFC 8259 | The JavaScript Object Notation (JSON) Data Interchange Format | REST API 事实上的标准媒体类型 |
| RFC 3339 | Date and Time on the Internet: Timestamps | JSON 中时间戳的标准化写法（如 2026-01-15T08:30:00Z） |
| RFC 6901 | JavaScript Object Notation (JSON) Pointer | 用指针精确引用 JSON 文档节点 |
| RFC 6902 | JSON Patch | application/json-patch+json：PATCH 的差量指令格式 |
| RFC 7386 | JSON Merge Patch | application/merge-patch+json：合并式补丁（更易用） |
| RFC 7807 → RFC 9457 | Problem Details for HTTP APIs | 错误响应体的官方标准格式（application/problem+json） |
2.4 认证与安全层
| 规范 | 标题 | 要点 |
|---|---|---|
| RFC 7235 | HTTP Authentication: Framework and Scheme Registration | 401 + WWW-Authenticate 的框架 |
| RFC 7617 | The Basic Authentication Scheme | HTTP Basic 认证方案 |
| RFC 6749 / 6750 | OAuth 2.0 Authorization Framework / Bearer Token Usage | 第三方授权的工业标准 |
| RFC 8785 | JSON Web Token (JWT) 的签名对象规范化（JCS）；JWT 本体为 RFC 7519 | Bearer Token 常用格式 |
2.5 演进与治理层
| 规范 | 标题 | 要点 |
|---|---|---|
| RFC 8594 | The Sunset HTTP Header Field | 声明 API 资源"日落"时间的官方头部 |
| RFC 9745 | The Deprecation HTTP Header Field（2025） | 官方"弃用通知"头部，标记 API 已进入废弃期 |
| RFC 6648 | Deprecating the "X-" Prefix | 头部命名不再用 X- 前缀 |
3. 社区规范与事实标准
RFC 之下，还有一批被大厂广泛采纳的"社区规范"，它们是 RFC 语义到团队落地规范之间的桥梁：
| 规范 | 出处 | 特点 |
|---|---|---|
| OpenAPI Specification 3.1 | Linux Foundation / OpenAPI Initiative | API 的"机器可读描述"标准，OAS 3.1 与 JSON Schema 完全对齐 |
| Microsoft REST API Guidelines | GitHub microsoft/api-guidelines | 条目极细（命名、分页、错误、异步作业），可作为团队规范蓝本 |
| Zalando RESTful API Guidelines | github.com/zalando/restful-api-guidelines | 欧洲大厂实战规则，明确引用 RFC 条款作为依据 |
| Google AIP（API Improvement Proposals） | aip.google | 含 resource / method / pagination 设计，gRPC 与 REST 双栖 |
| 阿里巴巴 Java 开发手册（黄山版） | 内部公开版 | 国内团队常引用的 API 命名与错误码规约 |
TIP
优先级判断法：RFC 定义"对错"（能否缓存、幂等性、状态码语义），社区规范定义"好坏"（命名风格、分页参数叫什么）。 团队制定规范时，建议以 RFC 9110 + RFC 3986 + RFC 9457 为硬性底线，从 Microsoft/Zalando 指南中裁剪适合自身的软性约定。
4. 常见误解澄清
- "REST 是一种协议" —— 错。REST 是架构风格；协议是 HTTP。REST 不发明任何新协议，只是"把 HTTP 用对"。
- "用 JSON 就是 RESTful" —— 错。媒体类型与是否 REST 无关，Fielding 原始论文甚至更倾向超媒体（HAL/Atom）。JSON 只是目前最流行的表示格式。
- "必须有 CRUD 才叫 REST" —— 不准确。REST 资源可以是"一次转账""一个视频转码任务"（POST 创建"任务"资源），不必对应数据库表。
- "POST /login 违反 REST" —— 争议点。把
login建模为"会话资源"（POST /sessions）更纯粹；业界普遍接受/login作为动词端点的实用主义例外（OAuth 的 RFC 6749 本身就用/token端点）。
5. 本章小结
- REST 的权威定义：Fielding 2000 年博士论文；工程语义的权威定义：RFC 9110 家族。
- 学 RESTful 规范的正确姿势：以 RFC 9110/3986/8259/9457 为核心教材，以 OpenAPI/社区指南为落地模板。
- 记住分界线：RFC 管"对错"，社区规范管"好坏"。