可自定义数据节点

2025-08-12 06:53:42 +08:00 · 2019-05-04 17:17:09 +08:00
parent a6e04b6ca4
commit 9d8891e49b
23 changed files with 515 additions and 45 deletions
--- a/doc/docs/_sidebar.md
+++ b/doc/docs/_sidebar.md
@@ -1,23 +1,25 @@
-* [首页](/?t=1556455222293)
+* [首页](/?t=1556955558296)
 * 开发文档
-  * [快速体验](files/10010_快速体验.md?t=1556455222295)
-  * [项目接入到SOP](files/10011_项目接入到SOP.md?t=1556455222316)
-  * [新增接口](files/10020_新增接口.md?t=1556455222316)
-  * [业务参数校验](files/10030_业务参数校验.md?t=1556455222316)
-  * [错误处理](files/10040_错误处理.md?t=1556455222317)
-  * [编写文档](files/10041_编写文档.md?t=1556455222317)
-  * [接口交互详解](files/10050_接口交互详解.md?t=1556455222317)
-  * [easyopen支持](files/10070_easyopen支持.md?t=1556455222317)
-  * [使用签名校验工具](files/10080_使用签名校验工具.md?t=1556455222317)
-  * [ISV管理](files/10085_ISV管理.md?t=1556455222317)
-  * [路由授权](files/10090_路由授权.md?t=1556455222317)
-  * [接口限流](files/10092_接口限流.md?t=1556455222317)
-  * [SDK开发](files/10095_SDK开发.md?t=1556455222317)
-  * [使用SpringCloudGateway](files/10096_使用SpringCloudGateway.md?t=1556455222318)
-  * [应用授权](files/10097_应用授权.md?t=1556455222318)
+  * [快速体验](files/10010_快速体验.md?t=1556955558299)
+  * [项目接入到SOP](files/10011_项目接入到SOP.md?t=1556955558316)
+  * [新增接口](files/10020_新增接口.md?t=1556955558316)
+  * [业务参数校验](files/10030_业务参数校验.md?t=1556955558316)
+  * [错误处理](files/10040_错误处理.md?t=1556955558316)
+  * [编写文档](files/10041_编写文档.md?t=1556955558316)
+  * [接口交互详解](files/10050_接口交互详解.md?t=1556955558317)
+  * [easyopen支持](files/10070_easyopen支持.md?t=1556955558317)
+  * [使用签名校验工具](files/10080_使用签名校验工具.md?t=1556955558317)
+  * [ISV管理](files/10085_ISV管理.md?t=1556955558317)
+  * [路由授权](files/10090_路由授权.md?t=1556955558317)
+  * [接口限流](files/10092_接口限流.md?t=1556955558317)
+  * [SDK开发](files/10095_SDK开发.md?t=1556955558317)
+  * [使用SpringCloudGateway](files/10096_使用SpringCloudGateway.md?t=1556955558317)
+  * [应用授权](files/10097_应用授权.md?t=1556955558317)
+  * [更改数据节点名称](files/10099_更改数据节点名称.md?t=1556955558318)
+  * [对接前端](files/10100_对接前端.md?t=1556955558318)
 * 原理分析
-  * [原理分析之@ApiMapping](files/90010_原理分析之@ApiMapping.md?t=1556455222318)
-  * [原理分析之路由存储](files/90011_原理分析之路由存储.md?t=1556455222318)
-  * [原理分析之如何路由](files/90012_原理分析之如何路由.md?t=1556455222318)
-  * [原理分析之文档归纳](files/90013_原理分析之文档归纳.md?t=1556455222318)
-  * [常见问题](files/90100_常见问题.md?t=1556455222318)
+  * [原理分析之@ApiMapping](files/90010_原理分析之@ApiMapping.md?t=1556955558318)
+  * [原理分析之路由存储](files/90011_原理分析之路由存储.md?t=1556955558318)
+  * [原理分析之如何路由](files/90012_原理分析之如何路由.md?t=1556955558318)
+  * [原理分析之文档归纳](files/90013_原理分析之文档归纳.md?t=1556955558318)
+  * [常见问题](files/90100_常见问题.md?t=1556955558318)
--- a/doc/docs/files/10095_SDK开发.md
+++ b/doc/docs/files/10095_SDK开发.md
@@ -21,7 +21,7 @@ SDK依赖了三个jar包
 - 参数：name 故事名称
 - 返回信息

-```
+```json
 {
 	"alipay_story_find_response": {
 		"msg": "Success",
--- a/doc/docs/files/10099_更改数据节点名称.md
+++ b/doc/docs/files/10099_更改数据节点名称.md
@@ -0,0 +1,69 @@
+# 更改数据节点名称
+
+针对`alipay.story.find`接口，它的返回结果如下：
+
+```json
+{
+	"alipay_story_find_response": {
+		"msg": "Success",
+		"code": "10000",
+		"name": "白雪公主",
+		"id": 1,
+		"gmtCreate": 1554193987378
+	},
+	"sign": "xxxxx"
+}
+```
+
+其中`alipay_story_find_response`是它的数据节点。规则是：
+
+> 将接口名中的"."转换成"_"，后面加上"_response"。
+
+代码实现如下：
+
+```java
+String method = "alipay.story.find";
+return method.replace('.', '_') + "_response";
+```
+
+详见`DefaultDataNameBuilder.java`
+
+如果要更改数据节点，比如`result`，可使用`CustomDataNameBuilder.java`。
+
+```java
+@Configuration
+public class ZuulConfig extends AlipayZuulConfiguration {
+
+    static {
+        ...
+        ApiConfig.getInstance().setDataNameBuilder(new CustomDataNameBuilder());
+        ...
+    }
+
+}
+```
+
+设置后，网关统一的返回结果如下：
+
+```json
+{
+	"result": {
+		...
+	},
+	"sign": "xxxxx"
+}
+```
+
+此外，构造方法可指定自定义字段名称：`new CustomDataNameBuilder("data");`。
+设置后，数据节点将变成`data`
+
+```json
+{
+	"data": {
+		...
+	},
+	"sign": "xxxxx"
+}
+```
+
+**注**：网关设置了CustomDataNameBuilder后，SDK也要做相应的更改：`SdkConfig.dataNameBuilder = new CustomDataNameBuilder();`
--- a/doc/docs/files/10100_对接前端.md
+++ b/doc/docs/files/10100_对接前端.md
@@ -0,0 +1,145 @@
+# 对接前端
+
+开放平台一般对接服务端应用，开发者使用SDK来调用接口。
+理论上来说，只要是客户端程序，都可以调用网关接口。因此，同样可以对接前端应用（H5、小程序、App）。
+
+针对H5页面，配置方式如下：
+
+- 网关关闭签名校验。`ApiConfig.getInstance().setIgnoreValidate(true);`
+
+由于是网页调用接口，把秘钥放在前端意义不大，干脆直接关闭签名校验。
+
+- 设置统一的数据节点
+
+```java
+@Configuration
+public class ZuulConfig extends AlipayZuulConfiguration {
+
+    static {
+        ...
+        ApiConfig.getInstance().setIgnoreValidate(true);
+        ApiConfig.getInstance().setDataNameBuilder(new CustomDataNameBuilder());
+        ...
+    }
+
+}
+```
+
+设置后，网关统一的返回结果如下：
+
+```json
+{
+	"result": {
+		...
+	},
+	"sign": "xxxxx"
+}
+```
+
+- 封装请求工具【可选】
+
+封装请求，方便调用，针对vue的封装如下：
+
+```js
+// 创建axios实例
+const client = axios.create({
+  baseURL: process.env.BASE_API, // api 的 base_url
+  timeout: 5000, // 请求超时时间
+  headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
+})
+
+const RequestUtil = {
+  /**
+   * 请求接口
+   * @param method 接口名，如：goods.get,goods.get
+   * @param version 版本号，如：1.0
+   * @param data 请求数据，json格式
+   * @param callback 成功回调
+   * @param errorCallback 失败回调
+   */
+  post: function(method, version, data, callback, errorCallback) {
+    client.request({
+      method: method,
+      version: version,
+      biz_content: JSON.stringify(data)
+    }).then(function(response) {
+        const resp = response.result
+        const code = resp.code
+        // 成功，网关正常且业务正常
+        if (code === '10000' && !resp.sub_code) {
+          callback(resp)
+        } else {
+          // 报错
+          Message({
+            message: resp.msg,
+            type: 'error',
+            duration: 5 * 1000
+          })
+        }
+      })
+      .catch(function(error) {
+        console.log('err' + error) // for debug
+        errorCallback && errorCallback(error)
+      })
+  }
+}
+
+export default RequestUtil
+```
+
+jQuery版本如下：
+
+```js
+var RequestUtil = {
+    /**
+     * 请求接口
+     * @param method 接口名，如：goods.get,goods.get
+     * @param version 版本号，如：1.0
+     * @param data 请求数据，json格式
+     * @param callback 成功回调
+     * @param errorCallback 失败回调
+     */
+    post: function(method, version, data, callback, errorCallback) {
+        $.ajax({
+            url: 'http://localhost:8081/api' // 网关url
+            , type: 'post'
+            , headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
+            , data: {
+                method: method,
+                version: version,
+                biz_content: JSON.stringify(data)
+            }
+            ,success:function(response){
+                var resp = response.result
+                var code = resp.code
+                // 成功，网关正常且业务正常
+                if (code === '10000' && !resp.sub_code) {
+                    callback(resp)
+                } else {
+                    // 报错
+                    alert(resp.msg);
+                }
+            }
+            , error: function(error) {
+                errorCallback && errorCallback(error)
+            }
+        });
+    }
+}
+```
+
+jQuery调用示例：
+
+```js
+$(function () {
+    var data = {
+        id: 1
+        ,name: '葫芦娃'
+    }
+    RequestUtil.post('alipay.story.get', '1.0', data, function (result) {
+        console.log(result)
+    });
+})
+```
+
+