Merge pull request #6 from Hyq0719/feature/hyq/2022/01/init

Feature/hyq/2022/01/init
Hyq0719 · Feb 11, 2022 · d27d818 · d27d818
2 parents 3decaf8 + 9fd9b9b
commit d27d818
Show file tree

Hide file tree

Showing 20 changed files with 283 additions and 52 deletions.
diff --git a/README.md b/README.md
@@ -1,20 +1,50 @@
-## Marketing API Java SDKs
-[![License](https://camo.githubusercontent.com/2a2157c971b7ae1deb8eb095799440551c33dcf61ea3d965d86b496a5a65df55/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d417061636865253230322e302d626c75652e737667)](https://opensource.org/licenses/Apache-2.0)  ![使用IntelliJ IDEA开发维护](https://camo.githubusercontent.com/5fa4dc7ff49e4a518c047200657e42382acaf0a612325e9fb560cd909d4b8902/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f496e74656c6c694a253230494445412d2545362538462539302545342542452539422545362539342541462545362538432538312d626c75652e737667)
+## Marketing API Java SDKs  [![LICENSE](https://camo.githubusercontent.com/6d2f1a361a07cd80444ad4a49998f95d10f81e634dcb0c80d4cb3038691d2544/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d416e74692532303939362d626c75652e737667)](https://github.com/996icu/996.ICU/blob/master/LICENSE) [![Badge](https://camo.githubusercontent.com/d043601dbaa32fcfcc1ad2b1901f09ad29f178428cf89dc9a6ea7991537770ea/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c696e6b2d3939362e6963752d7265642e737667)](https://996.icu/#/zh_CN)
 
-Marketing API Java SDKs 旨在对国内主流的Marketing API进行封装，帮助开发者快速搭建广告投放管理系统。 目前已完成了作者常用的Marketing API，如腾讯广告、巨量引擎和磁力引擎等。未来还会为更多Marketing API厂商进行封装，给开发者更好的使用体验，预计在2-3月发布第一个release版本。
+![Maven Central](https://img.shields.io/maven-central/v/io.github.hyq0719/marketing-api-sdk)  ![jdk1.8+](https://img.shields.io/badge/jdk-1.8%2B-green) [![License](https://camo.githubusercontent.com/2a2157c971b7ae1deb8eb095799440551c33dcf61ea3d965d86b496a5a65df55/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d417061636865253230322e302d626c75652e737667)](https://opensource.org/licenses/Apache-2.0) ![使用IntelliJ IDEA开发维护](https://camo.githubusercontent.com/5fa4dc7ff49e4a518c047200657e42382acaf0a612325e9fb560cd909d4b8902/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f496e74656c6c694a253230494445412d2545362538462539302545342542452539422545362539342541462545362538432538312d626c75652e737667)
 
+Marketing API Java SDKs 旨在对国内主流的Marketing API进行封装，帮助开发者快速搭建广告投放管理系统。 目前已完成了作者常用的Marketing API，如腾讯广告、巨量引擎、磁力引擎和vivo等。未来还会为更多Marketing API厂商进行封装，给开发者更好的使用体验，预计在2-3月发布第一个正式版本。
 
-### Maven 引用方式（待发布）
+
+### Maven 引用方式（未发布正式版）
 
 ```xml
 <dependency>
   <groupId>io.github.hyq0719</groupId>
   <artifactId>（不同模块参考下文）</artifactId>
-  <version>1.0.0-SNAPSHOT</version>
+  <version>1.0.0-beta.1</version>
 </dependency>
 ```
 
-- [腾讯广告](https://developers.e.qq.com/docs/start?version=1.3&_preview=1)：`marketing-api-tencent`
+- [腾讯广告](https://developers.e.qq.com/docs/start?version=1.3&_preview=1)：`marketing-api-tencent`  (待发布)
 - [巨量引擎](https://open.oceanengine.com/doc/index.html?key=ad&type=api&id=1696710497745920)：`marketing-api-oceanengine`
-- [磁力引擎](https://developers.e.kuaishou.com/docs/dsp/0.1)：`marketing-api-kuaishou`
-- [vivo](https://open-ad.vivo.com.cn/doc/index?id=162)：`marketing-api-vivo`
+- [磁力引擎](https://developers.e.kuaishou.com/docs/dsp/0.1)：`marketing-api-kuaishou`  (待发布)
+- [vivo](https://open-ad.vivo.com.cn/doc/index?id=162)：`marketing-api-vivo`
+
+### 22年计划
+
+- 各Marketing API厂商的时间分配（会根据开发效率、使用者需求和厂商爸爸支持程度进行调整）
+
+`新增`：新增该渠道的Marketing API Java SDK
+
+`全量`：开发完成所有接口
+
+`维护`：维护开发完成且使用中的接口
+
+|                             厂商                             |    人力分配    | 全量完成时间 |
+| :----------------------------------------------------------: | :------------: | :----------: |
+| [腾讯广告](https://developers.e.qq.com/docs/start?version=1.3&_preview=1) |      维护      |      待定      |
+| [巨量引擎](https://open.oceanengine.com/doc/index.html?key=ad&type=api&id=1696710497745920) |   全量+维护    |    2-3月     |
+|  [磁力引擎](https://developers.e.kuaishou.com/docs/dsp/0.1)  |      维护      |      待定      |
+| [百度营销](https://dev2.baidu.com/content?sceneType=0&pageId=100138&nodeId=15&subhead=) |      待定      |     待定     |
+|   [VIVO商业](https://open-ad.vivo.com.cn/doc/index?id=162)   |   全量+维护    |    2月底     |
+|       [小米营销](https://api.e.mi.com/doc.html#/home)        | 新增+全量+维护 |    2月底     |
+| [华为广告](https://developer.huawei.com/consumer/cn/doc/distribution/promotion/ads_api02-0000001058566534) | 新增+全量+维护 |    3-4月     |
+
+- 补全使用文档
+- 建立使用者社区和社区代码贡献机制
+
+### 致谢
+
+- 感谢 [TencentAd](https://github.com/TencentAd)/**[marketing-api-java-sdk ](https://github.com/TencentAd/marketing-api-java-sdk)** ，该项目使用了部分腾讯广告Marketing APi Java SDK的源码，通过学习腾讯广告源码大大减小了开发成本
+- 感谢 [Wechat-Group](https://github.com/Wechat-Group)/**[WxJava](https://github.com/Wechat-Group/WxJava)** ，该项目参考了WxJava的设计和命名规范
+
diff --git a/code-generators/pom.xml b/code-generators/pom.xml
@@ -8,7 +8,7 @@
   <parent>
     <groupId>io.github.hyq0719</groupId>
     <artifactId>marketing-api-sdk</artifactId>
-    <version>1.0.0-SNAPSHOT</version>
+    <version>1.0.0-beta.1</version>
   </parent>
 
   <artifactId>marketing-api-generators</artifactId>
@@ -19,6 +19,7 @@
   <properties>
     <maven.compiler.source>${java.version}</maven.compiler.source>
     <maven.compiler.target>${java.version}</maven.compiler.target>
+    <maven.deploy.skip>true</maven.deploy.skip>
   </properties>
 
   <modules>

diff --git a/marketing-api-common/pom.xml b/marketing-api-common/pom.xml
@@ -7,11 +7,11 @@
   <parent>
     <groupId>io.github.hyq0719</groupId>
     <artifactId>marketing-api-sdk</artifactId>
-    <version>1.0.0-SNAPSHOT</version>
+    <version>1.0.0-beta.1</version>
   </parent>
 
   <artifactId>marketing-api-common</artifactId>
-  <version>1.0.0-SNAPSHOT</version>
+  <version>1.0.0-beta.1</version>
   <name>Marketing API - Common Java SDK</name>
   <description>Marketing API Java SDK公共模块</description>
 

diff --git a/marketing-api-common/src/main/java/com/hyq0719/mktapi/common/ApiRequest.java b/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];
   }

diff --git a/marketing-api-common/src/main/java/com/hyq0719/mktapi/common/RetryStrategy.java b/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;
   }

diff --git a/marketing-api-common/src/main/java/com/hyq0719/mktapi/common/advice/ApiRequestAdvice.java b/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);
 }
diff --git a/...ting-api-common/src/main/java/com/hyq0719/mktapi/common/annotation/ApiRequestMapping.java b/...ting-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};
 }
diff --git a/marketing-api-common/src/main/java/com/hyq0719/mktapi/common/constant/AuthConstants.java b/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 {
 
   /**

diff --git a/...g-api-common/src/main/java/com/hyq0719/mktapi/common/executor/http/ApacheHttpHandler.java b/...g-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;

diff --git a/...ing-api-common/src/main/java/com/hyq0719/mktapi/common/executor/http/BaseHttpHandler.java b/...ing-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()) {