S1E6 为什么 OpenAPI 的设计如此重要？

在 APILetter 的 S1E6，我想和你聊聊 OpenAPI 设计的重要性。

在整个 S1 的文章中，我用了接近 4 篇的篇幅来介绍 OpenAPI 的设计，从一开始介绍为什么要使用 RESTFul ，到 API 的错误码设计理念，辅以批量接口设计的实例，再加上最后这篇重要性的强调，三分之二的比重，意在让你深刻认识到，OpenAPI 的设计至关重要。

为什么 OpenAPI 的设计如此重要？

在企业内部工作时，常常需要找到平衡质量和速度之间的折衷方案。当项目时间非常紧迫时，往往会牺牲一些质量。但如果项目有足够的时间，就有更高的概率能够设计出一个质量更好、开发者体验更佳的 OpenAPI。

然而，OpenAPI 是一项非常重要的任务，不能马马虎虎。一个坏的设计会让团队持续在 OpenAPI 开发上投入更多的精力。

沟通难度高带来的维护成本增高问题

和企业团队内部使用的 API 不同，OpenAPI 的用户是外部团队，用户的差异决定了沟通的难度的。

在内部API中，若需要对某个API进行不兼容变更，我们可以通过比较简单的沟通完成变更的通知，并通过企业内部的优先级对齐方式来明确变更的时间和行为。

但对于OpenAPI的用户来说，不兼容的变更意味着需要通知所有的外部开发者，并确保他们完成相应的更新。然而，这个时间节点和周期并不容易控制，跨企业的优先级对齐、时间节点对齐、以及出现问题时的技术支持，都可能会导致OpenAPI变更周期变得非常长，让维护人员感到疲惫不堪。

以平稳迁移为例，通常需要1-2年的时间才能下线OpenAPI。如果没有平缓过渡，那基本上就无法下线API了。

无法下线的 OpenAPI 最终将会指向不断增加的维护成本。毕竟，即使我们可以不在旧版的 OpenAPI 中去提供新的 Feature ，但依然要针对旧版本的 OpenAPI 提供安全更新，这会导致团队的研发成本越来越高。

风格/设计不统一带来的开发者评价问题

OpenAPI并不一定非要选择 RESTFul 风格，但一定要统一设计风格。

好的设计风格一方面是开发者对于美和好的追求，另一方面也会是开发者对于你的能力和团队水平的评估纬度。开发者可以通过对于接口风格、文档质量等多个角度的评估来评价你的产品的质量和结果。

虽然开发者并非企业的绝对决策者，但对于那些高度依赖开放性和集成性的业务而言，开发者的评价尤为重要。出色的开发者评价，将会使企业在进行集成相关的决策时，更加放心地进行选择。

当然，风格/设计不统一带来的也不仅仅是开发者评价问题，还涉及到更多的维护成本问题：

• 因为风格不统一，导致开发者对于不同的接口没有一个明确的范式，需要理解成本带来的学习成本高的问题。
• 因为风格不统一，导致开发者需要针对不同的接口做不同的适配层，重复建设。
• …

美与好不是一个 OpenAPI 在发布时必须要追求的，但又是你大规模获客时一个重要的对比项目。所以，在 OpenAPI 的设计早期，定义接口设计规范是一个值得投入时间和精力去思考的事情。

如果我的设计已经不好了，又该如何处理？

绝大多数人没有机会从头设计一个全新的 OpenAPI 系统，大多是需要一边跑一边换轮子的。

在这种情况下，可以考虑为你的 OpenAPI 设计一个明确的下线策略，以及，做好你需要花费一年的时间来做好这件事的准备。先定下统一的 OpenAPI 规范，并通过大版本迭代的方式，将旧版中的设计不好的 OpenAPI 重新梳理、设计、整合，并开放出新版的 OpenAPI 出去。

再将存量中设计不好的 OpenAPI 标记为 deprecated，引导增量开发者升级使用新版的 API，卡住存量的 API 的新增使用用户。

随后，只需要不断在新版的 API 中提供新的 Feature，使用自然的产品策略方式诱导开发者来升级，从而实现存量 API 的自然退役即可。

总结

和企业内部使用的 API 不同，OpenAPI 的开放属性决定了 OpenAPI 是很难退役的，因此，从一开始就朝着最好的方式来演进，可能才是最正确的做法。快速迭代，快速试错的路子，并不适合 OpenAPI 的产品形态。

祝好，

白宦成