# dppnetwork

**Repository Path**: gzlpsdp/dppnetwork

## Basic Information

- **Project Name**: dppnetwork
- **Description**: 最新的网络请求封装
- **Primary Language**: Android
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 网络请求库使用文档

[![](https://jitpack.io/v/com.gitee.gzlpsdp/dppnetwork.svg)](https://jitpack.io/#com.gitee.gzlpsdp/dppnetwork)


## 📖 概述

Pd网络请求库是一个基于 OkHttp 4.12.0 封装的 Android 网络通信组件，专为现代 Android 开发设计。它提供了同步/异步请求、文件上传/下载、自动 Token 管理（含并发刷新锁）、进度回调、自动重试、缓存策略、日志脱敏等完备的企业级特性。
本库全面适配 minSdk = 24 (Android 7.0) 至 targetSdk = 36 (Android 15)，在稳定性、性能和安全性上均经过精心打磨。

## 🚀 快速开始

**1. 添加依赖**

```gradle
dependencies {
     implementation 'com.gitee.gzlpsdp:dpnetwork:tag'
}
```

**2. 初始化（在 Application 中）**

```java
public class MyApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        // ① 初始化 Token 管理器（支持加密存储）
        TokenManager.init(this);

        // ② 构建配置
        HttpConfig config = new HttpConfig.Builder("https://api.example.com/")
                .setConnectTimeout(10000)
                .setReadTimeout(15000)
                .setWriteTimeout(15000)
                .setEnableLog(BuildConfig.DEBUG)   // 调试时开启日志
                .setAutoAddToken(true)
                .setTokenHeaderName("Authorization")
                .setTokenPrefix("Bearer ")
                .setRefreshUrl("/api/auth/refresh") // 可选：自动刷新
                .setRetryCount(2)                  // 可选：重试2次
                .setCache(getCacheDir().getAbsolutePath(), 10 * 1024 * 1024) // 可选：10MB缓存
                .addCommonHeader("platform", "android")
                .addStaticHeader("X-App-ID", "your-app-id")
                .build();

        // ③ 注入配置
        HttpManager.getInstance().setup(config);
    }
}
```

**3. 权限声明（AndroidManifest.xml）**

```xml
<uses-permission android:name="android.permission.INTERNET" />
<!-- 若使用 HTTP 明文请求，需允许 -->
<application android:usesCleartextTraffic="true" ... />
```

## 📚 核心 API 详解

所有网络回调均运行在主线程，可直接更新 UI。

**🔹 GET 请求**

***异步 GET（带参数）***
```java
public <T> void getAsync(String url, 
                         Map<String, Object> params, 
                         Class<T> clazz, 
                         HttpCallback<T> callback, 
                         String tag)
                    
public <T> void getAsync(String url, 
                         Map<String, Object> params, 
                         Class<T> clazz, 
                         HttpCallback<T> callback, 
                         String tag, 
                         boolean addToken)
```

***参数说明：***

- url：相对路径（自动拼接 baseUrl）或绝对 URL

- params：查询参数（null 表示无参数）

- clazz：期望返回的 Class 类型

- callback：回调接口

- tag：请求标签，用于取消

- addToken：是否自动添加 Token（覆盖全局设置）

***示例：***

```java
Map<String, Object> params = new HashMap<>();
params.put("page", 1);
params.put("limit", 20);

HttpManager.getInstance().getAsync("/api/users", params, UserList.class,
        new HttpCallback<UserList>() {
            @Override
            public void onSuccess(UserList result) {
                // 成功
            }
            @Override
            public void onError(int code, String message) {
                // 服务器错误
            }
            @Override
            public void onFailure(Throwable throwable) {
                // 网络异常
            }
        }, "get_users");
```

***异步 GET（带自定义 Header）***

```java
public <T> void getAsync(String url, 
                         Map<String, Object> params, 
                         Map<String, String> headers, 
                         Class<T> clazz, 
                         HttpCallback<T> callback, 
                         String tag, 
                         boolean addToken)
```

***解析泛型（Type 重载）***

```java
public <T> void getAsync(String url, 
                         Map<String, Object> params, 
                         Type type, 
                         HttpCallback<T> callback, 
                         String tag, 
                         boolean addToken)
```

用于解析嵌套泛型，例如 `Result<List<Article>>`：

```java
Type type = new TypeToken<Result<List<Article>>>(){}.getType();
HttpManager.getInstance().getAsync("/api/articles", null, type,
        new HttpCallback<Result<List<Article>>>() {
            @Override
            public void onSuccess(Result<List<Article>> result) {
                List<Article> articles = result.getData();
            }
            // ...
        }, "get_articles");

```

**🔹 POST 请求**

***表单提交***

```java
public <T> void postAsync(String url, 
                          Map<String, Object> params, 
                          Class<T> clazz, 
                          HttpCallback<T> callback, 
                          String tag, 
                          boolean addToken)

public <T> void postAsync(String url, 
                          Map<String, Object> params, 
                          Map<String, String> headers, 
                          Class<T> clazz, 
                          HttpCallback<T> callback, 
                          String tag, 
                          boolean addToken)

```

***JSON 提交***

```java
public <T> void postAsync(String url, 
                          String json, 
                          Class<T> clazz, 
                          HttpCallback<T> callback, 
                          String tag, 
                          boolean addToken)

public <T> void postAsync(String url, 
                          String json, 
                          Map<String, String> headers, 
                          Class<T> clazz, 
                          HttpCallback<T> callback, 
                          String tag, 
                          boolean addToken)
```

***示例：***

```java
Map<String, Object> params = new HashMap<>();
params.put("username", "user@example.com");
params.put("password", "pass123");

HttpManager.getInstance().postAsync("/api/login", params, LoginResponse.class,
        new HttpCallback<LoginResponse>() {
            @Override
            public void onSuccess(LoginResponse result) {
                // 登录成功
            }
            // ...
        }, "login", false); // 登录接口无需 Token
```

**🔹 文件上传**

```java
public <T> void uploadFile(String url, 
                           File file, 
                           String fileKey, 
                           Map<String, Object> params, 
                           Class<T> clazz, 
                           ProgressCallback<T> callback, 
                           String tag)


public <T> void uploadFile(String url, 
                           File file, 
                           String fileKey, 
                           Map<String, Object> params, 
                           Map<String, String> headers, 
                           Class<T> clazz, 
                           ProgressCallback<T> callback, 
                           String tag)
```

- file：要上传的文件

- fileKey：表单中的字段名（对应服务端接收的参数名）

- params：额外的表单参数（可为 null）

***示例：***

```java
File image = new File("/path/to/photo.jpg");
HttpManager.getInstance().uploadFile("/api/upload", image, "avatar", null,
        UploadResponse.class, new ProgressCallback<UploadResponse>() {
            @Override
            public void onProgress(long currentBytes, long totalBytes, float progress) {
                // 更新进度
            }
            @Override
            public void onSuccess(UploadResponse data) {
                // 上传成功
            }
            // 错误回调
        }, "upload_avatar");
```

**🔹 文件下载**

```java
public void downloadFile(String url, 
                         String savePath, 
                         ProgressCallback<File> callback, 
                         String tag)
```

- savePath：文件保存的绝对路径（包含文件名）

- 下载进度在主线程回调

***示例：***

```java
String savePath = getExternalFilesDir(Environment.DIRECTORY_DOWNLOADS)
        + "/document.pdf";
HttpManager.getInstance().downloadFile("https://example.com/file.pdf", savePath,
        new ProgressCallback<File>() {
            @Override
            public void onProgress(long current, long total, float progress) {
                // 更新进度
            }
            @Override
            public void onSuccess(File file) {
                // 下载完成
            }
            // ...
        }, "download_pdf");
```

**🔹 同步请求（需在子线程调用）**

所有同步方法均返回 HttpResponse<T> 对象，包含数据、状态码和错误信息。

```java
public <T> HttpResponse<T> getSync(String url, Map<String, Object> params, Class<T> clazz)
public <T> HttpResponse<T> getSync(String url, Map<String, Object> params, Type type)
public <T> HttpResponse<T> getSync(String url, Class<T> clazz) // params 为 null

public <T> HttpResponse<T> postSync(String url, Map<String, Object> params, Class<T> clazz)
public <T> HttpResponse<T> postSync(String url, Map<String, Object> params, Type type)
public <T> HttpResponse<T> postSync(String url, String json, Class<T> clazz)
public <T> HttpResponse<T> postSync(String url, String json, Type type)
```

***示例：***

```java
new Thread(() -> {
    HttpResponse<User> response = HttpManager.getInstance()
            .getSync("/api/user/123", null, User.class);
    if (response.isSuccess()) {
        User user = response.getData();
        runOnUiThread(() -> updateUI(user));
    } else {
        runOnUiThread(() -> showError(response.getMessage()));
    }
}).start();
```

**🔹 Token 管理**

```java
// 保存双 Token（推荐）
public void setTokens(String accessToken, String refreshToken)

// 仅设置 Access Token（Refresh Token 保持不变）
public void setToken(String token)

// 兼容旧版（tokenType 参数不存储）
public void setToken(String token, String tokenType)

// 获取当前 Access Token
public String getToken()

// 清除所有 Token
public void clearToken()
```

***注意：*** 调用 setTokens 后，库会自动处理 Token 刷新（需在 HttpConfig 中配置 refreshUrl）。

**🔹 请求头管理**

所有头方法操作全局配置，对后续所有请求生效。

```java
// 公共请求头（可被动态头覆盖）
public void addCommonHeader(String key, String value)
public void removeCommonHeader(String key)
public void clearCommonHeaders()

// 静态请求头（优先级最高，不可被覆盖）
public void addStaticHeader(String key, String value)
public void removeStaticHeader(String key)
public void clearStaticHeaders()
```

***优先级：*** 静态头 > 动态头（调用时传入） > 公共头。


**🔹 请求取消**

```java
// 取消指定标签的请求
public void cancelRequest(String tag)

// 取消所有进行中的请求
public void cancelAllRequests()
```

***建议：*** 在 onStop 或 onDestroy 中取消请求，避免内存泄漏。

**🔹 进度回调（ProgressCallback<T>）**

继承自 HttpCallback<T>，额外提供一个进度方法：

```java
void onProgress(long currentBytes, long totalBytes, float progress);
```

- currentBytes：当前已传输字节数

- totalBytes：总字节数（若未知则为 -1）

- progress：进度百分比（0.0 ~ 1.0）

**🔹 错误处理**

所有异步请求的 onFailure(Throwable throwable) 中抛出的异常为 HttpException，其中包含了 NetworkError 枚举，便于细化处理：

```java
@Override
public void onFailure(Throwable throwable) {
    if (throwable instanceof HttpException) {
        HttpException e = (HttpException) throwable;
        switch (e.getError()) {
            case TIMEOUT:          // 超时
            case TOKEN_EXPIRED:    // Token 过期
            case REFRESH_FAILED:   // 刷新 Token 失败
            case CANCELED:         // 请求被取消
            // ...
        }
    }
}
```

NetworkError 枚举完整列表：

|枚举值 |	说明|
|----|----|
NETWORK_IO	|IO 异常
TIMEOUT|	超时
PARSE_ERROR|	数据解析失败
UNKNOWN_HOST|	未知主机
SSL_ERROR|	SSL 证书错误
CANCELED|	请求被取消
TOKEN_EXPIRED|	Token 过期
REFRESH_FAILED|	刷新 Token 失败
SERVER_ERROR|	服务端错误 (5xx)
CLIENT_ERROR|	客户端错误 (4xx)
UNKNOWN|	未知错误

## ⚙️ 配置选项（HttpConfig）

|方法	|类型	|默认值	    |描述|
|----|----|----|----|
setBaseUrl(String)	|String	|必须	|基础 URL，支持相对路径拼接
setConnectTimeout(long)|	long|	15000ms	|连接超时
setReadTimeout(long)|	long|	15000ms	|读取超时
setWriteTimeout(long)|	long|	15000ms	|写入超时
setRetryOnConnectionFailure(boolean)|	boolean	|true	|连接失败是否重试
setEnableLog(boolean)|	boolean	|true	|是否启用日志（自动脱敏）
setAutoAddToken(boolean)|	boolean	|true	|是否自动添加 Token
setTokenHeaderName(String)	|String	|"Authorization"	|Token 头部字段名
setTokenPrefix(String)|	String|	"Bearer "	|Token 前缀
setRefreshUrl(String)|	String|	null	|刷新 Token 的接口路径（相对或绝对）
setRefreshMethod(String)|	String|	"POST"	|刷新请求方法
setRefreshWithEmptyBody(boolean)|	boolean|	true|	刷新请求是否发送空 body
setRetryCount(int)|	int|	0|	失败后自动重试次数（0 为不重试）
setCache(String, long)|	String, long	|null, 0	|缓存目录和大小（字节），0 表示不启用
addCommonHeader(String, String)|	-	|-	|添加公共请求头
addStaticHeader(String, String)|	-	|-	|添加静态请求头（最高优先级）


## 🧩 回调接口

**`HttpCallback<T>`**

```java
public interface HttpCallback<T> {
    void onSuccess(T result);
    void onError(int code, String message);
    void onFailure(Throwable throwable);
}
```

- onSuccess：请求成功，result 为解析后的数据

- onError：服务器返回错误（HTTP 状态码 >= 400），code 为状态码

- onFailure：网络层异常（超时、解析错误、取消等），throwable 通常为 HttpException

**`ProgressCallback<T>`（继承自 HttpCallback<T>）

```java
public interface ProgressCallback<T> extends HttpCallback<T> {
    void onProgress(long currentBytes, long totalBytes, float progress);
}
```

用于上传/下载进度通知。

## 🔥 高级功能

**1. Token 自动刷新（含并发锁）**

- 开启：在 HttpConfig 中设置 refreshUrl

- 自动行为：

    - 所有请求默认携带 Access Token（可通过 addToken 参数控制）

    - 当收到 401 响应时，自动发起刷新请求（使用 Refresh Token）

    - 若同时多个请求收到 401，仅第一个请求触发刷新，其余请求等待刷新完成并自动使用新 Token 重试

    - 刷新成功 → 更新本地 Token，重试原请求；刷新失败 → 清除本地 Token

自定义刷新处理器（适用于 JSON 响应等）：

```java
public class MyRefreshHandler implements RefreshTokenHandler {
    @Override
    public Request buildRefreshRequest(String refreshToken) {
        String json = "{\"refreshToken\":\"" + refreshToken + "\"}";
        RequestBody body = RequestBody.create(json, MediaType.parse("application/json"));
        return new Request.Builder()
                .url("https://api.example.com/v2/token/refresh")
                .post(body)
                .build();
    }

    @Override
    public String parseNewAccessToken(Response response) {
        try {
            JSONObject obj = new JSONObject(response.body().string());
            return obj.getString("accessToken");
        } catch (Exception e) {
            return null;
        }
    }
}
// 注册：
TokenManager.getInstance().setRefreshTokenHandler(new MyRefreshHandler());
```

**2. 自动重试**

通过 .setRetryCount(n) 配置，当请求因网络超时、服务端 5xx 错误等失败时，自动按 1s、2s、3s… 的退避间隔重试，直至成功或达到最大次数。

**3. HTTP 缓存**

通过 .setCache(cacheDir, cacheSize) 启用 OkHttp 缓存，缓存遵循 HTTP 响应头（如 Cache-Control），可显著减少重复网络请求。

## ⚠️ 注意事项

- 主线程限制

    - 异步回调均在主线程执行，可直接更新 UI。

    - 同步请求必须在子线程调用，否则抛出 NetworkOnMainThreadException。

- 内存泄漏

    - 在 Activity/Fragment 销毁时，建议通过 cancelRequest(tag) 取消对应请求，避免回调持有引用。

- 权限

    - 必须声明 INTERNET 权限。

    - Android 9+ 若使用 HTTP（非 HTTPS）需设置 android:usesCleartextTraffic="true"。

- Token 安全

    - Token 默认使用 AndroidX Security 加密存储（需调用 TokenManager.init(context)），若设备不支持则自动降级为普通 SharedPreferences。

- 日志脱敏

    - 日志中 Authorization、Cookie 等敏感头部会被自动脱敏（仅显示部分字符），确保调试安全。

- 请求标签

    - 每个请求建议指定唯一的 tag，以便精确取消。

- 文件操作

    - 文件上传/下载需要读写存储权限（根据 Android 版本动态申请）。

## ❓ 常见问题

**Q：如何关闭日志？**

A：new HttpConfig.Builder(...).setEnableLog(false)

**Q：如何让某个请求不自动添加 Token？**

A：调用方法时最后传入 false，例如 getAsync(..., false)。

**Q：同步请求为什么在子线程？**

A：Android 不允许主线程网络请求，否则崩溃。

**Q：Token 刷新失败后怎么办？**

A：库会自动清除 Token，你可以在 onFailure 中捕获 NetworkError.REFRESH_FAILED 或 TOKEN_EXPIRED 并跳转登录。

**Q：如何自定义日志输出？**

A：可继承 LoggingInterceptor 并替换默认日志拦截器（需修改 HttpManager.buildClient() 方法）。

**Q：是否支持 HTTPS 自签名证书？**

A：可通过自定义 OkHttpClient.Builder 的 sslSocketFactory 和 hostnameVerifier 扩展，库未内置该功能，需自行实现。