您当前的位置:首页 > 电脑百科 > 程序开发 > 编程百科

接口设计技巧和最佳实践

时间:2019-09-05 13:51:51  来源:  作者:

这篇文章是从人们在设计和实现接口时常见的和常被无视的错误,总结出来的一些技巧和最佳实践

1、严格的数据模型层

 

你的响应应该是在代码中严格定义的嵌套数据业务模型,不要依赖数据库查询结果映射,或者其他操作

2、无歧义的服务名

 

记住你的URL应该能充分表达出真实作用,而不是需要翻阅文档才能了解,另外不要不情愿使用版本号命名路由,当然服务版本应该要做到向下兼容

3、数据类型强一致

 

数值字段应该始终只包括数字,字符类型字体意义始终只包括字符串,同一个字段中不应该混合多种类型数据

4、始终返回所有的字段

 

不要删除字段属性,即使值为空

 

5、不要滥用JSON对象

 

API中的每个JSON对象应该始终在请求之间具有不可变性,具有严格的定义的字段集,下面这种返回就是可怕的做法

接口设计技巧和最佳实践

 

正确返回应该是

接口设计技巧和最佳实践

 

6、不要滥用JSON数组

当绝对无法避免在同一数组中返回不同类型实体时,尝试返回足够抽象的对象列表,里面包括所有对象,每个对象显示标明类型。比如飞机和汽车不应该出现在同一个返回数组中,但是无法避免时,可以使用下面这种方式

接口设计技巧和最佳实践

 

7、不要依赖普通的硬编码错误信息

接口返回错误时,在响应正文中应该包括严格定义的错误对象,对象一般包括内部代码和附加信息

8、不要使用数字枚举

9、不要返回非封装的响应

使用对象作为根响应容器以允许后续添加任意数量的字段而不会导致弃用,比如我们可以使用is_available布尔值标识book的状态,但是它没有表明为啥是不可用状态?什么时候会变得可用?如果将来需要增加其他信息,你将不得不修改根响应

10、使用JSON布尔值

11、尽量让你的接口满足HATEOAS 约束

服务器提供给客户端的表达中包含了动态的链接信息,客户端通过这些链接来发现可以触发状态转换的动作,资源的URI和其他信息都是动态发现的,当服务端发送变化时,客户端并不需要做出修改

12、考虑让你的接口结果可缓存

客户端可以缓存服务器返回的响应结果,服务器可以定义响应结果的缓存时长设置

13、为你的接口实现限流

API确实实施了速率限制的话,请务必通过响应提供其当前状态来告知你的调用者

14、考虑让你的接口返回支持字段过滤

客户端请求可以指定希望服务端在响应中包括哪些字段或者排除哪些字段,这样可以有效处理响应膨胀

15、接口支持高级分页

分页可以减少客户端接收的数据数目,但是当你需要将分页结果与不断接收的新条目结合时,通常的限制limit和偏移offset分页参数是低效的,因为每次当有个新条目在服务端被添加到先前的集合时,先前发送到客户端的偏移offset都变得无效,而且客户端无法得知在两次请求间新增了多少条目。保持客户端同步一个比较好的办法是使用before_id和after_id参数组合,比如客户端将已知的最新条目的id作为after_id请求参数,然后检索之后创建的新条目

16、接口异常显式返回

RPC调用中Exception应该也是返回值的一部分,应该设计成Checked Exception,尽量让调用方能够显式的处理

17、接口使用Specification规格模式

设计者应该避免太多findBy方法和各自的重载,正确的打开方式应该类似组合模式

接口设计技巧和最佳实践

 

18、为功能定义接口,不为个别使用方定义接口

定义好统一的路由接口,而非为每一个使用方定义个别处理,如果需要特殊字段,要考虑特殊字段的通用性,如果有通用性,在通用接口上加上字段,其他使用方可维持空,如果没有通用性,作为一个配置字段配置进去



Tags:接口   点击:()  评论:()
声明:本站部分内容来自互联网,转载是出于传递更多信息之目的,内容观点仅代表作者本人,如有任何标注错误或版权侵犯请与我们联系,我们将及时更正、删除,谢谢。
▌相关评论
发表评论 共有条评论
用户名: 密码:
验证码: 匿名发表
▌相关推荐
在6月中旬时,拼多多为了保障数据安全和运营信息安全,依据《拼多多开放平台开发者协议》等相关协议和规则,发布了对商家在使用API接口的时候开始收费的公告。 所谓API,百度百科...【详细内容】
2020-07-09   接口  点击:(3)  评论:(0)  加入收藏
现代电视具有一个或多个USB接口这一事实,早已成为每个人的习惯。但是,当USB采用另一种技术时,这通常会引发问题。因此,在我们的材料之一中,我们已经研究了为什么USB端口在路由器...【详细内容】
2020-06-29   接口  点击:(0)  评论:(0)  加入收藏
有没有遇到这样子的接口,放到互联网上面去,谁都可以调用,谁都可以访问,完全就是公开的,这样子的接口,如果只是普通的数据,其实可以考虑,只是可以考虑,但是,一般情况下,我们是不允许这样...【详细内容】
2020-06-20   接口  点击:(4)  评论:(0)  加入收藏
jmeter是apache公司基于java开发的一款开源压力测试工具,体积小,功能全,使用方便,是一个比较轻量级的测试工具,使用起来非常简单。因为jmeter是java开发的,所以运行的时候必须先要...【详细内容】
2020-06-18   接口  点击:(0)  评论:(0)  加入收藏
前篇文章介绍了Mock测试的相关理论知识,今天就通过实战操作来演示一下如何通过Fiddler抓包工具来Mock接口返回值。准备工作准备一个服务端接口,可以自己用SpringBoot写一个简...【详细内容】
2020-06-11   接口  点击:(6)  评论:(0)  加入收藏
大家在安装专业音响设备时,面对各式各样的设备音频接口类型,难免会有点晕头转向。接下来小编为大家介绍一下几种音频线接头,希望能在你选择音频线时提供一些帮助。013.5mm音频...【详细内容】
2020-06-09   接口  点击:(7)  评论:(0)  加入收藏
(一)实验拓扑及描述 1. 本拓扑环境共有2台路由器及2台PC;2. PC连接在接入交换机上,PC1属于vlan10,PC2属于vlan20;3. 设备接口编号与IP地址规划如图所示。(二)实验需求1. Vlan10及vla...【详细内容】
2020-06-06   接口  点击:(4)  评论:(0)  加入收藏
滑动验证是网站反爬虫、反作弊的升级,滑动验证也是机器学习在反爬虫、反作弊领域的应用; 本项目也是一个简单的全栈项目,使用tornado做的后端、Bootstrap4做的前端;核心的识别...【详细内容】
2020-06-04   接口  点击:(0)  评论:(0)  加入收藏
相信很多小伙伴都见过一些商业产品中的url接口响应时间,实时汇总显示功能。可以理解为web接口的慢查询,与sql的慢查询有异曲同工之妙,但是想做却无从入手不知道怎么实现此功能,...【详细内容】
2020-05-29   接口  点击:(4)  评论:(0)  加入收藏
为了统计访客数量来源所属地区,主要是省市的数量及其比例。网路上有多种免费的IP地址转换的服务,考虑了准确性,易用性,查询速率以及每日查询量,特推荐百度和腾讯的api以此文来总...【详细内容】
2020-05-29   接口  点击:(5)  评论:(0)  加入收藏
接口中通常都设置了一些用于数据、控制和状态缓存的寄存器,这些寄存器就是能够让CPU直接访问的I/O端口。为了便于CPU对外部设备的快速识别和选择,必须对接口中所有可访问的寄...【详细内容】
2020-05-25   接口  点击:(3)  评论:(0)  加入收藏
感谢大家的阅读,随着我们网络的提速,现在很多地方都使用光纤的网络(网络信号传输介质“光纤”到底有什么作用),那么问题来了,光纤猫(网络信号传输介质“光纤”到底有什么作用)的使用...【详细内容】
2020-05-23   接口  点击:(1)  评论:(0)  加入收藏
准备工作: 和风天气api接口的key(和风天气网址:https://www.heweather.com/)(注册账号-控制台-添加key) 2.安装axios依赖,npm install axios --save3.路由index.js配置 <template>...【详细内容】
2020-05-19   接口  点击:(0)  评论:(0)  加入收藏
问题描述某客户支队下辖3个单位需要做IP地址绑定1大队:xx.xx.xx.101-121 绑定1口 2大队:xx.xx.xx.122-142 绑定2口 3大队:xx.xx.xx.143-163 绑定3口要求每个单位只能使用分配...【详细内容】
2020-05-18   接口  点击:(12)  评论:(0)  加入收藏
关于音频接口的使用和链接什么是音频接口?音频接口是通过设备与接口的连接,从而进行音波处理,当然,音频接口也是多种多样的,下文就为大家讲解目前主流的音频接口:RCA模拟音频、S/...【详细内容】
2020-05-16   接口  点击:(2)  评论:(0)  加入收藏
随着HDMI的广泛使用,HDMI问题也随之产生。一方面,由于HDMI热插拔烧坏接口芯片的问题越来越多。另一方面,许多用户一直热插拔HDMI线,并且已经几十次或几百次没有烧毁设备了,那么问...【详细内容】
2020-05-14   接口  点击:(18)  评论:(0)  加入收藏
问题的起源在直播服务中,有一个敏感词的检测的需求:当用户发送聊天消息之前,调用接口验证消息是否包含敏感词,我们使用了阿里云的文本安全服务,这是一个按照次数收费的服务,所以接...【详细内容】
2020-05-13   接口  点击:(4)  评论:(0)  加入收藏
接口测试中的接口到底是什么?先看一道题,请找出以下可以被成为接口的选项:◆ USB◆ 水龙头◆ 用户界面UI◆ 函数◆ https://www.baidu.com◆ https://api.github.com接口的英文...【详细内容】
2020-05-03   接口  点击:(6)  评论:(0)  加入收藏
Loopback接口一、Loopback接口简介(环回接口) Loopback接口是虚拟接口,是一种纯软件性质的虚拟接口。任何送到该接口的网络数据报文都会被认为是送往设备自身的。大多数平台...【详细内容】
2020-05-02   接口  点击:(30)  评论:(0)  加入收藏
不知道开发的同学有没有遇到过类似这样的需求: 相同类型的数据在多个系统中,如果要得到全部的信息,就要连续调多个系统的接口; 业务复杂,一个需求需要关联几张表甚至几十张表才...【详细内容】
2020-04-17   接口  点击:(10)  评论:(0)  加入收藏
最新更新
栏目热门
栏目头条