通用接口开放平台设计与实现——（2）API服务总体设计

API服务是通用接口平台的主体部分，对外暴露Restful风格的数据接口，其他应用系统通过调用API服务，一方面，可以查询权限范围内的物流数据，另一方面，可以将自身系统产生的数据推送至物流系统。

总体设计

API服务分为服务技术框架和具体业务功能接口两部分，技术框架部分负责统一调度、数据验证、身份认证、安全控制、日志记录等职责，具体业务功能接口负责实际的业务接口功能处理，总体处理流程如下图所示：

交互技术

接口传输协议：HTTP
接口请求方式：POST
数据编码格式：UTF-8
数据传输格式：JSON

输入参数

API服务接口输入参数有且只有5个参数，如下表：

参数编码	参数类型	说明
serviceCode	string	服务编码
appKey	string	应用（调用系统）标识，由物流系统分配
requestTime	string	请求时间，格式yyyy-MM-dd HH:mm:ss
sign	string	签名
signMethod	string	签名方法，尚未启用，目前默认使用MD5，以后可扩展其他签名方式
data	string	请求业务数据，json字符串

前面4个为系统参数，不能为空。
最后1个参数为业务参数，所有跟业务相关的数据都封装在该参数中。

输出参数

API服务接口返回参数有4个参数，如下表：

参数编码	参数类型	说明
executeResult	string	执行结果，SUCCESS：成功，ERROR：失败
errorCode	string	错误编码
errorMessage	string	错误信息
data	string	响应业务数据，json字符串

执行结果如为SUCCESS，则代表成功，可进一步从业务数据字段data获取返回的业务数据，如为ERROR，则代表接口执行出错， errorCode和errorMessage字段中存放错误编码和错误信息。

安全控制

身份认证

物流系统会为调用系统分配一个应用标识和密钥，调用系统在调用API服务时，传入应用标识，使用密钥对参数进行签名，将签名作为请求参数传入，通过签名来完成身份认证。

防篡改

物流接口平台会为调用系统分配一个密钥，调用系统使用该密钥，通过特定的加密算法，对请求参数进行加密，生成签名，将签名作为请求的一部分，传给物流接口平台。物流接口平台收到请求后，以同样的算法进行签名，对比二者是否相同，如不相同，则说明传递过程中发生了数据篡改，拒绝进行服务。

时效性控制

为了控制API服务调用的时效性，物流接口平台设置了请求的有效时间为600秒，以调用系统传入的请求时间参数与服务器当前时间进行比对，10分钟范围内的请求视为合法请求，超出该范围视为非法请求，拒绝服务。

签名算法

签名生成过程如下：
1.对所有请求参数（除去sign签名参数自身），根据参数编码的ASCII码表的顺序排序
2.依序拼装参数编码和参数值，形成一个字符串，每组参数编码与参数值中间使用=连接
3.把拼装好的字符串前后拼接应用密钥
4.使用MD5签名算法对编码后的字节流进行运算
5.将运算得到的字节流结果使用十六进制表示，转换为全部大写
最后产生的是一个32位长度的16进制数

注意：密钥仅参与生成签名的运算过程，不能放到参数列表中。

错误定义

平台级错误定义如下:

错误编码	错误信息
S00	****不能为空
S01	请求时间格式不符合要求
S10	应用代码不存在
S11	应用已停用
S20	服务不存在
S21	服务已停用
S30	无权限
S40	请求时间超出合理范围
S50	签名验证失败
S99	未定义错误+具体异常信息

业务级错误定义参见各具体的API服务接口。

开源平台资料

平台名称：一二三开发平台
简介： 企业级通用低代码开发平台
设计资料：CSDN专栏
开源地址：Gitee
开源协议：MIT
欢迎收藏、点赞、评论，你的支持是我前行的动力。