关于接口:如何把一个接口设计好-京东云技术团队
如何设计一个接口？是在咱们日常开发或者面试时常常问及的一个话题。 很多人感觉这不就是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对齐计划。实现需求的过程中，有什么问题，须要及时跟产品沟通。须要跟客户端对齐接口，肯定不能上来就本人埋头把接口定义完了。种种场景，学会沟通是十分重要的，无效、高效沟通不仅会带来愉悦情绪，开发起来很顺畅，也会进步人际关系。 好啦，以上就是依据本身教训，对“如何设计一个接口？”问题的小小答复，如有有余，敬请指教。 作者：京东批发 李泽阳 起源：京东云开发者社区 转载请注明起源