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

- Link: https://www.ixiqin.com/2023/09/14/why-is-the-design-of-openapi-so-important/
- Published: 2023-09-14T23:02:27+08:00
- Author: 白宦成

文章目录

 [Toggle](https://www.ixiqin.com/2023/09/14/why-is-the-design-of-openapi-so-important/#)

 * [为什么 OpenAPI 的设计如此重要？](https://www.ixiqin.com/2023/09/14/why-is-the-design-of-openapi-so-important/#%e4%b8%ba%e4%bb%80%e4%b9%88_openapi_%e7%9a%84%e8%ae%be%e8%ae%a1%e5%a6%82%e6%ad%a4%e9%87%8d%e8%a6%81%ef%bc%9f)
 * [沟通难度高带来的维护成本增高问题](https://www.ixiqin.com/2023/09/14/why-is-the-design-of-openapi-so-important/#%e6%b2%9f%e9%80%9a%e9%9a%be%e5%ba%a6%e9%ab%98%e5%b8%a6%e6%9d%a5%e7%9a%84%e7%bb%b4%e6%8a%a4%e6%88%90%e6%9c%ac%e5%a2%9e%e9%ab%98%e9%97%ae%e9%a2%98)
 * [风格/设计不统一带来的开发者评价问题](https://www.ixiqin.com/2023/09/14/why-is-the-design-of-openapi-so-important/#%e9%a3%8e%e6%a0%bc%e8%ae%be%e8%ae%a1%e4%b8%8d%e7%bb%9f%e4%b8%80%e5%b8%a6%e6%9d%a5%e7%9a%84%e5%bc%80%e5%8f%91%e8%80%85%e8%af%84%e4%bb%b7%e9%97%ae%e9%a2%98)
 * [如果我的设计已经不好了，又该如何处理？](https://www.ixiqin.com/2023/09/14/why-is-the-design-of-openapi-so-important/#%e5%a6%82%e6%9e%9c%e6%88%91%e7%9a%84%e8%ae%be%e8%ae%a1%e5%b7%b2%e7%bb%8f%e4%b8%8d%e5%a5%bd%e4%ba%86%ef%bc%8c%e5%8f%88%e8%af%a5%e5%a6%82%e4%bd%95%e5%a4%84%e7%90%86%ef%bc%9f)
 * [总结](https://www.ixiqin.com/2023/09/14/why-is-the-design-of-openapi-so-important/#%e6%80%bb%e7%bb%93)

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

在整个 S1 的文章中，我用了接近 4 篇的篇幅来介绍 OpenAPI 的设计，从一开始介绍[为什么要使用 RESTFul ](https://www.apiletter.com/s1e1-wei-shi-yao-kai-fang-ping-tai-da-duo-xuan-ze-liao-restful-feng-ge/)，
到 [API 的错误码设计理念](https://www.apiletter.com/s1e4-dao-di-duo-shao-ge-cuo-wu-ma-cai-shi-he-li-de/)，
辅以[批量接口设计的实例](https://www.apiletter.com/s1e5-ru-he-she-ji-yi-ge-fu-he-restful-feng-ge-de-pi-liang-cao-zuo-de-openapi-jie-kou/)，
再加上最后这篇重要性的强调，三分之二的比重，意在让你深刻认识到，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 的产品形态。