设计一个高质量的 API 接口

news/2024/3/29 5:04:00/文章来源:https://blog.csdn.net/Noah_ZX/article/details/129123525

你是否也感同身受?

  • 对接XX业务时,XX业务具备的功能和API全靠跑业务负责人那反复逐个询问、确认。用哪个API;怎么用;有没有限制;等等

  • 各个业务间,甚至同一业务内,API风格不统一。

    • API命名: 按自然语义全翻译的;按属性角度定义的;按操作角度定义的;动宾、非动宾的;复数、非复数的;等等

    • API入参: 带Map的;相同语义字段名称不一样;

    • API出参: 有包装Resoponse的;直接返回结果数据的;相同数据,返回格式和字段名称有差别的;

    • 错误信息: 直接返回中文提示的;返回提示信息编码的;返回异常类型的;等等

  • XX业务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、抽象对象实体更宏观,具有更好的适用性、兼容性、扩展性。

了解更多的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提供方开发经验复用

  • 避免犯错,避免误用

     

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.luyixian.cn/news_show_71705.aspx

如若内容造成侵权/违法违规/事实不符,请联系dt猫网进行投诉反馈email:809451989@qq.com,一经查实,立即删除!

相关文章

如何快速、全面、深入地掌握一门编程语言

思考路线 如何快速? 什么样的Demo才能让人觉得你掌握了它? 空 判断:构造一个可以判断所有空的 is_empty 函数 for 循环:i 和 集合迭代两种 时间获取:年/月/日 时分秒 时间戳与时间格式互转 休眠时间函数 字符串处理…

Word控件Spire.Doc 【Table】教程(17):如何在 C#、VB.NET 中删除 Word 表格中的行和列

Spire.Doc for .NET是一款专门对 Word 文档进行操作的 .NET 类库。在于帮助开发人员无需安装 Microsoft Word情况下,轻松快捷高效地创建、编辑、转换和打印 Microsoft Word 文档。拥有近10年专业开发经验Spire系列办公文档开发工具,专注于创建、编辑、转…

PCB设计中降低噪声与电磁干扰的24个窍门

电子设备的灵敏度越来越高,这要求设备的抗干扰能力也越来越强,因此PCB设计也变得更加困难,如何提高PCB的抗干扰能力成为众多工程师们关注的重点问题之一。本文将介绍PCB设计中降低噪声与电磁干扰的一些小窍门。 下面是经过多年设计总结出来的…

大数据处理学习笔记1.3 使用Scala集成开发环境

文章目录零、本讲学习目标一、搭建Scala的IntelliJ IDEA开发环境(一)启动IDEA(二)安装Scala插件(三)配置IDEA使用的默认JDK(四)创建Scala项目1、创建Scala项目 - ScalaDemo2、创建Sc…

linux高级命令之死锁

死锁学习目标能够知道产生死锁的原因1. 死锁的概念死锁: 一直等待对方释放锁的情景就是死锁为了更好的理解死锁,来看一个现实生活的效果图:说明:现实社会中,男女双方一直等待对方先道歉的这种行为就好比是死锁。死锁的结果会造成应用程序的停止响应&…

【vue】elemente-ui table toggleRowSelection 默认选择无效[已解决]

项目场景: 点击按钮,弹出一个弹出框,内部出现一个table表,表内数据是动态获取,同时得勾选上几个table表的数据,类似以下的图 问题描述 点击按钮显示弹出框,加载table中的数据,默…

【机器学习】Adaboost

1.什么是Adaboost AdaBoost(adapt boost),自适应推进算法,属于Boosting方法的学习机制。是一种通过改变训练样本权重来学习多个弱分类器并进行线性结合的过程。它的自适应在于:被前一个基本分类器误分类的样本的权值会…

springboot整合Chat Generative Pre-trained Transformer

什么是Chat Generative Pre-trained Transformer Chat Generative Pre-trained Transformer,是以人工智能驱动的聊天机器人程序 ,已经更新多个版本,很多大厂也都在接入其API。 整合难度 难度一颗星,基本上就是给官方API发请求&am…

在VMware Workstation中配置固定IP、在VMware Fusion中配置固定IP

1、在VMware Workstation中配置固定IP 配置固定IP需要2个大步骤: 1.在VMware Workstation(或Fusion)中配置IP地址网关和网段(IP地址的范围) 首先让我们,先进行第一步,跟随图片进行操作 现在进…

基于某业务单登陆场景并发测试实战

文章目录1 测试目的2 测试目标和测试对象3 名词解释4 测试说明5 测试环境和工具5.1 测试工具5.2 测试环境5.3 人力计划6 测试用例6.1 方案设计6.2 接口地址6.3 接口参数6.3.1 header参数6.3.2 请求参数7 脚本设计8 监控数据8.1 虚拟用户并发情况8.2 事务响应时间8.3 每秒点击次…

面试攻略,Java 基础面试 100 问(十二)

如何将字符串转换为基本数据类型? 调用基本数据类型对应的包装类中的方法 parseXXX(String)或 valueOf(String)即可返回相应基本类型; 如何将基本数据类型转换为字符串? 一种方法是将基本数据类型与空字符串(””)连…

微服务03 分布式搜索引擎 elasticsearch ELK kibana RestAPI RestClient

分布式搜索引擎01-- elasticsearch基础0.学习目标1.初识elasticsearch1.1.了解ES1.1.1.elasticsearch的作用elasticsearch是一款非常强大的开源搜索引擎,具备非常多强大功能,可以帮助我们从海量数据中快速找到需要的内容例如:在GitHub搜索代码…

半年前学习了性能测试涨薪5k, 经验+技术积累+坚持很重要

做测试一年多来,虽然平时的工作都能很好的完成,但最近突然发现自己在关于测试的整体知识体系上面的了解很是欠缺,所以,在工作之余也做了一些测试方面的知识的补充。不足之处,还请大家多多交流,互相学习。现…

系列三、docker相关指令

一、docker指令 1.1、查看docker详细信息 docker info 1.2、查看docker版本 docker version 1.3、帮助命令 docker --help 二、images指令 2.1、查看本地仓库中有哪些镜像 docker images 2.2、下载新的镜像 # 语法 docker pull 镜像名:版本号# 案例 docker pull mysql…

Node.js安装配置及Angular CLI的安装

NodeJS的安装node.js官网下载地址: https://nodejs.org/en/download/在node.js的官网上面下载适合自己机型的,如果是Windows系统的话,建议下载对应的 Windows Installer (.msi) 。下载完成后,双击打开安装,安装路径最好自定义&…

12款适合小团队协作、任务管理和进度跟踪的在线任务管理的工具推荐?

国内外12款主流任务管理软件测评: 1.开发任务管理PingCode; 2.多合一项目任务管理Worktile;3.个人和小团队项目任务管理Notion; 4.企业任务管理平台SmartTask; 5.小团队任务管理Teambition;6.IT任务追踪管理Jira等。无论是做好工作任务管理还是个人任务管理,从来都不…

Flink-多流转换(Union、Connect、Join)

文章目录多流转换分流基本合流操作联合(Union)连接(Connect)基于时间的合流——双流联结(Join)窗口联结(Window Join)间隔联结(Interval Join)窗口同组联结&a…

Git复习

1. 引言 现在要用到Git,复习一下关于Git的指令,知识摘自《Pro Git》 2. 起步 git和其他版本控制软件最大的差别在于git是直接记录某个版本的快照,而不是逐渐地比较差异。 安装: sudo apt install git-all设置用户信息: git c…

Vue3搭建记录

一、初始化项目:项目名称vue3-element-admin npm init vitelatest vue3-element-admin --template vue-ts 二、整合Element-Plus 1.本地安装Element Plus和图标组件 npm install element-plus npm install element-plus/icons-vue 2.全局注册组件 // main.ts imp…

【LeetCode】No.232. 用栈实现队列 -- Java Version

题目链接:https://leetcode.cn/problems/implement-queue-using-stacks/ 1. 题目介绍(232. 用栈实现队列) 请你仅使用两个栈实现先入先出队列。队列应当支持一般队列支持的所有操作(push、pop、peek、empty)&#xff…