https://github.com/jpush/jiguang-sdk-java
这是 Jiguang REST API 的 Java 版本封装开发包，是由极光推送官方提供的，一般支持最新的 API 功能。
https://github.com/jpush/jiguang-sdk-java
Last synced: 6 days ago
JSON representation
这是 Jiguang REST API 的 Java 版本封装开发包，是由极光推送官方提供的，一般支持最新的 API 功能。
- Host: GitHub
- URL: https://github.com/jpush/jiguang-sdk-java
- Owner: jpush
- License: apache-2.0
- Created: 2024-01-25T05:27:21.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-04-11T07:18:47.000Z (9 months ago)
- Last Synced: 2025-04-23T22:07:45.243Z (9 months ago)
- Language: Java
- Homepage:
- Size: 156 KB
- Stars: 23
- Watchers: 16
- Forks: 6
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# jiguang-sdk-java
这是 Jiguang REST API 的 Java 版本封装开发包，是由极光推送官方提供的，一般支持最新的 API 功能。
对应的 REST API 文档：
* [REST API - Push](https://docs.jiguang.cn/jpush/server/push/rest_api_v3_push)
* [REST API - Device](https://docs.jiguang.cn/jpush/server/push/rest_api_v3_device)
* [REST API - Report](https://docs.jiguang.cn/jpush/server/push/rest_api_v3_report)
* [REST API - GroupPush](https://docs.jiguang.cn/jpush/server/push/rest_api_v3_push_grouppush)
支持 Java JDK 1.8 及其以上版本。
> 支持 Java JDK 1.6 版本：[jpush-api-java-client](https://github.com/jpush/jpush-api-java-client)，但不再更新。
## 1. 集成
引入sdk包
```xml
io.github.jpush
jiguang-sdk
5.3.0
```
引入log包
> 注意项目中已引用了logback、log4j、commons-logging等实现slfj接口的日志框架，则不需要配置。例如'example-for-spring'中引入了spring，自带logback框架，就不需要再配置。
```xml
ch.qos.logback
logback-classic
1.2.11
```
## 2. Api
创建api对象
> 可根据自身情况设置client、host和loggerLevel
```java
// appKey和masterSecret在极光官网-应用控制台获取
PushApi pushApi = new PushApi.Builder()
.setAppKey(appKey)
.setMasterSecret(masterSecret)
.build();
DeviceApi deviceApi = new DeviceApi.Builder()
.setAppKey(appKey)
.setMasterSecret(masterSecret)
.build();
ReportApi reportApi = new ReportApi.Builder()
.setAppKey(appKey)
.setMasterSecret(masterSecret)
.build();
// groupKey和groupMasterSecret在极光官网-分组应用控制台获取
GroupPushApi groupPushApi = new GroupPushApi.Builder()
.setGroupKey(groupKey)
.setGroupMasterSecret(groupMasterSecret)
.build();
// 其他可自定义演示
okhttp3.OkHttpClient okHttpClient = new okhttp3.OkHttpClient().newBuilder()
// .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("proxy_host", proxy_port))) // 可自定义代理，可选
.build();
PushApi pushApi = new PushApi.Builder()
.setClient(new OkHttpClient(okHttpClient)) // sdk默认使用的feign-okhttp，可自定义，可选
.setOptions(new Request.Options(10, TimeUnit.SECONDS, 10, TimeUnit.SECONDS, false)) // 可自定义超时参数，可选
.setRetryer(new Retryer.Default(10, 10, 10)) // 可自定义重试参数，可选
.setLoggerLevel(Logger.Level.FULL) // 可自定义日志打印级别，可选
.setAppKey(appKey) // 必填
.setMasterSecret(masterSecret) // 必填
.build();
```
使用api示例
* [PushApi](https://github.com/jpush/jiguang-sdk-java/blob/main/example-for-spring/src/test/java/cn/jiguang/app/api/PushApiTest.java)
* [DeviceApi](https://github.com/jpush/jiguang-sdk-java/blob/main/example-for-spring/src/test/java/cn/jiguang/app/api/DeviceApiTest.java)
* [ReportApi](https://github.com/jpush/jiguang-sdk-java/blob/main/example-for-spring/src/test/java/cn/jiguang/app/api/ReportApiTest.java)
* [GroupPushApi](https://github.com/jpush/jiguang-sdk-java/blob/main/example-for-spring/src/test/java/cn/jiguang/app/api/GroupPushApiTest.java)
## 3. 异常处理与限流信息
### 异常处理
API 调用失败会抛出 `ApiErrorException`，可通过异常对象获取错误信息和限流信息：
```java
try {
PushSendResult result = pushApi.send(param);
log.info("send success:{}", result);
} catch (ApiErrorException e) {
// 错误信息
int httpStatus = e.getStats(); // HTTP状态码
int errorCode = e.getApiError().getError().getCode(); // 错误码
String errorMessage = e.getApiError().getError().getMessage(); // 错误信息
log.error("send error, code:{}, message:{}", errorCode, errorMessage);
}
```
### 限流信息
所有 Result 对象和 ApiErrorException 异常都包含限流信息，可通过 `getRateLimit()` 方法获取：
```java
RateLimit rateLimit = result.getRateLimit(); // 或 e.getRateLimit()
Integer limit = rateLimit.getLimit(); // 单位时间内最大请求次数
Integer remaining = rateLimit.getRemaining(); // 单位时间内剩余请求次数
Integer reset = rateLimit.getReset(); // 限流重置时间(秒)
```
### 日志配置
```yaml
# 配置中打开feign-debug日志打印
logging:
level:
feign.Logger: debug
```
* 排查问题，请务必`setLoggerLevel(Logger.Level.FULL)`，查看feign日志
> 打印类为feign.Logger，从---> POST，到<--- END HTTP，参考下图
* 如需技术支持，请提供使用环境、复现步骤、示例代码、日志信息
## 4. 第三方库引用说明
```
4.12.0
1.18.30
13.1
3.8.0
2.15.3
org.projectlombok
lombok
${lombok.version}
provided
io.github.openfeign
feign-core
${feign-core.version}
io.github.openfeign.form
feign-form
${feign-form.version}
io.github.openfeign
feign-slf4j
${feign-core.version}
io.github.openfeign
feign-okhttp
${feign-core.version}
io.github.openfeign
feign-jackson
${feign-core.version}
com.squareup.okhttp3
okhttp
${okhttp.version}
com.fasterxml.jackson.datatype
jackson-datatype-jsr310
${jackson-datatype-jsr310.version}
org.bouncycastle
bcpkix-jdk15on
1.68
```