zeyi / open-doc

Download as
Browse Code »

Commit a45e5b22248b974b61530eb3e6571e80bf689160

Authored by 吴志飞
2 parents b051ba6e c9a9b211
Exists in master

Merge remote-tracking branch 'origin/master'

Showing 2 changed files with 275 additions and 2 deletions   Show diff stats
guide/notice/则一后端开发注意事项.md
  Diff comments   View file @a45e5b2
... ... @@ -49,7 +49,7 @@ SQL写完一定è¦åœ¨ç”Ÿäº§çŽ¯å¢ƒæ‰§è¡Œä¸€ä¸‹ï¼Œçœ‹ä¸‹æ‰§è¡Œè®¡åˆ’有没有走ç´
49 49  
50 50 ##### 命å规范â­â­â­â­
51 51  
52   -ç±»å需è¦ä½¿ç”¨å¤§é©¼å³°å‘½å法(UpperCamelCase) 风格
  52 +ç±»å一般为åè¯æˆ–åè¯ç»„åˆï¼Œéœ€è¦ä½¿ç”¨å¤§é©¼å³°å‘½å法(UpperCamelCase) 风格
53 53  
54 54 方法åã€å‚æ•°åã€æˆå‘˜å˜é‡ã€å±€éƒ¨å˜é‡éœ€è¦ä½¿ç”¨å°é©¼å³°å‘½å法(lowerCamelCase)
55 55  
... ... @@ -150,6 +150,14 @@ try {
150 150 }
151 151 ```
152 152  
  153 +#### 定时任务
  154 +
  155 +è¦æ³¨æ„定时任务事务回滚问题。ç†æ¸…楚当有异常产生时，是è¦å…¨éƒ¨å›žæ»šè¿˜æ˜¯æ­£å¸¸æ‰§è¡Œå®Œã€‚
  156 +
  157 +常è§é—®é¢˜â­â­â­â­
  158 +
  159 +定时任务异常未处ç†ï¼Œå¯¼è‡´æ•´ä¸ªäº‹åŠ¡å›žæ»šï¼Œä»»åŠ¡æ‰§è¡Œå¤±è´¥!
  160 +
153 161 #### 版本兼容
154 162  
155 163 APPåŽå°å¼€å‘è¦æ³¨æ„版本兼容问题，APPå‰ç«¯ç‰ˆæœ¬ä¸Šçº¿åŽä¸ä¸€å®šæ‰€æœ‰ç”¨æˆ·éƒ½èƒ½åŠæ—¶æ›´æ–°ç‰ˆæœ¬ã€‚è¦ä¿è¯è€ç‰ˆæœ¬ä½¿ç”¨çš„接å£ä¹Ÿèƒ½åšå‡ºå‡†ç¡®çš„å“应
... ... @@ -196,7 +204,7 @@ public Response<Void> addDriverVehicleLicenseV1(@RequestBody @Validated DriverVe
196 204 #### git
197 205  
198 206 分支：开å‘分支，测试分支，上线分支，master
199   -å¼€å‘分支: å¼€å‘功能时è¦åˆ›å»ºè‡ªå·±çš„å¼€å‘分支，开å‘分支从master创建分支
  207 +å¼€å‘分支: å¼€å‘功能时è¦åˆ›å»ºè‡ªå·±çš„å¼€å‘分支，开å‘分支从master创建分支，一般一个需求对应一个分支
200 208 测试分支: 测试环境部署的分支，功能开å‘完通过å•å…ƒæµ‹è¯•åŽå°±å¯ä»¥æŠŠä»£ç åˆå¹¶åˆ°æµ‹è¯•åˆ†æ”¯è¿›è¡Œæµ‹è¯•
201 209 上线分支: æ¯å‘¨ä¼šæœ‰ä¸€ä¸ªä¸Šçº¿ç‰ˆæœ¬ï¼Œä¸Šçº¿ä¹‹å‰éœ€è¦æŠŠè¦ä¸Šçº¿çš„代ç åˆå¹¶åˆ°ä¸Šçº¿åˆ†æ”¯ï¼Œä»Žè‡ªå·±çš„å¼€å‘分支åˆå¹¶åˆ°ä¸Šçº¿åˆ†æ”¯
202 210 master: 生产环境部署分支，由上线部署人员从上线分支åˆå¹¶åˆ°master
... ...
order/truck/zsh/2022121401/订单接口.md 0 → 100644
  Diff comments   View file @a45e5b2
... ... @@ -0,0 +1,265 @@
  1 +[toc]
  2 +
  3 +# 订单对接API
  4 +
  5 +则一提供了不同规范的API，调用服务端API前，需了解开发前须知及调用流程。本文提供了调用则一服务端API示例，供开发者参考。
  6 +
  7 +## 白名单
  8 +
  9 +则一服务端API接口访问有IP白名单限制，需要接口调用方提供调用API的服务器IP地址。
  10 +
  11 +## 数据加签
  12 +
  13 +采用md5(32位小写)算法生成签名
  14 +appKey(则一提供) + appSecret(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(请求数据)
  15 +
  16 +## 数据加密
  17 +
  18 +数据加密采用AES算法
  19 +加密模式： CBC
  20 +填充方式：PKCS5Padding
  21 +偏移量：iv(则一提供)
  22 +加密内容：appKey(则一提供) + timestamp(当前时间戳毫秒) + nonce(6位随机码大小写字母数子组合) + data(加密数据)
  23 +密钥： appSecret(则一提供)
  24 +输出：base64
  25 +字符集：utf-8
  26 +注：无敏感数据则无需加密
  27 +
  28 +## 获取访问凭证
  29 +
  30 +### 概述
  31 +
  32 +调用则一服务API时，都需要先获取对应权限类型的访问凭证accessToken。访问凭证（accessToken）是由则一权限系统颁发的，用来校验调用者的身份信息，确保调用者具有要执行的操作的权限。
  33 +**说明**： 在使用accessToken时，请注意：
  34 +
  35 +* accessToken的有效期默认为30天，有效期内重复获取会返回相同结果，过期后获取会返回新的accessToken。
  36 +* 开发者需要缓存accessToken，用于后续接口的调用。不能频繁调用获取accessToken接口，否则会受到频率拦截。
  37 +* 当调用业务API时，如果返回状态码为401，则说明accessToken不正确或已过期，这时需要重新获取accessToken后再调用对应的API。
  38 +
  39 +### 接口信息
  40 +
  41 +#### 请求方式：
  42 +
  43 +post
  44 +
  45 +#### 请求地址：
  46 +
  47 +* 生产：https://gw.shjiuze.cn/auth-service-api/login/password
  48 +* 测试：https://test.shjiuze.cn/auth-service-api/login/password
  49 +
  50 +#### Body参数
  51 +
  52 +| 名称 | 类型 | 必填 | 示例值 | 描述 |
  53 +| -------- | ------ | ---- | ----------- | ---------------- |
  54 +| username | String | 是 | zhangsan | 用户名，则一提供 |
  55 +| password | String | 是 | password123 | 密码，则一提供 |
  56 +
  57 +#### 返回参数
  58 +
  59 +| 名称 | 类型 | 示例值 | 描述 |
  60 +| ------------------------------ | ---------- | -------------------------------- | -------------------------------------------------- |
  61 +| success | boolean | true | 成功标识: true 成功，false 失败 |
  62 +| businessException | boolean | false | 业务异常标识: true 业务异常，false 正常 |
  63 +| errorCode | String | 200 | 错误码: 200 业务异常，500 系统异常， 空表示无错误 |
  64 +| message | String | 订单号不能为空 | 错误信息，无错误则返回空 |
  65 +| result | ZYTokenDto | | accessToken结果数据 |
  66 +|     accessToken | String | 000626f15b4b41bba6fe56216a5d2f73 | accessToken |
  67 +|     expiresIn | Integer | 2060 | 有效期限单位秒，accessToken在2060秒后过期 |
  68 +|     tokenType | String | bearer | token类型 |
  69 +
  70 +#### 请求示例
  71 +
  72 +##### Http方式
  73 +
  74 +```http
  75 +POST /auth-service-api/login/password HTTP/1.1
  76 +Host:test.shjiuze.cn
  77 +Content-Type:application/json
  78 +
  79 +{
  80 + "username" : "zeyi",
  81 + "password" : "test1111"
  82 +}
  83 +```
  84 +
  85 +##### Java-sdk方式[下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar)
  86 +
  87 +```java
  88 +public class Sample {
  89 + public static void main(String[] args_) {
  90 + String appKey = "appkey";
  91 + String appSecret = "appSecret";
  92 + ZYClient zyClient = new ZYClient(appKey, appSecret);
  93 + ZYTokenRequestDto zyTokenRequest = new ZYTokenRequestDto();
  94 + zyTokenRequest.setUsername("zeyi");
  95 + zyTokenRequest.setPassword("test1111");
  96 + String body = gson.toJson(zyTokenRequest);
  97 + HttpResponseData httpResponseData = zyClient.doPost(Constants.TEST_HOST + Constants.TOKEN_PATH, body);
  98 + if(httpResponseData == null) {
  99 + throw new TokenException("则一Token请求失败,返回为空!");
  100 + }
  101 + ZYResponse<ZYTokenDto> zyResponse = gson.fromJson(httpResponseData.getBody(), new TypeToken<ZYResponse<ZYTokenDto>>(){}.getType());
  102 + if(!Boolean.TRUE.equals(zyResponse.isSuccess())) {
  103 + throw new TokenException("则一Token请求返回失败!" + zyResponse.getMessage());
  104 + }
  105 + if(zyResponse.getResult() == null) {
  106 + throw new TokenException("则一Token请求返回失败,返回结果为空!" + zyResponse.getMessage());
  107 + }
  108 + if(StringUtils.isBlank(zyResponse.getResult().getAccessToken())) {
  109 + throw new TokenException("则一Token请求返回数据异常,AccessToken为空!" + zyResponse.getMessage());
  110 + }
  111 + // 结果 zyResponse.getResult();
  112 + }
  113 +}
  114 +```
  115 +
  116 +#### 返回示例
  117 +
  118 +```json
  119 +{
  120 + "success": true,
  121 + "businessException": false,
  122 + "errorCode": null,
  123 + "message": null,
  124 + "result": {
  125 + "accessToken": "64d7f367-609b-4f7d-a84d-a3d2a0b5ad85",
  126 + "expiresIn": 602105,
  127 + "tokenType": "bearer"
  128 + }
  129 +}
  130 +```
  131 +
  132 +## 委托单集成接口
  133 +
  134 +### 简要描述
  135 +
  136 +委托单集成接口
  137 +
  138 +### 请求URL
  139 +
  140 +· 测试环境：https://test.shjiuze.cn/oms-service-api/zshOrder/add
  141 +
  142 +· 生产环境：https://gw.shjiuze.cn/oms-service-api/zshOrder/add
  143 +
  144 +### 请求方式
  145 +
  146 +POST
  147 +
  148 +### Headers参数
  149 +
  150 +| 名称 | 类型 | 必填 | 示例值 | 描述 |
  151 +| ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ |
  152 +| Authorization | String | 是&nbsp;&nbsp;&nbsp;&nbsp; | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 |
  153 +| appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 则一提供 |
  154 +| timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 |
  155 +| nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 |
  156 +| sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 |
  157 +
  158 +### Body参数
  159 +
  160 +参数Json.
  161 +
  162 +### 返回结果正常示例
  163 +
  164 + { "success": true, "businessException": false}
  165 +
  166 +### 返回结果异常示例
  167 +
  168 + { "success": false, "businessException": true, "errorCode": "500", "message": "XXX异常!"}
  169 +
  170 +### 请求示例
  171 +
  172 +##### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar)
  173 +
  174 +```java
  175 +public class Sample {
  176 + public static void main(String[] args_) {
  177 + String appKey = "appkey";
  178 + String appSecret = "appSecret";
  179 + String jsonData = "委托单Body参数JSON数据";
  180 + ZYClient zyClient = new ZYClient(appKey, appSecret);
  181 + HttpResponseData httpResponseData =
  182 +zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/zshOrder/add", "accessToken", jsonData);
  183 + if(httpResponseData == null) {
  184 + throw new BusinessException("则一请求失败,返回结果为空!");
  185 + }
  186 + if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) {
  187 + //重新获取token再次请求
  188 + httpResponseData = zyClient.doPost(Constants.TEST_HOST +
  189 + "/oms-service-api/zshOrder/add", "accessToken", jsonData);
  190 + }
  191 + }
  192 +}
  193 +```
  194 +
  195 +## 拒单集成接口
  196 +
  197 +### 简要描述
  198 +
  199 +拒单集成接口
  200 +
  201 +### 请求URL
  202 +
  203 +· 测试环境：https://test.shjiuze.cn/oms-service-api/zshOrder/cancelOrder
  204 +
  205 +· 生产环境：https://gw.shjiuze.cn/oms-service-api/zshOrder/cancelOrder
  206 +
  207 +### 请求方式
  208 +
  209 +POST
  210 +
  211 +### Headers参数
  212 +
  213 +| 名称 | 类型 | 必填 | 示例值 | 描述 |
  214 +| ------------- | ------ | -------------------------- | -------------------------------- | ------------------------------------------------------------ |
  215 +| Authorization | String | 是&nbsp;&nbsp;&nbsp;&nbsp; | Bearer a2c5680001 | 调用服务端API的应用凭证accessToken，通过调用获取访问凭证接口获取。 |
  216 +| appKey | String | 是 | 0867ef5f23ef446483749e19e1692b40 | 则一提供 |
  217 +| timestamp | String | 是 | 1643251533306 | 当前时间戳毫秒值 |
  218 +| nonce | String | 是 | gdst9t | 6位小写字母数字组合随机串 |
  219 +| sign | String | 是 | fa3ed338d6dfe18e7273c8692234ee70 | 签名：appKey(则一提供) + appSecret(则一提供) + timestamp + nonce(6位随机码) + data(body参数)通过md5(32位小写)算法生成 |
  220 +
  221 +### Body参数
  222 +
  223 +参数Json.
  224 +
  225 +### 返回结果正常示例
  226 +
  227 + { "success": true, "businessException": false}
  228 +
  229 +### 返回结果异常示例
  230 +
  231 + { "success": false, "businessException": true, "errorCode": "500", "message": "XXX异常!"}
  232 +
  233 +### 请求示例
  234 +
  235 +##### Java-sdk方式 [下载SDK](https://zeyi-tms-product.oss-cn-hangzhou.aliyuncs.com/file/jar/java-sdk/zy-java-sdk-1.0.0.jar)
  236 +
  237 +```java
  238 +public class Sample {
  239 + public static void main(String[] args_) {
  240 + String appKey = "appkey";
  241 + String appSecret = "appSecret";
  242 + String jsonData = "拒单Body参数JSON数据";
  243 + ZYClient zyClient = new ZYClient(appKey, appSecret);
  244 + HttpResponseData httpResponseData =
  245 +zyClient.doPost(Constants.TEST_HOST + "/oms-service-api/zshOrder/cancelOrder", "accessToken", jsonData);
  246 + if(httpResponseData == null) {
  247 + throw new BusinessException("则一请求失败,返回结果为空!");
  248 + }
  249 + if(httpResponseData.getStatus() == HttpURLConnection.HTTP_UNAUTHORIZED) {
  250 + //重新获取token再次请求
  251 + httpResponseData = zyClient.doPost(Constants.TEST_HOST +
  252 + "/oms-service-api/zshOrder/cancelOrder", "accessToken", jsonData);
  253 + }
  254 + }
  255 +}
  256 +```
  257 +
  258 +
  259 +
  260 +------------------------------------------------------------------------------------------
  261 +
  262 +## 2022-05-05更新日志
  263 +
  264 +1. 接口初始化
  265 +
... ...