接口知识系统梳理.docx
《接口知识系统梳理.docx》由会员分享，可在线阅读，更多相关《接口知识系统梳理.docx（15页珍藏版）》请在冰豆网上搜索。
接口知识系统梳理
接口知识系统梳理
1、接口的定义
预先定义的函数，提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。
两个独立系统之间同步数据或访问对方程序的途径。
页面跳转同步通知：
如果一个进程在执行请求时，该请求需要一段时间才能返回信息，那么这个进程就会一直等待下去。
有先后顺序。
异步通知：
进程不用等待可以继续执行下面的操作。
背后信息传输，不分先后
2、接口的类型
1.内部系统接口
（公司内部系统与系统间的接口，如数据中台和业务系统的接口）。
如服务端向APP提供调用接口；通常具体APP和服务器的传输交互由开发工程师定义。
2.对外系统接口
（提供给第三方调用的接口，一般都是基于HTTP/soap的协议接口，例如微信开放平台提供给小程序开发者的接口）
（1）主动推送接口（主动给第三方发送信息）
（2）被动推送接口（被第三方推送信息）
（3）主动请求接口（主动请求第三方获取信息）
（4）被动请求接口（被第三方请求获取信息）
常见产品类型：
管理系统类产品（CRM、ERP、boss平台等）；办公系统类产品（OA）；商家端系统类产品（小B端用的商户系统）；接口服务类产品（聚合支付接口，人脸识别接口）
3、接口设计方法（对外系统接口）
定义如下内容：
输入内容，输出内容，业务异常处理方式，计费逻辑，响应速度，并发量，易用性，其他
1.输入内容：
第三方的业务请求参数，明确参数是否可空，无需定义公共请求参数
2.输出内容：
接收第三方请求后，经由系统处理后的业务返回参数。
明确参数可否为空，无需定义公共返回参数。
明确是同步返回还是异步返回。
3.业务异常处理方式：
定义业务异常处理方式，及对业务规则的要求。
系统异常（参数错误、参数缺失等）无需定义。
4.计费逻辑：
接口如何向第三方计费。
（1）哪些情况需计费，哪些情况可不计费。
（2）计费方式：
按次计费（调用一次接口收取一次费用）、阶梯计费（调用一次接口收取一次费用，达到一定使用量后单价下降）、按时间计费（包月或包年计费）
5.响应时间：
第三方发出请求报文后，多久可以收到返回报文。
通常为毫秒级，运算量大，时间稍长，如OCR文字识别和音频识别接口（需提取文字内容）
6.并发量：
支持同时请求接口的最大用户数量。
含用户数量、响应时间、持续时长。
7.易用性：
通常通过SDK（软件开发工具包，把接口封装成Java或PHP等语言的调用函数）和调用demo（示例代码）来实现
8.其他：
系统吞吐量，稳定性需求
4、接口安全
a.防伪转攻击即请求来源是否合法（如：
在公共网络中，第三方有意或恶意的调用我们的接口）
b.防篡改攻击（如：
在公共网络环境中，请求头/查询字符串/内容在传输过程中被修改）
c.防重放攻击即请求被恶意攻击（如：
在公共网络环境中，请求被截获，稍后被重放或多次重放）
d.防数据信息泄露（如：
截获用户登录请求，截获账号、密码等）
1.加密解密的概念与算法
（1）在客户端与服务器进行交互时，必然涉及到交互的报文（或者通俗的讲，请求数据与返回数据），如果不希望报文进行明文传输，则需要进行报文的加密与解密
所以加密的主要作用就是避免明文传输，就算被截获报文，截获方也不知道报文的具体内容
（2）对称加密，单向加密，非对称加密
（3）加密算法：
DES加密算法，AES加密算法，RSA加密算法……
2.签名的概念与算法
（1）签名作用：
认证数据来源，抗否认性，保证数据完整性
（2）签名方式：
APPKEY+签名认证，token+签名认证，HTTPS模式
5、接口书写规范（对外系统接口）
1.向对方系统主动推送数据
接口名称
向XXX系统推送XXX数据的接口
接口描述
1.介绍一下接口使用的业务场景
2.对方接口的访问地址
3.双方约定的数据唯一性维度，及数据重复时的处理机制
推送参数
字段名称
字段来源
示例
逻辑验证规则
1.要同步的字段的名称
2.此名称是业务上的名字，非字段名称
3.数据库的字段名称由开发根据此名称设计
字段的取值逻辑，此部分是重点。
因为接口实现时需根据此描述给字段赋值
真实业务中字段取值的例子，方便理解
1.对方系统对此字段的格式要求、缺省要求等验证规则。
若不按此规则设计，则同步时对方不会接收数据，会返回错误
2.这里对缺省的设计要注意的是：
若业务上存在缺省的情况且对方对缺省的要求性不高，则在同步时不应校验不可为空性，否则会因为不必性的限制，导致其他信息同步失败
返回参数
失败时的返回值及失败原因
成功时的返回值
2.对方主动来获取数据
接口名称
供XXX系统获取XXX数据的接口
接口描述
1.对方系统访问此接口的业务场景
2.一次性返回数据的数量（如单条、分页）
3.双方约定的数据唯一性维度，及数据重复时的处理机制
请求参数
字段名称
字段来源
示例
逻辑验证规则
对方来请求数据时需要传输的参数
真实业务中字段取值的例子，方便理解
1.对是否缺省的定义
2.对参数应该做的校验，如是否合法，及不满足条件时应返回的错误信息
返回参数
对方的请求参数
真实业务中字段取值的例子
毕传，方便对方识别是哪个参数获取到的数据
状态
能否根据请求参数返回数据的状态值
1.若存在数据，则返回成功值
2.若不存在，则返回失败值，表示失败
错误消息
对错误情况的定义和说明，以及每种情况下应返回的错误信息
根据请求参数需要返回给对方的数据
字段的取值逻辑，此部分是重点。
因为接口实现时工程师需要根据此描述给字段赋值
真实业务中字段取值的例子
若根据参数有匹配到数据，则返回，若匹配不到则返回空值
3.被动接收对方推送的数据
4.主动从对方获取数据
接口名称
供XXX系统获取XXX数据的接口
接口描述
1.通常此类接口用于用户实时操作时即时向对方请求数据，因此需要交代清楚在用户做什么操作的时候调用此接口获取数据
2.双方约定的数据唯一性维度，及数据重复时的处理机制
3.对方的接口访问地址
请求参数
字段名称
字段来源
示例
逻辑验证规则
1.对方要求传输的请求参数名称
2.此名称是业务上的名字，非数据的字段名称
3.数据库的字段名称由开发根据此名称设计
字段的取值逻辑，此部分是重点。
因为接口实现时工程师需要根据此描述给字段赋值
真实业务中字段取值的例子，方便理解
对方系统对此字段的格式要求、缺省要求等验证规则。
若不按此规则设计，则同步时对方不会接收数据，会返回错误
返回参数
传输给对方的请求参数
真实业务中字段取值的例子
必传，方便识别是哪个参数获取到的数据
状态
数据获取成功与否的状态值
1.若存在数据，则返回成功值
2.若不存在，则返回失败值，表示失败
错误消息
对方返回的错误消息
返回失败时，应返回失败原因，此原因用于定位数据获取失败的原因
获取的字段名称
字段在业务上的意思
对获取到的数据的校验规则
1.若请求成功，则不可为空
2.拿到数据后为了保证数据完整性需要做校验的规则
3.不满足校验规则时给对方返回的错误信息
6、常用模块接口（系统内部接口）
1．登录模块接口
（1）登录
功能名称
登录
接口方法
Login
参数描述
4.Mobile手机号码字符串类型
5.Loginpwd登录密码字符串类型
返回值
Ret：
“success”or“fall”
Date：
如果success，则返回userinfo；如果fall，存放错误提示信息
场景描述
备注
Userinfo包含userID/name
（2）获得注册短信
功能名称
获得注册短信
接口方法
Getregistersms
参数描述
1.Mobile手机号码字符串类型
返回值
Ret：
“success”or“fall”
Date：
如果success，则返回一个数表示多久可以再次获取验证码；如果fall，存放错误提示信息
场景描述
备注
（3）注册
功能名称
注册
接口方法
Register
参数描述
1.Mobile手机号码字符串类型
2.SmsCode短信验证码字符串类型
3.Loginpwd登录密码字符串类型
4.Invitecode邀请码字符串类型（可选）
返回值
Ret：
“success”or“fall”
Date：
如果success，则返回一个userID；如果fall，存放错误提示信息
场景描述
备注
（4）重置密码
功能名称
获取重置密码验证码
接口方法
Getchangepwdsms
参数描述
1.Mobile手机号码字符串类型
返回值
Ret：
“success”or“fall”
Date：
如果success，则返回一个数表示多久可以再次获取验证码；如果fall，存放错误提示信息
场景描述
备注
功能名称
重置登录密码
接口方法
Resetloginpwd
参数描述
1.Mobile手机号码字符串类型
2.Smscode短信验证码字符串类型
3.Newloginpwd新的登录密码字符串类型
返回值
Ret：
“success”or“fall”
Date：
可选；如果fall，存放错误提示信息
场景描述
备注
2．接口
（1）支付密码
功能名称
请求重设支付密码
接口方法
Getresetpaysms
参数描述
1.Mobile手机号码字符串类型
2.userID用户唯一编号字符串类型
返回值
Ret：
“success”or“fall”
Date：
可选；如果fall，存放错误提示信息
场景描述
备注
功能名称
重设支付密码
接口方法
Getresetpaysms
参数描述
1.Mobile手机号码字符串类型
2.smscode短信验证码字符串类型
3.newpaypwd新的支付密码字符串类型
返回值
Ret：
“success”or“fall”
Date：
可选；如果fall，存放错误提示信息
场景描述
备注
（2）产品列表
功能名称
获取产品列表
接口方法
Getproductlist
参数描述
1.cat分类字符串类型如家具电子
2.size条目字符串类型
3.offset偏移量字符串类型
返回值
Ret：
“success”or“fall”
Date：
如果success，则返回product对象的数组；如果fall，存放错误提示信息
场景描述
备注
（3）产品细节
功能名称
获取产品细节
接口方法
Getproductdetail
参数描述
1.Productid产品编号字符串类型
返回值
Ret：
“success”or“fall”
Date：
如果success，则返回一个product详细对象；如果fall，存放错误提示信息
场景描述
备注
（4）充值
功能名称
充值
接口方法
Puton
参数描述
1.fee费用数字类型
2.bankcard银行卡字符串类型
返回值
Ret：
“success”or“fall”
Date：
如果success，则返回可用余额double类型；如果fall，存放错误提示信息
场景描述
备注
（5）提现
功能名称
提现
接口方法
Putoff
参数描述
1.fee费用数字类型
2.bankcard银行卡字符串类型
返回值
Ret：
“success”or“fall”
Date：
如果success，则返回可用余额double类型；如果fall，存放错误提示信息
场景描述
备注
（6）交易列表
功能名称
获取交易列表
接口方法
Gettradelist
参数描述
1.size条目数字类型
2.offset偏移量数字类型
返回值
Ret：
“success”or“fall”
Date：
如果success，则返回trade对象的数组；如果fall，存放错误提示信息
场景描述
备注
（7）我的产品列表
功能名称
获取我的产品列表
接口方法
Getmyproductlist
参数描述
1.size条目数字类型
2.Offset偏移量数字类型
返回值
Ret：
“success”or“fall”
Date：
如果success，则返回trade对象的数组；如果fall，存放错误提示信息
场景描述
备注
（8）账户信息
功能名称
获取账户信息
接口方法
Getaccountinfo
参数描述
1.userID用户编号字符串类型
返回值
Ret：
“success”or“fall”
Date：
如果success，则返回一个account详细对象；如果fall，存放错误提示信息
场景描述
备注
（9）银行卡列表
功能名称
获取银行卡列表
接口方法
Getmybankcardlist
参数描述
1.size条目数字类型
2.Offset偏移量数字类型
返回值
Ret：
“success”or“fall”
Date：
如果success，则返回bankcard对象的数组；如果fall，存放错误提示信息
场景描述
备注
（10）添加银行卡
功能名称
添加银行卡
接口方法
Addbankcard
参数描述
1.bankcardinfo银行卡信息字符串类型
返回值
Ret：
“success”or“fall”
Date：
可选；如果fall，存放错误提示信息
场景描述
备注
（11）评论
功能名称
评论
接口方法
Comment
参数描述
1.postid帖子编号字符串类型
2.Commentid评论编号字符串类型（空）
3.Desc描述字符串编号
返回值
Ret：
“success”or“fall”
Date：
可选；如果fall，存放错误提示信息
场景描述
备注
（12）收藏
功能名称
收藏列表
接口方法
Listfavs
参数描述
1.size条目数字类型
2.Offset偏移量数字类型
返回值
Ret：
“success”or“fall”
Date：
如果success，则返回一个post对象的数组；如果fall，存放错误提示信息
场景描述
备注
（13）消息
功能名称
消息列表
接口方法
Getmeglist
参数描述
1.size条目数字类型
2.Offset偏移量数字类型
返回值
Ret：
“success”or“fall”
Date：
如果success，则返回msg对象的数组；如果fall，存放错误提示信息
场景描述
备注
升级会员 