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

news2024/11/16 13:41:00

你是否也感同身受？

优秀API的特质

自解释

易学习

易使用

难误用

API 设计原则

1. 充分原则

2. 单一视角原则

3. 单一功能原则

4. 简单原则

5. 抽象原则

6. 兼容扩展原则

7. 最小惊讶原则

8. 低耦合原则

9. 正交原则

10. 易测试原则

11. 统一原则

总结：

你是否也感同身受？

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

API编码规范迫在眉睫

基于 Spring Boot + MyBatis Plus + Vue & Element 实现的后台管理系统 + 用户小程序，支持 RBAC 动态权限、多租户、数据权限、工作流、三方登录、支付、短信、商城等功能。

项目地址：https://github.com/YunaiV/ruoyi-vue-pro

优秀API的特质

自解释

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

易学习

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

易使用

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

难误用

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

基于微服务的思想，构建在 B2C 电商场景下的项目实战。核心技术栈，是 Spring Boot + Dubbo 。未来，会重构成 Spring Cloud Alibaba 。

项目地址：https://github.com/YunaiV/onemall

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

总结：

感谢每一个认真阅读我文章的人！！！

我个人整理了我这几年软件测试生涯整理的一些技术资料，包含：电子书，简历模块，各种工作模板，面试宝典，自学项目等。欢迎大家点击下方名片免费领取，千万不要错过哦。

Python自动化测试学习交流群：全套自动化测试面试简历学习资料获取点击链接加入群聊【python自动化测试交流】：http://qm.qq.com/cgi-bin/qm/qr?_wv=1027&k=DhOSZDNS-qzT5QKbFQMsfJ7DsrFfKpOF&authKey=eBt%2BF%2FBK81lVLcsLKaFqnvDAVA8IdNsGC7J0YV73w8V%2FJpdbby66r7vJ1rsPIifg&noverify=0&group_code=198408628