如何设计一个高质量的 API 接口？

清疚 2023-10-15 14:31 164阅读 0赞

#### 你是否也感同身受？ ####

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

> API编码规范迫在眉睫

#### [优秀API][API]的特质 ####

###### 自解释 ######

*  从API本身一眼就能看懂API是干什么的，支持的用法，适用的场景，异常的处理等

###### 易学习 ######

*  有完善的文档，以及提供尽可能多的示例和可copy－paste的代码。

###### 易使用 ######

*  功能强大，但使用简单。不增加调用方的使用成本（例如要求业务方用API时需要额外的配置和依赖），不暴露复杂的细节、冗长的使用流程给调用方感知。调用方只做最小的感知和最少的传参。

###### 难误用 ######

*  优秀的API可以使有经验的开发直接使用API而不需要阅读文档。
 *  充分的静态检查、动态校验、显式的异常说明、有效的错误提示。

#### 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提供方开发经验复用
 *  避免犯错，避免误用

[API]: https://link.juejin.cn?target=http%3A%2F%2Fo0b.cn%2Ftinale

发表评论取消回复

表情：

评论列表（有 0 条评论，164人围观）

还没有评论，来说两句吧...

相关阅读

相关怎么样设计一个高质量的 API 接口？

一、什么是幂等性？对于同一笔业务交易，不管调用多少次，只会成功处理一次。二、幂等性设计我们转账业务为例，来说明一下这个问题，转账接口一定要做到幂等性，否则会出现重复

刺骨的言语ヽ痛彻心扉/ 2024年04月07日 13:38/ 0 赞/ 165 阅读

相关如何设计一个高质量的 API 接口？

你是否也感同身受？对接XX业务时，XX业务具备的功能和API全靠跑业务负责人那反复逐个询问、确认。用哪个API；怎么用；有没有限制；等等各个业务间，甚至同

清疚/ 2023年10月15日 14:31/ 0 赞/ 165 阅读

相关设计一个高质量的 API 接口

你是否也感同身受？对接XX业务时，XX业务具备的功能和API全靠跑业务负责人那反复逐个询问、确认。用哪个API；怎么用；有没有限制；等等各个业务间，甚至同一业务内，

今天药忘吃喽~/ 2023年09月29日 13:34/ 0 赞/ 118 阅读

相关如何设计一个好的接口/API

如何设计一个好的接口/API 1. 引言如果说好的 UI 设计可以让用户更容易地使用一款产品，那么，好的 API 设计则可以让其他开发者更高效地使用一个系统的能力

悠悠/ 2023年07月14日 10:36/ 0 赞/ 207 阅读

相关如何设计一个安全逼格高的接口？

如何设计一个安全的对外接口？ <table> <thead> <tr> <th><strong>序号</strong></th> <th><stro

约定不等于承诺〃/ 2022年10月19日 04:29/ 0 赞/ 383 阅读

相关如何编写高质量前端设计文档？

大厂技术高级前端 Node进阶点击上方程序员成长指北，关注公众号回复1，加入高级Node交流群 ![f89e5b61b6e2653260ca2e2

红太狼/ 2022年09月10日 03:22/ 0 赞/ 301 阅读

相关如何设计高并发接口？

01 并发队列的选择 Java的并发包提供了三个常用的并发队列实现，分别是：ArrayBlockingQueue、ConcurrentLinkedQueue 和 Linke

以你之姓@/ 2022年04月01日 05:51/ 0 赞/ 608 阅读

相关如何设计一个牛逼的API接口

在日常开发中，总会接触到各种接口。前后端数据传输接口，第三方业务平台接口。一个平台的前后端数据传输接口一般都会在内网环境下通信，而且会使用安全框架，所以安全性可以得到很好的保护

系统管理员/ 2021年09月18日 06:04/ 0 赞/ 522 阅读

相关如何设计一个牛逼的 API 接口

在日常开发中，总会接触到各种接口。前后端数据传输接口，第三方业务平台接口。一个平台的前后端数据传输接口一般都会在内网环境下通信，而且会使用安全框架，所以安全性可以得到很好的保护

淡淡的烟草味﹌/ 2021年09月02日 04:54/ 0 赞/ 636 阅读

相关如何设计一个良好的接口

预计阅读时间：7 min 在设计接口时，有很多因素要考虑，如接口的业务定位，接口的安全性，接口的可扩展性、接口的稳定性、接口的跨域性、接口的协议规则、接口的路径规则、接口单一

小鱼儿/ 2021年07月31日 11:46/ 0 赞/ 655 阅读