如何做好 API 接口设计？

无论是架构设计还是编码实现，现在都越来越离不开接口设计，接口可以说是新时代的“集装箱”，是得到了几乎所有人一致共识的通用标准。

GoF 在很多年前便建议大家应该针对接口编程，原因其实就是为了降低编程变化而导致风险出现的概率。

不过现实中，你可能遇见的更多是这样的情况：

• 定义好的 API 接口，却接收了额外的参数，导致程序异常退出；

• 查询返回的数据，没有回传预期的格式，数据处理出错；

• 一个 API 服务进行分布式部署，遗漏了某个节点，导致处理数据不一致。

现代软件开发虽然一直在按照约定进行编程，但是程序员群体却是喜欢违反契约的群体之一，因为契约代表了约束，而编程本身是自由灵活的事情。那如何才能平衡这种“约束”与“自由”之间的关系？如何才能更好地避免再发生上述情况？以及如何才能真正做到 API 设计呢？下面，我们就一起来看看做好API设计的方法和技巧。

一、契约式设计原则：API 设计的指导书

契约式设计原则（Design by Contract，缩写为 DbC，为表述统一，下文我们就简称为“契约原则”），是一种软件设计方法。其原理是：在软件设计时应该为软件组件定义一种精确和可验证的接口规范，这种规范要包括使用的预置条件、后置条件和不变条件，用来扩展普通抽象数据类型的定义。比如，在 Web 请求中，预置条件主要用于处理输入的参数校验，不变条件主要指一个请求中的共享数据状态，后置条件则是对返回的响应数据的检查与确认。如下示意图：

契约原则的核心思想是对软件系统中元素之间的相互合作以及“责任”与“义务”的比喻，这种比喻是从商业活动中“客户”与“供应商”达成“契约”而得来。

在我看来，理解三者之间的关系非常重要，因为这是帮助我们合理利用契约原则进行 API 设计的基础。

现在 API 设计已经变得越来越重要，但是不管怎么变，API 的设计实现依然需要回答三个关键问题：

• API 期望的是什么？

• API 要保证的是什么？

• API 要保持不变的是什么？

能否设计好一个 A