API接口知识小结

应用程序接口API（Application Programming Interface），是提供特定业务输出能力、连接不同系统的一种约定。这里包括外部系统与提供服务的系统（中后台系统）或后台不同系统之间的交互点。包括外部接口、内部接口，内部接口又包括：上层服务与下层服务接口、同级接口。

如果不想被视为技术大佬眼中什么都不懂的需求搬运工，清楚接口的相关知识是很有必要的。

常见web接口是http/https协议的接口，多用于外部系统或前端系统的调用，因为此类接口地址要暴露在外部，所以必须对接口的安全性做较高程度的校验。还要一种基于开源rpc构建的跨系统接口调用接口方案，此类主要用于大公司内网各系统间的互相调用，此类接口服务治理能力更强，接口相应速度更块。以下内容以http接口为例展开的讨论。

一、接口请求方式类型

常见的http请求方式包括：get（查）、post（增），除此之外还有put（改）、delete（删）等。接口所属类型是由业务决定的。比如你打开淘宝，展示的首页内容就需要用到get接口，获取页面信息，你看中了宝贝要下单，添加你的收获地址时，用的则是post接口。而这两种也是其中最常见的两种接口类型

1）get类型接口

格式：请求数参数写在网址后面，用”?”连接，多个参数之间用”&”连接。

场景：get型接口用于获取信息，多用于查询数据，如菜单列表展示，搜索展示，订单查询，优惠券查询等需要其他系统返回数据时使用。一般情况下请求的数据量较小，返回速度快，不过接口是暴露在外面的，所以会有一定的风险。

2）post型接口

说明：向指定资源位置提交数据（如提交表单、上传文件）来进行请求，post请求可能会导致新资源的建立。

场景：如注册、上传、发帖等功能，这种请求数据量大，安全性要求高。

其他接口类型如put（改）、delete（删）、patch等使用评率稍低一些，此处不再赘述。

二、接口响应机制类型

从返回上区分，分为 同步接口、异步接口

1）同步交互

指发送一个请求,需要等待返回,然后才能够发送下一个请求，有个等待过程；

比如登录接口，执行登录操作时，将用户名、密码、token等字段加密后通过接口校验，需要返回验证结果后，才能登录成功。

2）异步交互

指发送一个请求,不需要等待返回,随时可以再发送下一个请求，即不需要等待。

如用户领导优惠券，只需要将用户的领券行为请求成功，资产系统收到请求后异步操作用户发券，通过异步的方法执行发券，调用方无须等待每个请求的调用结果。

区别：一个需要等待，一个不需要等待，在不影响用户体验的情况下，我们的项目开发中一般会优先选择不需要等待的异步交互方式。

哪些情况建议使用同步交互呢？比如用户登录、银行的转账系统，对数据库的保存操作等等，都会使用同步交互操作，其余情况都优先使用异步交互。

三、接口的触发形式类型

1）分发接口

一个系统产生新数据的时候就分发给其它系统（也可以是多个）。

中台系统的核心思想是高内聚、低耦合，所以分发接口的使用场景还是比较多的。比如有一个主渠道系统来管理所有的渠道数据，而渠道数据是其他系统如商品系统、促销系统经常要使用到的信息。所以一旦出现新的渠道或者发生渠道变更，需要分发给其他所有对接了各个系统，实现对最新渠道的功能支撑。

2）订阅接口

一个系统在需要的时候调用其他系统的接口进行数据订阅。

比如订单系统生成订单时，因为很多外部系统可能需要及时获取订单状态信息。而订单系统也不知道要分发给哪些系统，这时候一般会将订单推送至特定的消息队列，比如KFK，其他由需要跟进订单状态的的系统订阅KFK消息后，可以即使获取订单完成信息，进行触发下一个动作。

四、其他API接口基本组成

再既定的业务下，接口请求类型、响应机制等确定后，再以京东详情API为例，了解下接口的其他组成内容。

1）应用场景

顾名思义，此接口适用于的场景，明确接口的业务用途。

京东详情API的应用场景主要包括以下几个方面：

1. 获取商品信息：通过调用京东详情API，开发者可以快速获取商品的基本信息、图片、规格参数等，这有助于在自有平台上构建与京东商品详情页类似的页面，提升用户体验。
2. 支持购买决策：商品详情API提供的评论和评价信息可以帮助用户判断商品的质量和性价比，从而做出更准确的购买决策。
3. 实现数据同步：商家可以利用API实时更新商品信息，确保在多个平台上的商品信息保持一致，避免因信息不一致而导致的订单错误和消费者投诉。
4. 优化销售策略：通过分析API提供的销售数据，商家可以了解消费者的购买行为和喜好，进而调整销售策略，优化商品组合和定价策略。
5. 进行竞品分析：商家可以通过API获取竞品的详细信息和销售数据，进行市场研究，了解市场需求和消费者喜好，制定更有效的销售策略。

2）入参及出参

公共参数

​​前往测试接口​​

名称	类型	必须	描述
key	String	是	调用key（必须以GET方式拼接在URL中）
secret	String	是	调用密钥
api_name	String	是	API接口名称（包括在请求地址中）[item_search,item_get,item_search_shop等]
cache	String	否	[yes,no]默认yes，将调用缓存的数据，速度比较快
result_type	String	否	[json,jsonu,xml,serialize,var_export]返回数据格式，默认为json，jsonu输出的内容中文可以直接阅读
lang	String	否	[cn,en,ru]翻译语言，默认cn简体中文
version	String	否	API版本

请求参数

请求参数：num_iid=10335871600

参数说明：num_iid:JD商品ID

响应参数

Version: Date:

名称	类型	必须	示例值	描述
item	item[]	0		获得JD商品详情
num_iid	Bigint	0		商品ID
title	String	0		商品标题
desc_short	String	0		商品简介
price	Float	0		价格
total_price	Float	0
suggestive_price	Float	0
orginal_price	Float	0		原价
nick	String	0		掌柜昵称
num	Int	0		库存
min_num	Int	0
detail_url	String	0		商品链接
pic_url	String	0		商品图片
brand	String	0		品牌名称
brandId	Int	0		品牌ID
rootCatId	Int	0		顶级分类ID
cid	Int	0		分类ID
crumbs	Mix	0
created_time	String	0
modified_time	String	0
delist_time	String	0
desc	String	0
desc_img	Mix	0
item_imgs	Mix	0		商品图片
item_weight	String	0
item_size	String	0
location	String	0		发货地
post_fee	Float	0		物流费用
express_fee	Float	0		快递费用
ems_fee	Float	0		EMS费用
shipping_to	String	0		发货至
has_discount	Boolean	0
video	Mix	0		商品视频
is_virtual	String	0
sample_id	String	0		商品风格标识ID
is_promotion	Boolean	0
props_name	String	0		商品属性名
prop_imgs	Mix	0		商品属性图片列表
property_alias	String	0		商品属性别名
props	Mix	0		商品详情
total_sold	Int	0
skus	Mix	0		商品规格信息
seller_id	Int	0		卖家ID
sales	Int	0		销量
shop_id	Int	0		店铺ID
props_list	Mix	0		商品属性
seller_info	Mix	0		卖家信息
tmall	Boolean	0		是否天猫
error	String	0		错误信息
warning	String	0		警告信息
url_log	Mix	0
props_img	Mix	0		属性图片
shop_item	Mix	0
relate_items	Mix	0

入参是接口请求所需要的变量参数，其中包括必填参数和非必填参数，非必填并非是可以忽略的，比如上面的入参中，签名类型为非必填，如果未传此参数，则默认此签名类型为MD5，如果使用的并非此类签名类型，则此项为必填项。如果是普通订单查询，入参时间非必填，则返回结果是用户全部订单，或者用户特定时间订单的区别。

3）错误码

状态代码(error_code)	状态信息	详细描述	是否收费
0000	success	接口调用成功并返回相关数据	是
2000	Search success but no result	接口访问成功，但是搜索没有结果	是
4000	Server internal error	服务器内部错误	否
4001	Network error	网络错误	否
4002	Target server error	目标服务器错误	否
4003	Param error	用户输入参数错误	忽略
4004	Account not found	用户帐号不存在	忽略
4005	Invalid authentication credentials	授权失败	忽略
4006	API stopped	您的当前API已停用	忽略
4007	Account stopped	您的账户已停用	忽略
4008	API rate limit exceeded	并发已达上限	忽略
4009	API maintenance	API维护中	忽略
4010	API not found with these values	API不存在	忽略
4012	Please add api first	请先添加api	忽略
4013	Number of calls exceeded	调用次数超限	忽略
4014	Missing url param	参数缺失	忽略
4015	Wrong pageToken	参数pageToken有误	忽略
4016	Insufficient balance	余额不足	忽略
4017	timeout error	请求超时	否
5000	unknown error	未知错误	否

接口请求并非每次都能成功，所以在接口开发时会对可能失败的情况进行错误码区分，在接口联调时可以根据返回的错误码快递定位问题。如果错误码不够全面，那在接口调用失败的时候，需要反复定位，降低开发效率。

五、接口安全性校验

接口完成业务逻辑开发后，接下来要考虑的就是安全性问题了，接口的安全性问题主要来源于几方面考虑：

1）请求来源是否合法？

即接口的伪装攻击，因为接口是对外的，在公网环境中，接口地址是暴露的，收到的请求有可能是恶意非法请求；如果真的是合法请求，也需要知道这个请求的来源，同时这个请求来源不能否认。这里引入“签名”的概念，以及签名的防伪装及抗否认性特性。

近些年各大企业强制使用https替换掉原有的http接口，正是因为https所使用的的证书安全性更高。

2）请求是否会被篡改，返回数据可能会被截取

因为接口是对外的，所以接收请求和返回数据的时候，是不可能使用明文方式传输的，否则一旦被恶意截取，会造成极大风险。所以请求数据及返回数据都是需要加密的，这样即使数据被截取，也不用泄露数据的内容。这里介绍几种现在常见的加密方法。

DES（Data Encryption Standard）：数据加密标准，速度较快，适用于加密大量数据的场合；

3DES（Triple DES）：是基于DES，对一块数据用三个不同的密钥进行三次加密，强度更高；

RSA：非对称加密，由 RSA公司发明，是一个支持变长密钥的公共密钥算法，需要加密的文件块的长度也是可变的；既可以实现加密，又可以实现签名。

如果是用户账号相关，现在会使用token加密用户信息，用户请求身份信息时，服务端会分配token存在缓存中，后续请求会将token与时间戳一起打包加密，这样即使请求数据被截获，因为不知道token的值，数据也不会被解析出来。

3）如何防范接口的重放攻击，防重放攻击是什么呢？

就是把你的请求原封不动地多次发放，请求都会通过验证进入到正常逻辑中，会造成服务端接口拥堵并且会造成实际损失。

防重放一般需在请求参数加上 时间戳 + 随机数，通过时间戳确保接口是最新的请求，而随机数相同则可以认定为是重放攻击。

六、接口性能相关

如果是访问量比较大的接口，再上线前肯定需要进行压力测试。因为普通的开发自测和生产模拟是不能推算出高并发时候接口是否可正常运行。

1）TPS

Transaction Per Second 每秒系统处理的交易或事物的数量，衡量系统处理能力的重要指标。

2）RT

响应时间，从客户端发送一个请求开始，到客户端接收到从服务器返回的响应结果结束所经历的时间，包括请求发送时间，网络传输时间和服务器处理时间三部分。

3）吞吐量

指的是在一次性能测试过程中网络上传输的数据量的总和。

用户的响应时间自不必说，时间太久伤用户体验，及时处于高并发期，用户的响应时间依然需要控制到最低，一般不超过5s；

tps则是高并发的指标，一般提供服务的接口，需要考虑到最极端情况下的并发数，这些数量一般来自于运营的活动策划和往期的数据趋势预估，以此为依据，保证自己的接口可以支持最高的并发数，而验证这些使用的一般是压力测试。如正常情况下压测时tps可以达到2000时接口正常，就可以保证2000的实际并发。

七、接口需要做哪些测试

接口测试其实是白盒测试，首页要明确系统的能力输出，明确服务覆盖是否满足需求。以业务逻辑推接口参数。

1）入参不符合要求需要有明确错误码，报错信息和日志，方便问题复现与定位。

2）如果另有参数处理逻辑的链路，也需要一并验证，如购买网易云音乐会员，订单生成后会去权益系统加权，加权成功后会有短信通知用户，但加权接口和订单信息中都没有用户手机号，所以虽然入参中没有用户手机号，但需要根据用户的username去查询手机号，并执行短信发放的操作。

其他验证目标如：代码覆盖率是否达到要求、性能指标是否满足要求、安全指标是否满足要求则是更为专业性的测试指标了。