API设计

Posted 2021-05-01 叻道

本文章的主题材料是《每个程序员应该知道的97件事》里的第35件事

API设计的黄金法则

（The Golden Rule of API Design）

老规矩，先分享书里这个章节的大意，再写“命题作文” 

It's not enough to write tests for an API you develop; you have to write unit tests for code that uses your API.

《The Golden Rule of API design》（点击“原文阅读”）

原文推荐：⭐⭐⭐

个人简评：我觉得这个黄金法则的表述有问题。结合原文其他内容，这个法则应该是“你必须让使用你的API的代码能够编写单元测试”，而不是“你必须为使用你的API的代码编写单元测试”。如果没测试过自己设计的接口，那么这个接口的设计犹如纸上谈兵。  

API设计

我认为， API 的设计并不是一件很困难的事情。因为给出一个能用的 API 并没有什么技术难度，它更多受限于对业务理解的程度。

如果不是从零开始打造服务或系统，现有代码的API风格便是一个基准线，我们至少容易和现有代码保持一致的水平。

如果是从零开始，我们大可不必纠结于在初期设计出一劳永逸的API，因为在这个时候的主要目标是先让一个最小的功能集合运转起来，API越简单具体越好。

然而，API的设计的确是一个容易让程序员烦恼的事情。API不易变，只要还有使用API的业务代码。而业务需求会不断变化，或者对业务需求的理解会不断深化，于是便有了API的升级扩展。当API的使用者越多，API的升级/迁移越是漫长和痛苦。

评价API的好坏，不能脱离具体的业务场景和工程环境。

首先，API的设计需要满足业务需求。虽然很多时候我们希望定义的API能尽可能满足更多的上层业务场景，但是API的定义应该明确地描述输入和输出。

虽然我们不会去声明 Object Do(Object input) 这极端的接口定义，但在定义里留一个通用的数据类型以备其他情况使用并不是一种很罕见的设计，无论对于输入还是输出。这并不是一个应该提倡的API设计，因为它牺牲了对业务能力的自描述能力，对业务编程不友好，而且容易引起代码缺陷、不易维护。

其次，工程环境不同，设计API要考虑的因素往往也不尽相同。比如将能力拆分成细小的API，在单体架构（monolithic architecture）下一般是好的设计原则，但对于微服务架构往往并不提倡。

如果不考虑具体的业务场景和工程环境，API的设计往往只需要做好一点： 确保使用API的业务代码能够编写单元测试。

在设计API的时候，我们不仅仅需要考虑业务代码如何使用API进行编程，我们还需要考虑那些业务代码是否能够通过单元测试验证业务代码自身的逻辑，而不需要依赖API内部的实现。

从业务代码开发者的角度看，也许这更容易理解—— 程序员应该面向接口编程而不是面向实现编程 。

在单元测试中，我们应该只测试业务代码自身的逻辑，而不该测试所依赖的API的逻辑。当引入API依赖的时候，业务代码应该面向API的抽象接口编程，无论是API自身提供的抽象接口，还是业务代码自身定义的抽象接口。如此，写业务代码的单元测试时我们才能够模拟API的各种行为，进而测试业务代码的所有分支。如果业务代码和API的实现相耦合，为了确保测试的覆盖率，我们需要理解API实现的细节才能够定义测试数据，这往往很困难、不易维护，而且不现实。

为了确保使用API的业务代码能够自测，在API设计的时候我们会更有意识地思考API的错误处理场景，从而提高API设计的完备性。在这个时候，API设计之道才算真正入门了。  

入门之后呢? 我想便是不断与具体业务场景和工程环境打磨的过程了。 关于这个打磨过程的道法术，我还能得出一个满意的总结概述。我希望这始终会是我技术生涯里的一个追求，因为这表示这门技术一直会快速往前发展，始终有需要学习的新变化。

 

---

来个“分享、点赞、在看”吧