如何把一个接口设计好? | 京东云技术团队
如何设计一个接口?是在我们日常开发或者面试时经常问及的一个话题。
很多人觉得这不就是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对齐方案。实现需求的过程中,有什么问题,需要及时跟产品沟通。需要跟客户端对齐接口,一定不能上来就自己埋头把接口定义完了。种种场景,学会沟通是非常重要的,有效、高效沟通不仅会带来愉悦心情,开发起来很顺畅,也会提高人际关系。
好啦,以上就是根据自身经验,对“如何设计一个接口?”问题的小小回答,如有不足,敬请指教。
作者:京东零售 李泽阳
来源:京东云开发者社区 转载请注明来源
低调大师中文资讯倾力打造互联网数据资讯、行业资源、电子商务、移动互联网、网络营销平台。
持续更新报道IT业界、互联网、市场资讯、驱动更新,是最及时权威的产业资讯及硬件资讯报道平台。
转载内容版权归作者及来源网站所有,本站原创内容转载请注明来源。
- 上一篇
GaussDB数据库SQL系列-UNION & UNION ALL
目录 一、前言 二、GaussDB UNION/UNION ALL 1、GaussDB UNION 操作符 2、语法定义 三、GaussDB实验示例 1、创建实验表 2、合并且除重(UNION) 3、合并不除重(UNION ALL) 4、合并带有WHERE子句SQL结果集(UNION ALL) 5、业务逻辑除重后合并(UNION ALL) 四、GaussDB UNION常见错误 1、“each UNION query must have the same number of columns” 2、“UNION types timestamp without time zone and text cannot be matched” 五、小结 一、前言 SQL(结构化查询语言)是一种用于管理关系型数据库的标准语言。它允许用户通过使用SQL语言来操作数据库中的数据。而在SQL中,UNION是一个非常强大的功能,它可以将多个SELECT语句的结果合并成一个结果集。本文将以GaussDB数据库为例,介绍一下UNION操作符的使用。 二、GaussDB UNION/UNION ALL 1、Gau...
- 下一篇
【案例分享】OneOS带你玩转高精度定位组件
一、服务简介 OneOS高精度定位服务基于中移智行的高精度定位平台,可以为搭载OneOS的物联网硬件提供最高动态厘米级、静态毫米级的卫星定位能力;并且针对性优化了物联网硬件在使用差分服务时资源占用过大的问题。包含三种服务:厘米级RTK、亚米级RTK、亚米级RTD,开发者可根据使用场景和硬件配置灵活选用相应服务。服务详细介绍如下: 二、高精度定位组件 OneOS高精度定位组件是一种端云融合组件,需要搭配OneOS的CMS(China Mobile Service,即中国移动服务框架,是中国移动OneOS操作系统服务合集)服务平台使用,搭载OneOS的物联网端侧使用CMS组件接入平台后即可使用高精度定位功能。OneOS中高精度定位组件具体配置开启方式参考文档。 1、环境准备 本次采用OneOS万耦创世开发板(STM32L475VGT6) + 蜂窝模组(ML302)+ GNSS模块(ublox-f9p)的方案进行演示! (1)OneOS下载 地址:https://os.iot.10086.cn/download/ (2)OneOS Cube下载并安装 地址:https://os.iot.1...
相关文章
文章评论
共有0条评论来说两句吧...
文章二维码
点击排行
推荐阅读
最新文章
- CentOS关闭SELinux安全模块
- SpringBoot2更换Tomcat为Jetty,小型站点的福音
- CentOS7安装Docker,走上虚拟化容器引擎之路
- Springboot2将连接池hikari替换为druid,体验最强大的数据库连接池
- CentOS7编译安装Cmake3.16.3,解决mysql等软件编译问题
- SpringBoot2整合Thymeleaf,官方推荐html解决方案
- Docker快速安装Oracle11G,搭建oracle11g学习环境
- CentOS8编译安装MySQL8.0.19
- CentOS7,8上快速安装Gitea,搭建Git服务器
- Hadoop3单机部署,实现最简伪集群