API设计的一点思路

Wesley13
• 阅读 346

API是模块或者子系统之间交互的接口定义。好的系统架构离不开好的API设计,而一个设计不够完善的API则注定会导致系统的后续发展和维护非常困难。

以下谈一点API设计的原则。

业务层

业务语义简单明确

一个接口或者说一个api,必定是为外部使用者服务的,因此必须具有明确的业务/使用意图。api的从命名到定义,都必须围绕着这个意图来进行设计,简单明确的命名/参数设计是一个好的api设计的第一步。

定义抽象,稳定,允许多个实现

API的设计需要注意的是,我们给出的api,实际上给出的是一个契约,由于业务实现/系统迭代的关系,内部的实现时常在变化的,但是契约的本质是没有变化的,因此我们定义api的时候,必须要进行一定程度的抽象,能够保证稳定的业务语义。最常见的方式就是,我这个api定义之后,如何方便的进行替换实现,并且外部的服务使用者是不感知我的变化的。

API定义的粒度

这里一个API的设计,至少需要保证原子服务的能力,但是很多情况下,服务调用方并不关心相关的原子服务能力,他所关心的是一个业务的处理。那么这个时候的情况下,我们的需要提供多个维度的api,使用门面模式进行原子能力的封装。

技术层

幂等

一个api的设计必须要进行幂等性设计,幂等性指的是多次的操作不影响第一次操作的结果;那我们常说的curd来说,Query接口具有天生的幂等性;Create多次调用的话容易存在重复创建,因此常用的做法是api设计有uk字段,显示或这个隐式的都可以,客户端必须要保证多次调用这个uk生成是唯一的;update进行幂等,常用的存在状态的话,会用乐观锁来进行校验,或者使用版本号的方式来进行判断;Delete的方式,其实delete多次调用不存在影响第一次调用的情况,只是会带来删除不存在的数据的一个错误提示的问题,这个可以和调用方进行约定,一定意义上,delete操作也是具有幂等性,无需做特殊的处理;

兼容

这个不用说了,api版本的升级,必须要考虑向下兼容;

批量处理

服务端是否提供批量处理的能力,这个一直是有争议的。我们先来看下服务端批量更新的优势和坏处,再根据具体的场景来选择是否进行服务端批量更新;

优势

1、性能的提升

一定程度上面可以进行性能的优化,比如我可以对批次数据进行划分,多线程进行处理,减少远程交互带来的网络开销等;

2、系统负载的转移

客户端的负载转移到服务端,服务端天生是需要进行这么多数据的处理,只是原先是在客户端进行流量的控制,甚至是批量的调用,现在转移到服务端进行批次处理了

3、客户端业务语义简化

批量处理,客户端不用关心一个业务聚合语义上面的数据的完整性和一致性,这部分交由服务端进行统一处理。客户端只需要关注数据结果,制定相关的重试策略即可。

劣势

1、带来了语义上的复杂性

全部成功,部分成功,全部失败,多种状态的处理,需要交由客户端进行处理,并且客户端很多情况下需要关注哪些成功,哪些失败,对于失败的数据需要明细的数据,这样就带来了接口语义的复杂性,丧失了api的简单的原则。

2、幂等处理的复杂性

如同上述,幂等处理需要考虑多数据之间的关联影响,部分成功处理的幂等性如何处理。

3、事务处理的复杂性

对于很多的客户端来说,一批次的数据不具有聚合关系,是允许存在数据状态不一致的(当然这种情况,可以将批量接口作为原子接口使用),并且由于实现的可替换性,是否支持批量的事务性这个需要进行考量

4、性能挑战

服务端实现批量处理,对于批次数据会对服务端带来性能上的挑战,并且不能对客户端进行约束,客户端滥用可能会导致性能问题的进一步恶化。

接口异常规范

需要具有比较粗力度的表示接口成功失败的字段,也有比较具体的明细信息,使用统一的异常码(常见并且精简的);

其他

API接口参数不要过多,不要具有相同参数类型参数,最好进行对象传递,进行防呆处理。

点赞
收藏
评论区
推荐文章
技术小男生 技术小男生
4个月前
linux环境jdk环境变量配置
1:编辑系统配置文件vi/etc/profile2:按字母键i进入编辑模式,在最底部添加内容:JAVAHOME/opt/jdk1.8.0152CLASSPATH.:$JAVAHOME/lib/dt.jar:$JAVAHOME/lib/tools.jarPATH$JAVAHOME/bin:$PATH3:生效配置
光头强的博客 光头强的博客
4个月前
Java面向对象试题
1、请创建一个Animal动物类,要求有方法eat()方法,方法输出一条语句“吃东西”。创建一个接口A,接口里有一个抽象方法fly()。创建一个Bird类继承Animal类并实现接口A里的方法输出一条有语句“鸟儿飞翔”,重写eat()方法输出一条语句“鸟儿吃虫”。在Test类中向上转型创建b对象,调用eat方法。然后向下转型调用eat()方
kenx kenx
1年前
个人博客开发之blog-api项目统一结果集api封装
前言由于返回jsonapi格式接口,所以我们需要通过javabean封装一个统一数据返回格式,便于和前端约定交互,状态码枚举ResultCodejavapackagecn.soboys.core.ret;importlombok.Getter;/@authorkenx@version1.0@date2021/6/1715:35
Stella981 Stella981
1年前
Jenkins API Token
JenkinsRESTAPI提供了APItoken,使得可以在程序中使用APItoken进行认证(而不是使用你真实的密码)。APItoken可以在用户个人设置界面查看到用户→用户id→设置页面,在APIToken区域点击ShowAPItoken按钮,便可查看APItoken,同时还可以更改APItoken相应的URL是
Stella981 Stella981
1年前
Android SDK和API Level对照表
Android平台版本对应的APILevel的对照表,经常会用到,又老记不住,这里就记录下,自己备忘,也给需要的人人参考,如果有错误或者遗漏,请大家给我评论,我会及时更新这个对照表的~系统版本和APILevel对照表(谢谢熊哥~)CodenameVersionAPIlevel(nocodename)1.
Stella981 Stella981
1年前
Duang,HUAWEI DevEco IDE全面升级啦
想感受全新UI带来的视觉及交互体验、HiKey970开发板调测、HiAIAPI推荐和收藏、深度AI模型分析等新功能,体验高清晰度和流畅度的远程AI真机调测吗?!(https://oscimg.oschina.net/oscnet/f4e1bb24ff00b8c6ea27f75370a53bfbacd.jpg)全新的UI设计
liam liam
9个月前
谁在从API经济里分得一杯羹!
从ApiHub说开去前阵子机缘巧合下载了个趁手的接口设计和调试管理工具——Apifox(),工具虽然小众,目前也才迭代了几个版本,但是产品里已经开辟了ApiHub模块来收集其他企业的开放Api。我看到快手开放API,企业微信,钉钉开放API等好几十个研发协同,效率管理和生活服务类的接口文档已经先行被收录进去了,目前提交的开放API项目数量还在缓慢增加。不得
liam liam
6个月前
如何模拟后台API调用场景,很细!
简介在开发前后台分离项目并且通过不同团队来实现的时候,如何将后台设计的API准确的传达到前台,是一个非常重要的工作。为了简化这个过程,开源社区做了很多努力,比如protobuf技术,swagger的诞生,以及后面openapi的演化,都在试图解决API描述和文档的问题。这些标准某些程度上大大简化了API文档的撰写和维护,但是API设计往
高性能API网关Kong介绍
本文关键词:高性能、API网关、Kong、微服务1.Introduction是随着微服务(Microservice)概念兴起的一种架构模式。原本一个庞大的单体应用(Allinone)业务系统被拆分成许多微服务(Microservice)系统进行独立的维护和部署,服务拆分带来的变化是API的规模成倍增长,API的管理难度也在日益增加,使用API网关发布和管
liam liam
7个月前
为什么越来越多的开发者放弃使用Postman,而选择Apifox
一、API调试常用解决方案1、PostmanSwaggerMockJMeter作为一个后端开发,我做的大部分项目一般都是基于Swagger来管理API文档,基于Postman来做接口调试,基于JMeter来做接口性能测试,基于RAP等工具MockAPI数据。\2、存在的问题(1)多系统数据不互通API设计者、前