服务API设计之——API设计原则

你是否也感同身受？

1. 对接XX业务时，XX业务具有的功能和API全靠跑业务负责人那反复逐个询问、确认。用哪一个API；怎么用；有没有限制；等等
2. 各个业务间，甚至同一业务内，API风格不统一。
   • API命名：按天然语义全翻译的；按属性角度定义的；按操做角度定义的；动宾、非动宾的；复数、非复数的；等等
   • API入参：带Map的；相同语义字段名称不同；
   • API出参：有包装Resoponse的；直接返回结果数据的；相同数据，返回格式和字段名称有差异的；
   • 错误信息：直接返回中文提示的；返回提示信息编码的；返回异常类型的；等等
3. XX业务API性能方面未知。
4. 随着业务的演进，开放的API持续在增长，但类同的不少

API编码规范迫在眉睫

---

优秀API的特质

1. 自解释
   • 从API自己一眼就能看懂API是干什么的，支持的用法，适用的场景，异常的处理等
2. 易学习
   • 有完善的文档，以及提供尽量多的示例和可copy－paste的代码。
3. 易使用
   • 功能强大，但使用简单。不增长调用方的使用成本（例如要求业务方用API时须要额外的配置和依赖），不暴露复杂的细节、冗长的使用流程给调用方感知。调用方只作最小的感知和最少的传参。
4. 难误用
   • 优秀的API可使有经验的开发直接使用API而不须要阅读文档。
   • 充分的静态检查、动态校验、显式的异常说明、有效的错误提示。

---

ZCY API 设计原则

1. 充分原则

不是随便一个功能就要有个接口，也不是随便一个需求就要加个接口。

每新建一个接口，要有充分的理由和考虑，即这个接口的存在是十分有意义和价值的。无心义的接口不只增长了维护的难度，更重要是对于程序的可控性的大大下降，接口也会十分臃肿。

2. 单一视角原则

设计接口时，分析的角度要统一。不然会形成接口结构的混乱。例如：不要一会以角色的角度设计，一下子就要以功能的角度设计。

推荐：以”属性对象 + 行为”的视角定义API

3. 单一功能原则

每一个API接口应该只专一一件事，并作好。产品概念简单、关系清楚。功能模棱两可，诸多特殊逻辑的API确定不是个优雅的API，且会形成功能相似重复的API。

注：若是API它很难命名，那么这或许是个很差的征兆，好的名称能够驱动开发、而且只需拆分与合并模块便可。

功能大而全的API在灵活性、简单性方面确定捉襟见肘。定义API的粒度以前，建议先将业务分领域、划边界，以此来提取业务对象，而后再根据业务对象用例来设计单一功能的API。

好比：查询会员，可能除了查询会员表外还要获取该会员的其余必要信息，但不要在查询会员的同时还有修改权限等相似的其余业务功能，应该分红两个接口执行。

4. 简单原则

接口设计简单、清晰。API执行的功能能够很丰富、很强大，但API声明和用法必定要尽可能的简单，不能将功能的丰富经过复杂的用法来实现，这会致使API功能不单一，演进不可控。

最终的评审要看API的简单易用程度。

• 你写的例子，能不能让你的代码看起来更简单？
• 你是否是强迫调用方关注/提供他们不在意的选项/配置？
• 有没有毫无价值的额外步骤？

编写的代码必定要易于读、易于理解，这样别人才会欣赏，也可以给你提出合理化的建议。相反，如果繁杂难解的程序，其余人老是会避而远之的。

5. 抽象原则

API的入参、出参所述的对象、属性，必定是按业务特性进行抽象后的实体。误将底层数据模型概念如实的反应到API上。抽象API、抽象对象实体更宏观，具备更好的适用性、兼容性、扩展性。

6. 兼容扩展原则

对扩展开放，对修改关闭。保证API的向后兼容。

扩展参数应当是便利的，保证后续相似的需求，能够在已有的API上经过兼容扩展的方式实现。

7. 最小惊讶原则

代码应该尽量减小让读者惊喜。业务API只需根据需求来设计便可，不须要刻意去设计一下复杂无用、华而不实的API，以避免弄巧成拙。

8. 低耦合原则

API应该减小对其余业务代码的依赖关系。低耦合每每是完美结构系统和优秀设计的标志。

耦合的种类：

• 代码实现业务逆向调用。
• 条件逻辑依赖耦合。例如：此API在处理国税网超订单类型时，须要额外发送结算支付凭证上传的事件MQ出来。
• 耦合API无关的业务行为。例如：采购计划链路日志API被调用时，如果项目采购委托单的状况，须要额外调用公告的API拉取链路信息，新建成为一条此委托单的一条链路日志。

9. 正交原则

正交性是指改变某个特性而不会影响到其余的特性。

API之间的功能应该成正交性，无功能重合。API之间应该是互相补充的关系。

10. 易测试原则

对于API调用者而言，API应该是可被测试且易于被测试的。测试API不须要依赖额外的环境、容器、配置、公共服务等。

对可测试友好的API也是可被有效集成测试的前提。

11. 统一原则

API要具有统一的命名、统一的入/出参规范、统一的异常规范、统一的错误码规范、统一的版本规范等。

统一规范的API优势：

• 易于被框架集成、处理
• 有助于API调用方、API提供方开发经验复用
• 避免犯错，避免误用