【common】补全注释

Author: Hyq0719

marketing-api-common/src/main/java/com/hyq0719/mktapi/common/ApiRequest.java

@@ -10,35 +10,50 @@
 import com.hyq0719.mktapi.common.util.StringUtil;
 import org.apache.commons.lang3.StringUtils;
 
-import java.io.File;
 import java.lang.reflect.ParameterizedType;
 import java.lang.reflect.Type;
 import java.util.*;
 
 public abstract class ApiRequest<T, R> implements ParamHandler<T> {
 
+  /**
+   * 响应类型Type
+   */
   private Type localVarReturnType = getRType();
 
   public R execute(T t) throws ApiException {
     return execute(t, null, null);
   }
 
   /**
-   * 新增钩子函数用于使用时增强
+   * 钩子函数用于使用时增强
    *
-   * @param t
-   * @param apiRequestAdvice
-   * @return
+   * @param t                请求
+   * @param apiRequestAdvice 请求增强
+   * @return 响应
    * @throws ApiException
    */
   public R execute(T t, ApiRequestAdvice apiRequestAdvice) throws ApiException {
     return execute(t, apiRequestAdvice, null);
   }
 
+  /**
+   * @param t     请求
+   * @param token access token, 传参后不去缓存中取token
+   * @return 响应
+   * @throws ApiException
+   */
   public R execute(T t, String token) throws ApiException {
     return execute(t, null, token);
   }
 
+  /**
+   * @param t                请求
+   * @param apiRequestAdvice 请求增强
+   * @param token            access token, 传参后不去缓存中取token
+   * @return
+   * @throws ApiException
+   */
   public R execute(T t, ApiRequestAdvice apiRequestAdvice, String token) throws ApiException {
     if (Objects.nonNull(apiRequestAdvice)) {
       apiRequestAdvice.before();
@@ -50,11 +65,17 @@ public R execute(T t, ApiRequestAdvice apiRequestAdvice, String token) throws Ap
     return retry(resp, t, apiRequestAdvice, token);
   }
 
+  /**
+   * 重试机制，默认不重试
+   */
   public R retry(ApiResponse<R> resp, T t, ApiRequestAdvice apiRequestAdvice, String token)
           throws ApiException {
     return resp.getData();
   }
 
+  /**
+   * 重试请求
+   */
   public R retryRequest(T t, ApiRequestAdvice apiRequestAdvice, String token) throws ApiException {
     if (Objects.nonNull(apiRequestAdvice)) {
       apiRequestAdvice.before();
@@ -66,6 +87,13 @@ public R retryRequest(T t, ApiRequestAdvice apiRequestAdvice, String token) thro
     return retryResponse.getData();
   }
 
+  /**
+   * 用注解和继承方法构造请求参数
+   *
+   * @param t     请求体
+   * @param token access token
+   * @return RequestParam 请求参数
+   */
   @Override
   public RequestParam constructParameters(T t, String token) {
     Object localVarPostBody = null;
@@ -195,6 +223,9 @@ protected ApiResponse<R> executeWithHttp(T t, String token) throws ApiException
     return getApiClient().execute(param, localVarReturnType);
   }
 
+  /**
+   * 响应类型Type
+   */
   private Type getRType() {
     return ((ParameterizedType) getClass().getGenericSuperclass()).getActualTypeArguments()[1];
   }

marketing-api-common/src/main/java/com/hyq0719/mktapi/common/RetryStrategy.java

@@ -1,34 +1,45 @@
 package com.hyq0719.mktapi.common;
 
+/**
+ * api请求重试策略
+ *
+ * @author hyq0719
+ */
 public interface RetryStrategy {
 
   /**
-   * 重试次数
+   * 重试次数，默认为3次
    *
-   * @return
+   * @return 重试次数
    */
   default Integer retryCount() {
     return 3;
   }
 
   /**
-   * 重试条件
+   * 根据各渠道返回码判断是否重试
    *
-   * @return
+   * @return 重试条件
    */
   default Boolean retryCondition(Long code) {
     return false;
   }
 
   /**
-   * 是否启用
+   * 是否开启重试
    *
-   * @return
+   * @return 是否开启重试
    */
   default Boolean enable() {
     return true;
   }
 
+  /**
+   * 根据返回码判断token是否过期
+   *
+   * @param code 请求返回码
+   * @return token是否过期
+   */
   default Boolean isTokenExpired(Long code) {
     return false;
   }

marketing-api-common/src/main/java/com/hyq0719/mktapi/common/advice/ApiRequestAdvice.java

@@ -2,12 +2,25 @@
 
 import com.hyq0719.mktapi.common.ApiResponse;
 
+/**
+ * api请求增强，类似AOP
+ *
+ * @author hyq0719
+ */
 @FunctionalInterface
 public interface ApiRequestAdvice {
 
+  /**
+   * 请求前执行
+   */
   default void before() {
 
   }
 
+  /**
+   * 请求后执行
+   *
+   * @param response 请求的返回内容
+   */
   void after(ApiResponse response);
 }

marketing-api-common/src/main/java/com/hyq0719/mktapi/common/annotation/ApiRequestMapping.java

@@ -5,19 +5,48 @@
 
 import java.lang.annotation.*;
 
+/**
+ * 请求参数注解
+ *
+ * @author hyq0719
+ */
 @Target({ElementType.METHOD, ElementType.TYPE})
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited
 public @interface ApiRequestMapping {
+  /**
+   * 请求路径后缀，和BaseUrl拼接
+   * @return 请求路径后缀
+   */
   String value();
 
+  /**
+   * 请求版本号，默认从BaseUrl获取
+   * @return 请求版本号
+   */
   String version() default "";
 
+  /**
+   * 请求host地址，默认从BaseUrl获取
+   * @return 请求host地址
+   */
   String host() default "";
 
+  /**
+   * 请求方法：GET，POST等
+   * @return 请求方法
+   */
   String method();
 
+  /**
+   * 是否使用请求体，默认为true
+   * @return 是否使用请求体
+   */
   boolean usePostBody() default true;
 
+  /**
+   * 请求头中的Content-Type
+   * @return Content-Type
+   */
   String[] contentTypes() default {RequestConstants.CONTENT_TYPE_JSON, RequestConstants.CONTENT_TYPE_XML};
 }

marketing-api-common/src/main/java/com/hyq0719/mktapi/common/constant/AuthConstants.java

@@ -1,5 +1,10 @@
 package com.hyq0719.mktapi.common.constant;
 
+/**
+ * 各渠道请求中的授权参数
+ *
+ * @author hyq0719
+ */
 public interface AuthConstants {
 
   /**

marketing-api-common/src/main/java/com/hyq0719/mktapi/common/executor/http/ApacheHttpHandler.java

@@ -131,6 +131,17 @@ public <T> T handleResponse(HttpResponse response, Type returnType) throws ApiEx
             code, toMultimap(response.getAllHeaders()), respBody);
   }
 
+  /**
+   * Deserialize response body to Java object, according to the return type and the Content-Type
+   * response header.
+   *
+   * @param <T>        Type
+   * @param response   HTTP response
+   * @param returnType The type of the Java object
+   * @return The deserialized Java object
+   * @throws ApiException If fail to deserialize response body, i.e. cannot read response body or
+   *                      the Content-Type of the response is not supported.
+   */
   public <T> T deserialize(HttpResponse response, Type returnType) throws ApiException {
     if (response == null || returnType == null) {
       return null;

marketing-api-common/src/main/java/com/hyq0719/mktapi/common/executor/http/BaseHttpHandler.java

@@ -9,10 +9,15 @@
 import java.net.URLEncoder;
 import java.util.List;
 
+/**
+ * HttpHandler抽象类，提供url构造的默认实现
+ *
+ * @author hyq0719
+ */
 public abstract class BaseHttpHandler implements HttpHandler {
 
-  private JSON json;
-  private boolean verifyingSsl;
+  private final JSON json;
+  private final boolean verifyingSsl;
 
   protected BaseHttpHandler() {
     json = new JSON();
@@ -72,6 +77,12 @@ public boolean isJsonMime(String mime) {
     return mime != null && (mime.matches(jsonMime) || "*/*".equals(mime));
   }
 
+  /**
+   * 添加请求参数
+   *
+   * @param url          当前url
+   * @param requestParam 请求参数
+   */
   private void appendQueryParams(StringBuilder url, RequestParam requestParam) {
     List<Pair> queryParams = requestParam.getQueryParams();
     if (queryParams != null && !queryParams.isEmpty()) {
@@ -92,6 +103,12 @@ private void appendQueryParams(StringBuilder url, RequestParam requestParam) {
     }
   }
 
+  /**
+   * 添加请求参数集合
+   *
+   * @param url          当前url
+   * @param requestParam 请求参数
+   */
   private void appendCollectionQueryParams(StringBuilder url, RequestParam requestParam) {
     List<Pair> collectionQueryParams = requestParam.getCollectionQueryParams();
     if (collectionQueryParams != null && !collectionQueryParams.isEmpty()) {

marketing-api-common/src/main/java/com/hyq0719/mktapi/common/executor/parameter/BaseUrl.java

@@ -3,12 +3,26 @@
 import lombok.Builder;
 import lombok.Data;
 
+/**
+ * 请求基础url
+ *
+ * @author hyq0719
+ */
 @Data
 @Builder
 public class BaseUrl {
-  String scheme;
-  String host;
-  String version;
+  /**
+   * 协议：http,https
+   */
+  private String scheme;
+  /**
+   * host地址
+   */
+  private String host;
+  /**
+   * api版本
+   */
+  private String version;
 
   @Override
   public String toString() {

marketing-api-common/src/main/java/com/hyq0719/mktapi/common/token/ExternalTokenService.java

@@ -4,7 +4,18 @@
 
 public interface ExternalTokenService {
 
+  /**
+   * 刷新所有token
+   *
+   * @return token列表
+   */
   List<IToken> refreshAllToken();
 
+  /**
+   * 刷新单个token
+   *
+   * @param tokenKey token key
+   * @return token
+   */
   IToken refreshToken(String tokenKey);
 }

marketing-api-common/src/main/java/com/hyq0719/mktapi/common/token/ITokenCronService.java

@@ -12,10 +12,14 @@
 @Slf4j
 public class ITokenCronService implements CronService {
 
+  /**
+   * 外部token授权服务
+   */
   private ExternalTokenService externalTokenService;
-
+  /**
+   * tokwn本地缓存
+   */
   private volatile ITokenLocalCache iTokenLocalCache;
-
   private String cron;
 
   public ITokenCronService(ExternalTokenService externalTokenService, ITokenLocalCache iTokenLocalCache,