Skip to content

Commit d27d818

Browse files
author
黄悦麒
authored
Merge pull request #6 from Hyq0719/feature/hyq/2022/01/init
Feature/hyq/2022/01/init
2 parents 3decaf8 + 9fd9b9b commit d27d818

File tree

20 files changed

+283
-52
lines changed

20 files changed

+283
-52
lines changed

‎README.md‎

Lines changed: 38 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,50 @@
1-
## Marketing API Java SDKs
2-
[![License](https://camo.githubusercontent.com/2a2157c971b7ae1deb8eb095799440551c33dcf61ea3d965d86b496a5a65df55/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d417061636865253230322e302d626c75652e737667)](https://opensource.org/licenses/Apache-2.0) ![使用IntelliJ IDEA开发维护](https://camo.githubusercontent.com/5fa4dc7ff49e4a518c047200657e42382acaf0a612325e9fb560cd909d4b8902/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f496e74656c6c694a253230494445412d2545362538462539302545342542452539422545362539342541462545362538432538312d626c75652e737667)
1+
## 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)
32

4-
Marketing API Java SDKs 旨在对国内主流的Marketing API进行封装，帮助开发者快速搭建广告投放管理系统。 目前已完成了作者常用的Marketing API，如腾讯广告、巨量引擎和磁力引擎等。未来还会为更多Marketing API厂商进行封装，给开发者更好的使用体验，预计在2-3月发布第一个release版本。
3+
![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)
54

5+
Marketing API Java SDKs 旨在对国内主流的Marketing API进行封装，帮助开发者快速搭建广告投放管理系统。 目前已完成了作者常用的Marketing API，如腾讯广告、巨量引擎、磁力引擎和vivo等。未来还会为更多Marketing API厂商进行封装，给开发者更好的使用体验，预计在2-3月发布第一个正式版本。
66

7-
### Maven 引用方式（待发布）
7+
8+
### Maven 引用方式（未发布正式版）
89

910
```xml
1011
<dependency>
1112
<groupId>io.github.hyq0719</groupId>
1213
<artifactId>（不同模块参考下文）</artifactId>
13-
<version>1.0.0-SNAPSHOT</version>
14+
<version>1.0.0-beta.1</version>
1415
</dependency>
1516
```
1617

17-
- [腾讯广告](https://developers.e.qq.com/docs/start?version=1.3&_preview=1)：`marketing-api-tencent`
18+
- [腾讯广告](https://developers.e.qq.com/docs/start?version=1.3&_preview=1)：`marketing-api-tencent` (待发布)
1819
- [巨量引擎](https://open.oceanengine.com/doc/index.html?key=ad&type=api&id=1696710497745920)：`marketing-api-oceanengine`
19-
- [磁力引擎](https://developers.e.kuaishou.com/docs/dsp/0.1)：`marketing-api-kuaishou`
20-
- [vivo](https://open-ad.vivo.com.cn/doc/index?id=162)：`marketing-api-vivo`
20+
- [磁力引擎](https://developers.e.kuaishou.com/docs/dsp/0.1)：`marketing-api-kuaishou` (待发布)
21+
- [vivo](https://open-ad.vivo.com.cn/doc/index?id=162)：`marketing-api-vivo`
22+
23+
### 22年计划
24+
25+
- 各Marketing API厂商的时间分配（会根据开发效率、使用者需求和厂商爸爸支持程度进行调整）
26+
27+
`新增`：新增该渠道的Marketing API Java SDK
28+
29+
`全量`：开发完成所有接口
30+
31+
`维护`：维护开发完成且使用中的接口
32+
33+
| 厂商 | 人力分配 | 全量完成时间 |
34+
| :----------------------------------------------------------: | :------------: | :----------: |
35+
| [腾讯广告](https://developers.e.qq.com/docs/start?version=1.3&_preview=1) | 维护 | 待定 |
36+
| [巨量引擎](https://open.oceanengine.com/doc/index.html?key=ad&type=api&id=1696710497745920) | 全量+维护 | 2-3月 |
37+
| [磁力引擎](https://developers.e.kuaishou.com/docs/dsp/0.1) | 维护 | 待定 |
38+
| [百度营销](https://dev2.baidu.com/content?sceneType=0&pageId=100138&nodeId=15&subhead=) | 待定 | 待定 |
39+
| [VIVO商业](https://open-ad.vivo.com.cn/doc/index?id=162) | 全量+维护 | 2月底 |
40+
| [小米营销](https://api.e.mi.com/doc.html#/home) | 新增+全量+维护 | 2月底 |
41+
| [华为广告](https://developer.huawei.com/consumer/cn/doc/distribution/promotion/ads_api02-0000001058566534) | 新增+全量+维护 | 3-4月 |
42+
43+
- 补全使用文档
44+
- 建立使用者社区和社区代码贡献机制
45+
46+
### 致谢
47+
48+
- 感谢 [TencentAd](https://github.com/TencentAd)/**[marketing-api-java-sdk ](https://github.com/TencentAd/marketing-api-java-sdk)** ，该项目使用了部分腾讯广告Marketing APi Java SDK的源码，通过学习腾讯广告源码大大减小了开发成本
49+
- 感谢 [Wechat-Group](https://github.com/Wechat-Group)/**[WxJava](https://github.com/Wechat-Group/WxJava)** ，该项目参考了WxJava的设计和命名规范
50+

‎code-generators/pom.xml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
<parent>
99
<groupId>io.github.hyq0719</groupId>
1010
<artifactId>marketing-api-sdk</artifactId>
11-
<version>1.0.0-SNAPSHOT</version>
11+
<version>1.0.0-beta.1</version>
1212
</parent>
1313

1414
<artifactId>marketing-api-generators</artifactId>
@@ -19,6 +19,7 @@
1919
<properties>
2020
<maven.compiler.source>${java.version}</maven.compiler.source>
2121
<maven.compiler.target>${java.version}</maven.compiler.target>
22+
<maven.deploy.skip>true</maven.deploy.skip>
2223
</properties>
2324

2425
<modules>

‎marketing-api-common/pom.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,11 +7,11 @@
77
<parent>
88
<groupId>io.github.hyq0719</groupId>
99
<artifactId>marketing-api-sdk</artifactId>
10-
<version>1.0.0-SNAPSHOT</version>
10+
<version>1.0.0-beta.1</version>
1111
</parent>
1212

1313
<artifactId>marketing-api-common</artifactId>
14-
<version>1.0.0-SNAPSHOT</version>
14+
<version>1.0.0-beta.1</version>
1515
<name>Marketing API - Common Java SDK</name>
1616
<description>Marketing API Java SDK公共模块</description>
1717

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

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -10,35 +10,50 @@
1010
import com.hyq0719.mktapi.common.util.StringUtil;
1111
import org.apache.commons.lang3.StringUtils;
1212

13-
import java.io.File;
1413
import java.lang.reflect.ParameterizedType;
1514
import java.lang.reflect.Type;
1615
import java.util.*;
1716

1817
public abstract class ApiRequest<T, R> implements ParamHandler<T> {
1918

19+
/**
20+
* 响应类型Type
21+
*/
2022
private Type localVarReturnType = getRType();
2123

2224
public R execute(T t) throws ApiException {
2325
return execute(t, null, null);
2426
}
2527

2628
/**
27-
* 新增钩子函数用于使用时增强
29+
* 钩子函数用于使用时增强
2830
*
29-
* @param t
30-
* @param apiRequestAdvice
31-
* @return
31+
* @param t 请求
32+
* @param apiRequestAdvice 请求增强
33+
* @return 响应
3234
* @throws ApiException
3335
*/
3436
public R execute(T t, ApiRequestAdvice apiRequestAdvice) throws ApiException {
3537
return execute(t, apiRequestAdvice, null);
3638
}
3739

40+
/**
41+
* @param t 请求
42+
* @param token access token, 传参后不去缓存中取token
43+
* @return 响应
44+
* @throws ApiException
45+
*/
3846
public R execute(T t, String token) throws ApiException {
3947
return execute(t, null, token);
4048
}
4149

50+
/**
51+
* @param t 请求
52+
* @param apiRequestAdvice 请求增强
53+
* @param token access token, 传参后不去缓存中取token
54+
* @return
55+
* @throws ApiException
56+
*/
4257
public R execute(T t, ApiRequestAdvice apiRequestAdvice, String token) throws ApiException {
4358
if (Objects.nonNull(apiRequestAdvice)) {
4459
apiRequestAdvice.before();
@@ -50,11 +65,17 @@ public R execute(T t, ApiRequestAdvice apiRequestAdvice, String token) throws Ap
5065
return retry(resp, t, apiRequestAdvice, token);
5166
}
5267

68+
/**
69+
* 重试机制，默认不重试
70+
*/
5371
public R retry(ApiResponse<R> resp, T t, ApiRequestAdvice apiRequestAdvice, String token)
5472
throws ApiException {
5573
return resp.getData();
5674
}
5775

76+
/**
77+
* 重试请求
78+
*/
5879
public R retryRequest(T t, ApiRequestAdvice apiRequestAdvice, String token) throws ApiException {
5980
if (Objects.nonNull(apiRequestAdvice)) {
6081
apiRequestAdvice.before();
@@ -66,6 +87,13 @@ public R retryRequest(T t, ApiRequestAdvice apiRequestAdvice, String token) thro
6687
return retryResponse.getData();
6788
}
6889

90+
/**
91+
* 用注解和继承方法构造请求参数
92+
*
93+
* @param t 请求体
94+
* @param token access token
95+
* @return RequestParam 请求参数
96+
*/
6997
@Override
7098
public RequestParam constructParameters(T t, String token) {
7199
Object localVarPostBody = null;
@@ -195,6 +223,9 @@ protected ApiResponse<R> executeWithHttp(T t, String token) throws ApiException
195223
return getApiClient().execute(param, localVarReturnType);
196224
}
197225

226+
/**
227+
* 响应类型Type
228+
*/
198229
private Type getRType() {
199230
return ((ParameterizedType) getClass().getGenericSuperclass()).getActualTypeArguments()[1];
200231
}

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

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,45 @@
11
package com.hyq0719.mktapi.common;
22

3+
/**
4+
* api请求重试策略
5+
*
6+
* @author hyq0719
7+
*/
38
public interface RetryStrategy {
49

510
/**
6-
* 重试次数
11+
* 重试次数，默认为3次
712
*
8-
* @return
13+
* @return 重试次数
914
*/
1015
default Integer retryCount() {
1116
return 3;
1217
}
1318

1419
/**
15-
* 重试条件
20+
* 根据各渠道返回码判断是否重试
1621
*
17-
* @return
22+
* @return 重试条件
1823
*/
1924
default Boolean retryCondition(Long code) {
2025
return false;
2126
}
2227

2328
/**
24-
* 是否启用
29+
* 是否开启重试
2530
*
26-
* @return
31+
* @return 是否开启重试
2732
*/
2833
default Boolean enable() {
2934
return true;
3035
}
3136

37+
/**
38+
* 根据返回码判断token是否过期
39+
*
40+
* @param code 请求返回码
41+
* @return token是否过期
42+
*/
3243
default Boolean isTokenExpired(Long code) {
3344
return false;
3445
}

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

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,25 @@
22

33
import com.hyq0719.mktapi.common.ApiResponse;
44

5+
/**
6+
* api请求增强，类似AOP
7+
*
8+
* @author hyq0719
9+
*/
510
@FunctionalInterface
611
public interface ApiRequestAdvice {
712

13+
/**
14+
* 请求前执行
15+
*/
816
default void before() {
917

1018
}
1119

20+
/**
21+
* 请求后执行
22+
*
23+
* @param response 请求的返回内容
24+
*/
1225
void after(ApiResponse response);
1326
}

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

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,19 +5,48 @@
55

66
import java.lang.annotation.*;
77

8+
/**
9+
* 请求参数注解
10+
*
11+
* @author hyq0719
12+
*/
813
@Target({ElementType.METHOD, ElementType.TYPE})
914
@Retention(RetentionPolicy.RUNTIME)
1015
@Inherited
1116
public @interface ApiRequestMapping {
17+
/**
18+
* 请求路径后缀，和BaseUrl拼接
19+
* @return 请求路径后缀
20+
*/
1221
String value();
1322

23+
/**
24+
* 请求版本号，默认从BaseUrl获取
25+
* @return 请求版本号
26+
*/
1427
String version() default "";
1528

29+
/**
30+
* 请求host地址，默认从BaseUrl获取
31+
* @return 请求host地址
32+
*/
1633
String host() default "";
1734

35+
/**
36+
* 请求方法：GET，POST等
37+
* @return 请求方法
38+
*/
1839
String method();
1940

41+
/**
42+
* 是否使用请求体，默认为true
43+
* @return 是否使用请求体
44+
*/
2045
boolean usePostBody() default true;
2146

47+
/**
48+
* 请求头中的Content-Type
49+
* @return Content-Type
50+
*/
2251
String[] contentTypes() default {RequestConstants.CONTENT_TYPE_JSON, RequestConstants.CONTENT_TYPE_XML};
2352
}

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
package com.hyq0719.mktapi.common.constant;
22

3+
/**
4+
* 各渠道请求中的授权参数
5+
*
6+
* @author hyq0719
7+
*/
38
public interface AuthConstants {
49

510
/**

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,17 @@ public <T> T handleResponse(HttpResponse response, Type returnType) throws ApiEx
131131
code, toMultimap(response.getAllHeaders()), respBody);
132132
}
133133

134+
/**
135+
* Deserialize response body to Java object, according to the return type and the Content-Type
136+
* response header.
137+
*
138+
* @param <T> Type
139+
* @param response HTTP response
140+
* @param returnType The type of the Java object
141+
* @return The deserialized Java object
142+
* @throws ApiException If fail to deserialize response body, i.e. cannot read response body or
143+
* the Content-Type of the response is not supported.
144+
*/
134145
public <T> T deserialize(HttpResponse response, Type returnType) throws ApiException {
135146
if (response == null || returnType == null) {
136147
return null;

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

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,15 @@
99
import java.net.URLEncoder;
1010
import java.util.List;
1111

12+
/**
13+
* HttpHandler抽象类，提供url构造的默认实现
14+
*
15+
* @author hyq0719
16+
*/
1217
public abstract class BaseHttpHandler implements HttpHandler {
1318

14-
private JSON json;
15-
private boolean verifyingSsl;
19+
private final JSON json;
20+
private final boolean verifyingSsl;
1621

1722
protected BaseHttpHandler() {
1823
json = new JSON();
@@ -72,6 +77,12 @@ public boolean isJsonMime(String mime) {
7277
return mime != null && (mime.matches(jsonMime) || "*/*".equals(mime));
7378
}
7479

80+
/**
81+
* 添加请求参数
82+
*
83+
* @param url 当前url
84+
* @param requestParam 请求参数
85+
*/
7586
private void appendQueryParams(StringBuilder url, RequestParam requestParam) {
7687
List<Pair> queryParams = requestParam.getQueryParams();
7788
if (queryParams != null && !queryParams.isEmpty()) {
@@ -92,6 +103,12 @@ private void appendQueryParams(StringBuilder url, RequestParam requestParam) {
92103
}
93104
}
94105

106+
/**
107+
* 添加请求参数集合
108+
*
109+
* @param url 当前url
110+
* @param requestParam 请求参数
111+
*/
95112
private void appendCollectionQueryParams(StringBuilder url, RequestParam requestParam) {
96113
List<Pair> collectionQueryParams = requestParam.getCollectionQueryParams();
97114
if (collectionQueryParams != null && !collectionQueryParams.isEmpty()) {

0 commit comments

Comments
 (0)