2.6 HATEOAS：契约的导航

2.6 HATEOAS：契约的导航

本节摘要：HATEOAS（超媒体作为应用状态引擎）让服务器在资源表示里附带 _links，用链接引导客户端"下一步能做什么、去哪做"，从而把客户端从硬编码 URI 的泥潭里解放出来。本节讲清它的完整机制、业界"半套 vs 全套"的真实落差，并用一个订单状态机案例，判断什么时候值得认真做、做到什么程度。

学习目标

阅读完本节，你应当能够：

1. 用一句话说清 HATEOAS 与"响应里多几个链接"的本质区别。
2. 设计一个带 _links 的资源表示，表达 self 与各种关系的链接。
3. 解释"客户端靠链接导航"如何换来服务器端改 URI 的自由。
4. 权衡 HATEOAS 的实现成本，判断什么场景该做、到什么程度收手。

"有点链接"不等于 HATEOAS

大部分团队声称做了 HATEOAS，实际只是"响应里塞了一串 _links"。区别在哪？看一个反例：资源表示里放了个 "self": "/book/42"，客户端代码里仍然把"撤销订单那个 URI"写死成字符串。

这是假 HATEOAS——链接只是装饰，客户端根本没靠链接活。真 HATEOAS 的定义是：客户端把链接当应用状态的路标，跟着它走，而不把 URI 硬编码进自己代码。链接不是点缀，是导航，是让客户端"不知道自己下一站在哪、也懒得知道"的机制。

二、一次订单状态机的完整推演

用一个订单案例把机制走通。订单状态可能是：待支付 → 已支付 → 已发货 → 已完成，或中途取消。

服务器对 GET /orders/456（状态为"待支付"）返回：

{
  "id": 456,
  "status": "pending",
  "_links": {
    "self": "http://api.example.com/orders/456",
    "pay": "http://api.example.com/orders/456/payments",
    "cancel": "http://api.example.com/orders/456/cancel"
  }
}
​

隔天同一个订单已支付，GET /orders/456 现在的表示变成：

{
  "id": 456,
  "status": "paid",
  "_links": {
    "self": "http://api.example.com/orders/456",
    "cancel": "http://api.example.com/orders/456/cancel",
    "invoice": "http://api.example.com/orders/456/invoice"
  }
}
​

注意发生了什么：状态从 pending 变 paid 后，pay 链接消失了，出现了 invoice 链接。客户端代码不用改——它读走每一项 _links 里的 href，跟着可用链接导航，状态变了链接集合就变，客户端天然只能做当前状态允许的动作。这就是"应用状态引擎"：状态的推进，靠服务器给的链接指引，而不是客户端自己脑补逻辑。

三、客户端因此拿到什么

• URI 自由度：服务器可以改 URI 结构、加子域、换前缀，只要每个动作的 _links 还指向正确的新 URI，客户端无需跟着改。
• 动作自适应：客户端显示什么按钮、允许什么操作，取决于响应里有没有对应链接——状态机每次推进都同步更新，客户端逻辑变得极简。
• 发现新功能：服务器新增能力只需在 _links 里多暴露一个链接，老客户端忽略它，新客户端直接用上，向后兼容天然成立。

链接的"关系名"也别跟闹着玩似的起：self、next、prev、pay、cancel 这类语义明确的关系名，让客户端能按名字而非猜 URI 去找链接；而 link1、foo 这类无意义名字，等于没给导航。关系名本身就是给"应用状态引擎"铺的路标，起得越像是"下一个能做的是什么"，客户端越不需要在逻辑里硬塞状态判断。

四、代价与"半套 vs 全套"

HATEOAS 的代价也不小，这是谈它时必须摊在明面的部分：

• 实现成本：每个资源要想清楚"当前状态能干什么、链接怎么组织"，对领域状态机的要求高。
• 文档与测试成本：客户端与测试都要跟着链接走，脚本化的测试要处理"不确定的 URL"。
• 改造成本：对已有硬编码 URI 的客户端，上线 HATEOAS 是破坏性变更，要规划迁移。

于是业界真实分布是"半套 HATEOAS 远多于全套"：绝大多数接口做"链接已暴露、客户端仍硬编码"的折中——效率与演进性的平衡点落在"链接为参考、不强制客户端跟走"。可以这样定位自己：

⚠️ 常见坑：为某个业务一拍脑袋承诺"我们做全套 HATEOAS"，却没评估状态机复杂度与客户端迁移成本，最后半途而废，链接成了摆设。先从小范围（订单这种状态明确的资源）试点半套，验证收益再谈升级。

💡 关键直觉：HATEOAS 买到的是"未来改 URI 的自由"，付账的是"现在的建模与测试复杂度"。买不买、买到几成，是纯粹的工程取舍，不是宗教立场。

本节要点回顾

• 要点一：HATEOAS 是"客户端靠链接活"，不是"响应里多几个链接"。
• 要点二：_links 随资源状态变化而增减，驱动客户端动作自适应。
• 要点三：回报是服务器改 URI 的自由与向后兼容的演进。
• 要点四：代价在状态机建模与测试复杂度，与客户端迁移成本。
• 要点五：业界以"半套 HATEOAS"为主，全套是少数。
• 要点六：做不做、做到几成，是工程取舍而非立场之争。

导航条款画上句号，最后给这份契约上保险——幂等与安全这两条保证条款，专门管"重试、队列、重复提交"这些出事的时刻。