使用友好的 API 设计理念

大家经常接触 API，而且往往会吐槽这个 API 设计的太难用了，那个 AP 理解成本提高，某个 API 有看起来那么不专业，等等。那么，怎样的 API 设计才是优雅的呢？

本文我们不讨论 API 的设计模式，是 Restful 还是 RPC，是声明式还是命令式。我们聚焦于 API 的设计理念，从使用方的角度，怎样的 API 设计是对使用方友好的。API 是定义出来给人调用的，对使用方友好的 API，基本上就等于是优雅的 API。

我们认为，对使用方友好的 API，需要满足三个特征：清晰、简单、完整。

首先，清晰。API 的设计必须没有二义性，这里面包括几个层面的清晰：

1. 每个 API 的命名、功能和适用场景是清晰的。使用方可以很容易的知道在什么场景下用什么 API。比如将支付的 API 定义为咨询、下单、回执、撤销。按照使用的阶段进行划分，使用的时候就不会有歧义。

2. 每个 API 里面的字段含义必须是清晰的。每个字段都有明确的业务语意，而且多个 API 之间的业务术语是统一的。使用方可以望文生义的知道每个请求的字段应该怎么赋值，回执的每个字段又表示什么。

3. 字段的 criteria 是清晰的。每个字段是必填、选填、还是 condition。每个字段的取值范围、长度、pattern 等。而且如果违反了 criteria，返回也是清晰的，用户从根据返回结果很容易的知道哪里错了。

其次，简单。对于两个领域之间的交互界面，维持 KISS 原则是非常有好处的。简单、傻瓜式，可以减少双方的理解成本、学习成本和沟通成本。成本越低，生命力越强。

这个简单，也有几个层面：

1. 交互简单：能同步的不要异步。能一次完成交互的不要分成多次。比如汇率和对手金额可以一起返回，没必要返回一个汇率，然后再请求一次（不管是 API 还是工具）来计算金额。比如一次咨询完成渠道、日历、汇率、费用的咨询，不要每个对象一次咨询。

2. 最小暴露领域概念：从使用方的视角去设计字段，不要过多的将本领域内部的概念暴露给使用方。比如汇率的标准币种对、OFFER/BID 价格就没必要暴露给使用方，让使用方按照自己领域的概念，给出付款和收款的币种金额就可以了。

3. 逐个斟酌字段：字段需要最简化，没必要的字段不要放在 API 中。不要做过度的预留，目前没想好的字段就不要放进去。

最后，完整。这个也很必要，API 的设计需要考虑全面。不要由于考虑不完整，导致 API 不断的升级和变更。

1. 业务场景全支撑：比如一个支付的 API，需要考虑到管制和非管制币种；需要考虑卡、APM、钱包等支付方式；需要考虑预扣款和后请款的模式。

2. 异常场景完整支持：需要对乱序、重发、超时等场景都考虑完整，并在 API 的定义中体现。对于幂等字段、结果码的定义，要求满足这些异常场景的要求。

完整和简单，在一定程度上是有矛盾的。这个需要在日常实践中用经验来弥补。