REST 反模式务实谈：当「不纯粹」也能把事办成

按 REST 之父 Fielding 的定义，没有 HATEOAS（超媒体驱动应用状态）就不算真正的 REST。但对大多数团队，HATEOAS 用现有工具实现起来并不轻松，而且对调用方来说反而稀释了你追求的简洁。原文一句话点透：「不采用超媒体，在很多情况下既可以是缺点，也可以是一种特性」。关键教训是——敢于如实称呼你的设计：大部分采用 REST 但不全用的，叫「务实 REST（pragmatic REST）」即可；如果它本质就是 RPC，只要名副其实、客户也认同，那就大方做成 RPC API，不必硬贴 REST 标签。

来看「Dave 这位 API 设计师」的案例：Dave 在一家大银行做客户查询 API，用 GET 查 Customer 资源，评审都通过了。IT 安全团队却一箭穿心：「我们这儿不搞 GET，改成 POST。」理由很现实：

• API 网关到 PaaS 之间有多层系统，都在记录请求。
• 被记的最多的就是 URI，而 URI 可能带敏感查询参数。
• 日志平台从不记 body，所以敏感数据得放进 body。
• 这是已签字确认的合规标准（涉及 PCI DSS 等对支付卡数据的保护）。

改标准成本太高，Dave 只能让步。教训：我们都想严格按 REST 来，但有时这跟组织的最佳利益冲突。作为设计者，可能得基于组织语境而非最佳实践做让步——它不 REST，但能把事办成、让干系人满意。

论幂等时，多数设计者默认照搬 Fielding 的 HTTP 方法规则。但 API 提供方常为业务弯折规则——幂等 POST 由此而生，尤其在支付场景：当一次支付调用在执行中失败（比如超时、客户端没收到任何 HTTP 响应），后续重试不能产生重复扣款。做法是对客户端要求提交「完全相同的指令 + 一个幂等标识」，让服务端识别出「这条指令我可能见过」。

PayPal、英国 Open Banking 支付发起 API 都这么做。幂等 POST 虽因无视 HTTP 规则而不「REST」，却为调用方避免了向客户重复扣款的重大事故——在这里，把 API 当产品、保护调用方不出错，优先于技术正确。

新手设计常把 REST 的「实体」概念滥用：连调用 API 的消费者也塞成一个实体，于是出现 GET /consumer/{consumerId}/customers/{customerId} 这种 URI。问题一堆：

• 它只对提供方有意义，对消费者零价值，还徒增 URI 复杂度。
• 把安全模型和数据模型混在一起（让调用方在 URI 里「自报身份」），接口更脆、易被滥用——一旦安全层有缝，冒名者可借机够到别的客户的资源。
• 引发「嵌套资源谬误（fallacy of nested resources）」，版本化时尤其头疼。

要点：只建模你真正需要建模的东西，别把关联实体硬塞进来。确需关联，用 HATEOAS 或考虑 GraphQL，而不是用脆弱的嵌套 URI。

说到底，有些做法会让你要么频频点头、要么咬牙切齿（比如 URI 里放版本号这种同样有争议的点）。但在这套仍在演化的「好设计」共识里，我们能学的一点是：把设计决策写进文档，让所有人看得见「为什么这么实现」，并做足调研、参考前人。最重要的是——技术人得学会放松：需求和人总会逼你实现自己不喜欢的模式或反模式，记住，说到底都只是 0 和 1。