2.0

sop-sdk/sdk-csharp/SDKCSharp/Client/OpenClient.cs

@@ -16,50 +16,112 @@ using Newtonsoft.Json.Linq;
 namespace SDKCSharp.Client
 {
     /// <summary>
-    /// 客户端
+    /// 客户端，申明一个即可
     /// </summary>
     public class OpenClient
     {
-
+        /// <summary>
+        /// 默认配置
+        /// </summary>
         private static OpenConfig DEFAULT_CONFIG = new OpenConfig();
 
         private Dictionary<string, string> header = new Dictionary<string, string>();
 
-
+        /// <summary>
+        /// 接口请求url
+        /// </summary>
         private string url;
+
+        /// <summary>
+        /// 平台提供的appId
+        /// </summary>
         private string appId;
+
+        /// <summary>
+        /// 开放平台提供的私钥
+        /// </summary>
         private string privateKey;
+
+        /// <summary>
+        /// 开放平台提供的公钥
+        /// </summary>
         private string publicKeyPlatform;
 
+        /// <summary>
+        /// 配置项
+        /// </summary>
         private OpenConfig openConfig;
+
+        /// <summary>
+        /// 请求对象
+        /// </summary>
         private OpenRequest openRequest;
-        private DataNameBuilder dataNameBuilder;
 
+        /// <summary>
+        /// 节点处理
+        /// </summary>
+        private DataNameBuilder dataNameBuilder;
 
+        /// <summary>
+        /// 构建请求客户端
+        /// </summary>
+        /// <param name="url">接口url</param>
+        /// <param name="appId">平台分配的appId</param>
+        /// <param name="privateKey">平台分配的私钥</param>
         public OpenClient(string url, string appId, string privateKey)
             : this(url, appId, privateKey,false, DEFAULT_CONFIG)
         {
 
         }
 
+        /// <summary>
+        /// 构建请求客户端
+        /// </summary>
+        /// <param name="url">接口url</param>
+        /// <param name="appId">平台分配的appId</param>
+        /// <param name="privateKey">平台分配的私钥</param>
+        /// <param name="publicKeyPlatform">平台分配的公钥</param>
         public OpenClient(string url, string appId, string privateKey, string publicKeyPlatform)
             : this(url, appId, privateKey)
         {
             this.publicKeyPlatform = publicKeyPlatform;
         }
 
+        /// <summary>
+        /// 构建请求客户端
+        /// </summary>
+        /// <param name="url">接口url</param>
+        /// <param name="appId">平台分配的appId</param>
+        /// <param name="privateKey">平台分配的私钥</param>
+        /// <param name="priKeyFromFile">如果设置 <c>true</c> 从文件中加载私钥</param>
         public OpenClient(string url, string appId, string privateKey, bool priKeyFromFile)
             : this(url, appId, privateKey, priKeyFromFile, DEFAULT_CONFIG)
         {
 
         }
 
+        /// <summary>
+        /// 构建请求客户端
+        /// </summary>
+        /// <param name="url">接口url</param>
+        /// <param name="appId">平台分配的appId</param>
+        /// <param name="privateKey">平台分配的私钥</param>
+        /// <param name="priKeyFromFile">如果设置 <c>true</c> 从文件中加载私钥</param>
+        /// <param name="publicKeyPlatform">平台分配的公钥</param>
         public OpenClient(string url, string appId, string privateKey, bool priKeyFromFile, string publicKeyPlatform)
             : this(url, appId, privateKey, priKeyFromFile)
         {
             this.publicKeyPlatform = publicKeyPlatform;
         }
 
+        /// <summary>
+        /// 构建请求客户端
+        /// </summary>
+        /// <param name="url">接口url</param>
+        /// <param name="appId">平台分配的appId</param>
+        /// <param name="privateKey">平台分配的私钥</param>
+        /// <param name="priKeyFromFile">如果设置 <c>true</c> 从文件中加载私钥</param>
+        /// <param name="openConfig">配置项</param>
         public OpenClient(string url, string appId, string privateKey,bool priKeyFromFile, OpenConfig openConfig)
         {
             this.url = url;
@@ -75,6 +137,15 @@ namespace SDKCSharp.Client
             this.dataNameBuilder = openConfig.DataNameBuilder;
         }
 
+        /// <summary>
+        /// 构建请求客户端
+        /// </summary>
+        /// <param name="url">接口url</param>
+        /// <param name="appId">平台分配的appId</param>
+        /// <param name="privateKey">平台分配的私钥</param>
+        /// <param name="priKeyFromFile">如果设置 <c>true</c> 从文件中加载私钥</param>
+        /// <param name="publicKeyPlatform">平台分配的公钥</param>
+        /// <param name="openConfig">配置项</param>
         public OpenClient(string url, string appId, string privateKey, bool priKeyFromFile, string publicKeyPlatform, OpenConfig openConfig)
             : this(url, appId, privateKey, priKeyFromFile, openConfig)
         {
@@ -203,6 +274,14 @@ namespace SDKCSharp.Client
             }
         }
 
+        /// <summary>
+        /// 构建业务json内容。
+        /// 假设返回的结果是：{"alipay_story_get_response":{"msg":"Success","code":"10000","name":"海底小纵队","id":1},"sign":"xxx"}
+        /// 将解析得到：{"msg":"Success","code":"10000","name":"海底小纵队","id":1}
+        /// </summary>
+        /// <returns>The biz json.</returns>
+        /// <param name="rootNodeName">根节点名称.</param>
+        /// <param name="body">返回内容.</param>
         protected virtual string BuildBizJson(string rootNodeName, string body)
         {
             int indexOfRootNode = body.IndexOf(rootNodeName);
@@ -219,6 +298,14 @@ namespace SDKCSharp.Client
             return result;
         }
 
+        /// <summary>
+        /// 获取业务结果，如下结果：{"alipay_story_get_response":{"msg":"Success","code":"10000","name":"海底小纵队","id":1},"sign":"xxx"}
+        /// 将返回：{"msg":"Success","code":"10000","name":"海底小纵队","id":1}
+        /// </summary>
+        /// <returns>The json node data.</returns>
+        /// <param name="body">Body.</param>
+        /// <param name="rootNode">Root node.</param>
+        /// <param name="indexOfRootNode">Index of root node.</param>
         protected virtual string BuildJsonNodeData(string body, string rootNode, int indexOfRootNode)
         {
             int signDataStartIndex = indexOfRootNode + rootNode.Length + 2;

sop-sdk/sdk-java/src/main/java/com/gitee/sop/sdk/client/OpenClient.java

@@ -21,36 +21,85 @@ import java.util.Collections;
 import java.util.Map;
 
 /**
- * 请求客户端
+ * 请求客户端，申明一个即可
  *
  * @author tanghc
  */
 public class OpenClient {
     private static final Log log = LogFactory.getLog(OpenClient.class);
 
+    /**
+     * 默认配置
+     */
     private static final OpenConfig DEFAULT_CONFIG = new OpenConfig();
 
+    /**
+     * 接口请求url
+     */
     private String url;
+
+    /**
+     * 平台提供的appId
+     */
     private String appId;
+
+    /**
+     * 开放平台提供的私钥
+     */
     private String privateKey;
+
     /**
      * 开放平台提供的公钥
      */
     private String publicKeyPlatform;
 
+    /**
+     * 配置项
+     */
     private OpenConfig openConfig;
+
+    /**
+     * 请求对象
+     */
     private OpenRequest openRequest;
+
+    /**
+     * 节点处理
+     */
     private DataNameBuilder dataNameBuilder;
 
+    /**
+     * 构建请求客户端
+     *
+     * @param url           接口url
+     * @param appId         平台分配的appId
+     * @param privateKeyIsv 平台分配的私钥
+     */
     public OpenClient(String url, String appId, String privateKeyIsv) {
         this(url, appId, privateKeyIsv, DEFAULT_CONFIG);
     }
 
+    /**
+     * 构建请求客户端
+     *
+     * @param url               接口url
+     * @param appId             平台分配的appId
+     * @param privateKeyIsv     平台分配的私钥
+     * @param publicKeyPlatform 平台分配的公钥
+     */
     public OpenClient(String url, String appId, String privateKeyIsv, String publicKeyPlatform) {
         this(url, appId, privateKeyIsv);
         this.publicKeyPlatform = publicKeyPlatform;
     }
 
+    /**
+     * 构建请求客户端
+     *
+     * @param url           接口url
+     * @param appId         平台分配的appId
+     * @param privateKeyIsv 平台分配的私钥
+     * @param openConfig    配置项
+     */
     public OpenClient(String url, String appId, String privateKeyIsv, OpenConfig openConfig) {
         if (openConfig == null) {
             throw new IllegalArgumentException("openConfig不能为null");
@@ -64,6 +113,15 @@ public class OpenClient {
         this.dataNameBuilder = openConfig.getDataNameBuilder();
     }
 
+    /**
+     * 构建请求客户端
+     *
+     * @param url               接口url
+     * @param appId             平台分配的appId
+     * @param privateKeyIsv     平台分配的私钥
+     * @param publicKeyPlatform 平台分配的公钥
+     * @param openConfig        配置项
+     */
     public OpenClient(String url, String appId, String privateKeyIsv, String publicKeyPlatform, OpenConfig openConfig) {
         this(url, appId, privateKeyIsv, openConfig);
         this.publicKeyPlatform = publicKeyPlatform;
@@ -124,6 +182,14 @@ public class OpenClient {
         return openRequest.request(url, requestForm, header);
     }
 
+    /**
+     * 解析返回结果
+     *
+     * @param resp    返回结果
+     * @param request 请求对象
+     * @param <T>     返回结果
+     * @return 返回对于的Response对象
+     */
     protected <T extends BaseResponse> T parseResponse(String resp, BaseRequest<T> request) {
         String method = request.getMethod();
         String rootNodeName = dataNameBuilder.build(method);
@@ -148,6 +214,17 @@ public class OpenClient {
         return t;
     }
 
+    /**
+     * 构建业务json内容。
+     * 假设返回的结果是：<br>
+     * {"alipay_story_get_response":{"msg":"Success","code":"10000","name":"海底小纵队","id":1},"sign":"xxx"}
+     * 将解析得到：<br>
+     * {"msg":"Success","code":"10000","name":"海底小纵队","id":1}
+     *
+     * @param rootNodeName 根节点名称
+     * @param body         返回内容
+     * @return 返回业务json
+     */
     protected String buildBizJson(String rootNodeName, String body) {
         int indexOfRootNode = body.indexOf(rootNodeName);
         if (indexOfRootNode < 0) {
@@ -161,17 +238,42 @@ public class OpenClient {
         return result;
     }
 
+    /**
+     * 获取业务结果，如下结果：<br>
+     * {"alipay_story_get_response":{"msg":"Success","code":"10000","name":"海底小纵队","id":1},"sign":"xxx"}
+     * 将返回：<br>
+     * {"msg":"Success","code":"10000","name":"海底小纵队","id":1}
+     *
+     * @param body            返回内容
+     * @param rootNodeName    根节点名称
+     * @param indexOfRootNode 根节点名称位置
+     * @return 返回业务json内容
+     */
     protected String buildJsonNodeData(String body, String rootNodeName, int indexOfRootNode) {
+        /*
+          得到起始索引位置。{"alipay_story_get_response":{"msg":"Success","code":"10000","name":"海底小纵队","id":1},"sign":"xxx"}
+          得到第二个`{`索引位置
+         */
         int signDataStartIndex = indexOfRootNode + rootNodeName.length() + 2;
+        // 然后这里计算出"sign"字符串所在位置
         int indexOfSign = body.indexOf("\"" + openConfig.getSignName() + "\"");
         if (indexOfSign < 0) {
             return null;
         }
         int length = indexOfSign - 1;
+        // 根据起始位置和长度，截取出json：{"msg":"Success","code":"10000","name":"海底小纵队","id":1}
         return body.substring(signDataStartIndex, length);
     }
 
-    protected <T extends BaseResponse> boolean checkResponseSign(String signContent, String sign, String publicKeyPlatform) {
+    /**
+     * 校验返回结果中的sign
+     *
+     * @param signContent       校验内容
+     * @param sign              sign
+     * @param publicKeyPlatform 平台公钥
+     * @return true：正确
+     */
+    protected boolean checkResponseSign(String signContent, String sign, String publicKeyPlatform) {
         try {
             String charset = this.openConfig.getCharset();
             String signType = this.openConfig.getSignType();