REST API藏了24年：Roy Fielding的论文让多少

2000年，一个博士生在论文里随手写下的架构风格，成了今天90%互联网产品的底层骨架。但24年后，面试场上仍有开发者分不清PUT和PATCH的区别——这不是能力问题，是REST被过度简化的代价。

从"能跑就行"到架构思维：REST不是协议，是约束游戏

Roy Fielding在博士论文里提出的REST（表述性状态转移，Representational State Transfer），本质上是一套让互联网规模化的设计哲学。它和HTTP的关系，就像交通规则和柏油马路——后者是基础设施，前者是让你不撞车的约定。

但很多人误解了这一点。RESTful API的核心不是"用HTTP传JSON"，而是六个约束条件的精密配合：客户端-服务器分离、无状态通信、可缓存性、统一接口、分层系统、按需代码（可选）。违反任意一条，你的API就只是"长得像REST"的冒牌货。

状态码是API的肢体语言，200和201的区别，就像"收到"和"已办妥"的职场分寸。

初级开发者常犯的错：把所有成功返回都塞200，把错误详情藏在响应体里。正确的做法是让状态码本身说话——201表示资源已创建，204表示删除成功无需返回体，401和403要区分"没登录"和"没权限"。这省下的不只是字节数，是前后端沟通的心智成本。

分页、鉴权、版本控制：三个让系统崩溃的隐形炸弹

SELECT * FROM users 是生产环境的自杀式代码。10万条用户数据能让你的API内存爆炸，响应时间从毫秒级跌到秒级。正确的分页姿势是用查询参数：GET /api/v1/orders?page=2&limit=50&status=shipped。这里藏着另一个坑——limit不设上限，恶意请求直接拉爆数据库。

REST的无状态特性把会话管理踢出了服务器端。JSON Web Token（JWT，一种紧凑的令牌格式）成了主流方案，客户端每次请求都在Authorization头部带上令牌。但令牌过期策略、刷新机制、黑名单处理，每个环节都是架构设计的取舍题。

版本控制是API的遗嘱公证——v1和v2的URL分叉，决定了老用户是被温柔迁移还是被粗暴抛弃。

NeedleCode的技术文档里提到一个典型场景：某电商平台在v2重构了订单状态机，却没做版本隔离。结果第三方卖家的ERP系统集体报错，售后工单淹没技术团队。URL版本控制（/v1/ vs /v2/）虽然被吐槽"不够优雅"，却是工程上最可预测的方案。

HATEOAS：被90%项目跳过的"自描述"理想

Hypermedia as the Engine of Application State（超媒体作为应用状态引擎），这个拗口的缩写代表着REST的终极形态。响应里不光有数据，还有下一步操作的链接指引：

{ "user_id": 123, "name": "Dev", "links": [ { "rel": "self", "href": "/users/123" }, { "rel": "delete", "href": "/users/123", "method": "DELETE" } ] }

这让API像网页一样自发现——客户端不需要硬编码URL，跟着链接走就行。但现实很骨感：内部项目嫌它冗余，前端团队抱怨解析麻烦，GraphQL的崛起更是直接绕过了这套范式。Fielding的理想主义，在交付压力下节节败退。

不过某些场景它仍在发光。支付网关、云服务商的API常采用HATEOAS，因为它们的业务流程复杂且多变，硬编码状态机维护成本更高。Stripe的API设计就是典型案例，每个响应都附带下一步可能的操作。

从"调接口"到"设计系统"：REST是架构师的试金石

REST的流行从来不因为它"最先进"，而是因为它"最可预测"。同样的URL结构、同样的HTTP动词、同样的状态码语义，让不同语言、不同团队、不同年代写的代码能互相理解。这种兼容性在微服务架构里成了救命稻草——当你的系统拆成几十个服务，约定比创新更重要。

但REST也在被挑战。gRPC用二进制协议压榨性能，GraphQL用查询灵活性颠覆资源模型，Serverless架构让"无状态"变得理所当然。这些不是REST的葬礼，而是架构工具箱的扩容。

真正区分初级和高级开发者的，不是记住多少约束条件，而是面对具体业务时的取舍能力：什么时候严格遵循REST，什么时候 pragmatic 地打破规则，什么时候该换一套工具。

Roy Fielding的论文标题是《Architectural Styles and the Design of Network-based Software Architectures》。他写的是"风格"和"设计"，不是"标准"和"实现"。24年后，这个区分仍然值得被写在每个API文档的扉页。

你在设计API时，最近一次打破REST约束是为了什么？评论区聊聊你的 trade-off。