API对接实战

目录

一 背景

二 了解B公司接口的基础约定

三 基础域名

四 请求及相应格式说明

五 确定要对接哪些API

六 根据API文档，编写一些基础工具类。

七 根据API文档，编写必要的DTO

八 针对每个API方法，进行对接

九 对接代码结构

十 一些对接技巧

---

一 背景

在平时工作中，经常会遇到的一种场景是：A公司要对接B公司的API方法，这时，A公司就要阅读B公司的接口文档，从接口文档中找到自己需要对接的API，并根据接口文档的要求，完成编码工作，最终完成对接工作。

本篇是站在A公司的角度，去对接B公司API接口的实战。

二 了解B公司接口的基础约定

一般情况下，B公司都会给出以下类似约定来满足基础对接，并且会提供测试环境和正式环境的两套信息。

appkey：A公司商户平台 id

appsecret：A公司商户平台 secret

三 基础域名

一般情况下，B公司会提供测试环境和生产环境两个基础域名。

例如

测试环境 ： https://api-b-dev.com.cn

生产环境 ： https://api-b-prod.com.cn

四 请求及相应格式说明

一般情况下，B公司会提供请求及相应的基础格式说明。

例如：

1 请求方式

post

2 请求消息格式

application/json

3 响应消息格式

application/json

4 请求公共参数

例如，B公司有以下要求

所有接口均需要以 Http Header 方式传递以下参数；

参数名	描述	必填
appkey	商户平台 id	是
request_id	请求标识 ，每次请求唯一	是
sign_type	签名方法，固定为 sha256	是
signature	签名，算法为 HMACSHA256(appkey+timestamp+appsecret,appsecret)	是
version	版本， 固定为 2.0	是
callback_url	回调地址， 以 https://或者 http://开头并进行 base64 编码	是（同步响应的接口可不必填写）
timestamp	时间戳（秒）， 30 分钟过期	是

当然，不同的公司提供的参数各不相同，因公司而异。

5 响应/回调参数说明

例如：B公司所有API都有响应，并且有的API还有回调响应，不论是响应还是回调响应，它们的参数格式都一样。

参数	类型	描述
code	int	状态码
msg	String	消息
request_id	String	请求时的 request_id
data	Object	数据
appkey	String	商户平台id

6 针对异步回调的说明

例如：B公司对异步回调说明如下：

异步回调：

某些特定的接口需要异步返回结果，因此需商户A提供一个回调地址，将其进行base64 编码后，配置在 Http 请求 Header 中的 callback_url 里。

应答机制：

应答机制是指当商户A收到B公司数据通知时，必须回写 success 字符串，不区分大小写，B公司收到该“ success”，便认为商户A已收到通知； 否则会继续重复请求回调接口 3 次， 时间间隔为 1s， 5s， 30s。如果 4 次都访问不通，则会间隔 3h 继续轮询回调。

回调解密：

回调使用 aes 加密，需解密后使用。为避免由于网络波动造成回调失败，长时间未收到回调，请主动查询。

7 请求体加密说明及示例

数据采用AES加密，加密后作为data的值。

示例：

加密前：

{"settlement_code":["JS19BUB14F5D8D4C"],"random_code":["19BUB14F5D8D4C","19BUAD0E89D780"]}

加密后：

{"data":"236agZcupcSsMZghtlmzhb7lEWzGZc3FO5GWQyrSB5kP/y1ESvd+CuBgQiWU/fwAICY/s0mideku/rXSKEb8In41F4SkUVLyLzYoYGed4QTjsqohTM0T6wmbkOiT1TH3"}

对 {"settlement_code":["JS19BUB14F5D8D4C"],"random_code":["19BUB14F5D8D4C","19BUAD0E89D780"]} 进行AES加密，结果为：

236agZcupcSsMZghtlmzhb7lEWzGZc3FO5GWQyrSB5kP/y1E