乐趣区

关于接口:如何把一个接口设计好-京东云技术团队

如何设计一个接口?是在咱们日常开发或者面试时常常问及的一个话题。

很多人感觉这不就是 CRUD,能实现不就行了。单纯实现来说,并非难事,但要做到易用、易扩大、易保护并不是一件简略的事。这里并不强调一些个接口设计的准则或者设计办法,仅从如何设计一个好的接口登程,简略探讨。

1、命名标准

咱们写代码,不仅仅是为了实现以后的性能,也要有利于前面的保护。所谓的保护,就是代码不仅仅是写给本人看的,也是给他人看的。所以接口定义要清晰易懂、命名标准。

除了接口、办法、出入参命名标准,也要留神代码标准问题。一开始接触到各种代码坏滋味的小伙伴,大多都会感觉这些标准很多余、很烦人,但实际上,这些好的编码习惯是让大家都能依照根本规约开发,易于浏览易于保护的根底。

在接口定义时,也请留神接口性能的单一性。其实这也是微服务的一些思维,接口性能的繁多职责、明确简略。比方登录接口,它做的事件就是校验账户名和明码相干;订单服务、积分服务、商品信息相干的接口都是划分开的。

2、参数校验

入参出参校验是每个程序员必备的根本素养。你设计的接口,必须先校验参数。比方入参是否容许为空、入参长度要求、入参是否在枚举值范畴内等等。日常开发中,很多低级 bug 都是不校验参数导致的。

提到参数,就必须提到接口状态和错误码。无论是失败还是胜利,一个齐备的接口都应该通知调用方返回信息。如果接口失败,具体失败的起因是什么,这就须要定义明确的错误码和对应形容。同时,尽量对报错信息进行封装,不要间接将服务端异样信息抛出去。

3、监控 / 性能

如何评判一个接口的性能就必须要有监控,这对于服务端监督接口性能和异样报警至关重要。调用次数、可用率、TP99、TP999 等监督指标,极其重要的外围接口,还须要细分至秒级监控加以标识。

一个接口的性能不单单只看本人业务逻辑,内部近程调用也是耗费性能的重要局部。如果你调用第三方接口或者近程服务,就须要思考异样和超时。如果异样了,怎么解决,是重试还是当作失败还是告警解决。如果重试,重试几次?这就须要站在业务角度思考这个问题。这些措施也是间接影响以后接口性能。

进步性能的利器还能够思考缓存。缓存用得好,能够承载更多的申请,晋升查问效率,缩小数据库的压力。然而应用缓存须要思考缓存和数据库一致性保障、缓存击穿等问题。

4、日志

接口的要害代码,要有日志的保驾护航。首先日志级别须要正当应用:error > warn > info > debug。

其次日志信息蕴含哪些呢,外围代码块调用前的入参打印、接口调用后的异样捕捉日志等。须要留神的是,如果日志中波及比拟大的 JSON 富文本,请应用 log.isInfoEnable(),在高并发和简单 log 信息拼接的状况下,应用这种规范的办法输入 log 可能省去不小的零碎开销。另外,如果结构 log 信息的过程须要大量字符串操作,倡议应用 StringBuilder 来实现字符串拼接。

5、异样 / 超时

实现一个好的接口,离不开优雅的异样解决。比方异样匹配的程序,优先捕捉具体的异样;应用流时记得应用 finally 敞开流资源;

对于运行时谬误,比方数据边界越界、空指针也在日常开发中呈现,该判断、该校验的还是一项不能少哦。

超时问题也常常会导致接口不可用。设置正当的超时工夫,也是在爱护你的接口。超时个别与重试搭配应用,不过请留神,设置超时工夫时,须要充分考虑你的上下游设置的超时工夫。比方一个申请率先拜访你的上游,而你的上游设置的超时工夫是 500ms,上游调用你的接口,但你设置的超时是 2000ms,这其实就是有效超时工夫。

对于接口耗时优化,也是有一些伎俩的,比方近程串行改为并行调用、单次调用改为批量调用等等。但请留神尽量不在循环或者事务里近程调用。

6、异步

接口有些场景,应用异步更正当。举个简略的例子,对于一些经营操作的接口,往往须要记录对应操作的操作日志,记录下是谁在什么工夫操作了什么对象,便于追踪“事发现场”。然而记录操作日志并不在接口主流程上,记录操作日志是否成功失败也不应该影响失常主流程的执行,这个时候就应该思考用音讯队列等形式进行异步解耦。

7、正文

能够说,正文也是良好代码的重要组成部分。有些人,始终置信 show me the code,却不想写一行正文,认为没有必要。然而你无奈保障代码逻辑始终清晰、高效。如果是比较复杂的话,就倡议把正文写分明,这对于后续保护和缕清代码逻辑很重要。

8、降级 / 限流

现在的申请调用根本都是分布式调用链路,当分布式系统中某个根底服务不可用时,就会最终导致整个零碎不可用,所以当上游零碎或者本身服务呈现问题时,肯定要思考降级。如果做的更齐备的话,还能够思考熔断。

同时,针对高并发的流量洪峰接口,必须思考限流应答超出零碎的承载能力挑战。限流措施也同样能够限度爬虫,爱护零碎,抛弃多余的申请。

9、平安

这里说的平安,范畴可太大了。比方线性平安,很多人反手上来就是 HashMap,因为它是非线性平安的,能够思考高并发下的 ConcurrentHashMap。

如果前端反复申请,你的逻辑如何解决?是不是思考接口去重解决(有时候是防刷解决)。简略点,能够应用 redis 防重解决,同样的申请,肯定工夫距离内进行过滤。当然,对于一些并发不高的接口,比方转账类接口,举荐应用数据库主键或者惟一索引。

如果音讯队列呈现反复生产的状况,你的业务逻辑怎么管制?是不是思考幂等性校验。

防重次要为了防止产生反复数据,把反复申请拦挡下来即可。而幂等设计除了拦挡曾经解决的申请,还要求每次雷同的申请都返回一样的后果。不过很多时候,它们的解决流程和形式是相似的。

还有一些其余平安方面的思考,比方读写拆散、代码锁的粒度管制、数据加密等等。

10、沟通

为什么要有沟通?又为什么把沟通放在最初呢?遇到一些技术难题,跟技术 leader 对齐计划。实现需求的过程中,有什么问题,须要及时跟产品沟通。须要跟客户端对齐接口,肯定不能上来就本人埋头把接口定义完了。种种场景,学会沟通是十分重要的,无效、高效沟通不仅会带来愉悦情绪,开发起来很顺畅,也会进步人际关系。

好啦,以上就是依据本身教训,对“如何设计一个接口?”问题的小小答复,如有有余,敬请指教。

作者:京东批发 李泽阳

起源:京东云开发者社区 转载请注明起源

退出移动版