OkHttp 优雅封装 HttpUtils 之气海雪山初探

曾经在代码里放荡不羁，如今在博文中日夜兼行，只为今天与你分享成果。如果觉得本文有用，记得关注我，我将带给你更多。

介绍

HttpUtils 是近期开源的对 OkHttp 轻量封装的框架，它独创的异步预处理器，特色的标签，灵活的上传下载进度监听与过程控制功能，在轻松解决很多原本令人头疼问题的同时，设计上也力求纯粹与优雅。

链式调用，一点到底
BaseURL、URL占位符、JSON自动封装与解析
同步拦截器、异步预处理器、回调执行器
文件上传下载（过程控制、进度监听）
TCP连接池、Http2

中文官网：http://okhttps.ejlchina.com/

项目地址
Gitee：https://gitee.com/ejlchina-zhxu/httputils
GitHub：https://github.com/ejlchina/httputils

安装教程

Maven

<dependency>
     <groupId>com.ejlchina</groupId>
     <artifactId>httputils</artifactId>
     <version>2.2.0</version>
</dependency>

Gradle

compile 'com.ejlchina:httputils:2.2.0'

使用说明

1 简单示例

1.1 构建 HTTP

HTTP http = HTTP.builder().build();

以上代码构建了一个最简单的HTTP实例，它拥有以下三个方法：

async(String url) 开始一个异步请求
sync(String url) 开始一个同步请求
cancel(String tag) 根据标签批量取消请求

为了使用方便，在构建的时候，我们更愿意指定一个BaseUrl（请参见下文[5.1 设置 BaseUrl]）:

HTTP http = HTTP.builder()
        .baseUrl("http://api.demo.com")
        .build();

为了简化文档，下文中出现的http均是在构建时设置了BaseUrl的HTTP实例。

1.2 同步请求

使用方法sync(String url)开始一个同步请求：

List<User> users = http.sync("/users") // http://api.demo.com/users
        .get()                         // GET请求
        .getBody()                     // 获取响应报文体
        .toList(User.class);           // 得到目标数据

方法sync返回一个同步HttpTask，可链式使用。

1.3 异步请求

使用方法async(String url)开始一个异步请求：

http.async("/users/1")                //  http://api.demo.com/users/1
        .setOnResponse((HttpResult result) -> {
            // 得到目标数据
            User user = result.getBody().toBean(User.class);
        })
        .get();                       // GET请求

方法async返回一个异步HttpTask，可链式使用。

2 请求方法（GET|POST|PUT|DELETE）

同步与异步的HttpTask都拥有get、post、put与delete方法。不同的是：同步HttpTask的这些方法返回一个HttpResult，而异步HttpTask的这些方法返回一个HttpCall。

HttpResult res1 = http.sync("/users").get();     // 同步 GET
HttpResult res2 = http.sync("/users")post();     // 同步 POST
HttpResult res3 = http.sync("/users/1").put();   // 同步 PUT
HttpResult res4 = http.sync("/users/1").delete();// 同步 DELETE
HttpCall call1 = http.async("/users").get();     // 异步 GET
HttpCall call2 = http.async("/users").post();    // 异步 POST
HttpCall call3 = http.async("/users/1").put();   // 异步 PUT
HttpCall call4 = http.async("/users/1").delete();// 异步 DELETE

3 解析请求结果

3.1 回调函数

只有异步请求才可以设置回调函数：

http.async("/users/{id}")             // http://api.demo.com/users/1
        .addPathParam("id", 1)
        .setOnResponse((HttpResult result) -> {
            // 响应回调
        })
        .setOnException((Exception e) -> {
            // 异常回调
        })
        .setOnComplete((State state) -> {
            // 完成回调，无论成功失败都会执行
        })
        .get();

3.2 HttpResult

HttpResult是HTTP请求执行完后的结果，它是同步请求方法（ get、post、put、delete）的返回值，也是异步请求响应回调（OnResponse）的参数，它定义了如下方法：

getState() 得到请求执行状态枚举，它有以下取值：
- State.CANCELED 请求被取消
- State.RESPONSED 已收到响应
- State.TIMEOUT 请求超时
- State.NETWORK_ERROR 网络错误
- State.EXCEPTION 其它请求异常
getStatus() 得到HTTP状态码
isSuccessful() 是否响应成功，状态码在 [200..300) 之间
getHeaders() 得到HTTP响应头
getBody() 得到响应报文体Body实例，它定义了如下方法（对同一个Body实例，以下的toXXX()类方法只能使用一个且仅能调用一次）：
- toBytes() 返回字节数组
- toByteStream() 返回字节输入流
- toCharStream() 返回字符输入流
- toString() 返回字符串
- toJsonObject() 返回Json对象
- toJsonArray() 返回Json数组
- toBean(Class<T> type) 返回根据type自动json解析后的JavaBean
- toList(Class<T> type) 返回根据type自动json解析后的JavaBean列表
- toFile(String filePath) 下载到指定路径
- toFile(File file) 下载到指定文件
- toFolder(String dirPath) 下载到指定目录
- toFolder(File dir) 下载到指定目录
- getContentType() 返回报文体的媒体类型
- getContentLength() 返回报文体的字节长度
- close() 关闭报文体，未对报文体做任何消费时使用，比如只读取报文头
getError() 执行中发生的异常，自动捕获执行请求是发生的网络超时、网络错误和其它请求异常
close() 关闭报文，未对报文体做任何消费时使用，比如只读取长度

示例，请求结果自动转Bean和List：

// 自动转Bean
Order order = http.sync("/orders/1")
        .get().getBody().toBean(Order.class);
        
// 自动转List
List<Order> orders = http.sync("/orders")
        .get().getBody().toList(Order.class);

示例，下载文件到指定目录：

String path = "D:/reports/2020-03-01.xlsx";    // 文件保存目录

// 同步下载
http.sync("/reports/2020-03-01.xlsx")
        .get().getBody().toFile(path).start();

// 异步下载
http.async("/reports/2020-03-01.xlsx")
        .setOnResponse((HttpResult result) -> {
            result.getBody().toFile(path).start();
        })
        .get();

关于上传下载更详细的介绍请看后文：OkHttp 优雅封装 HttpUtils 之上传下载解密。

3.3 HttpCall

HttpCall对象是异步请求方法（get、post、put、delete）的返回值，与java的Future接口很像，它有如下方法：

cancel() 取消本次请求，返回取消结果
isCanceled() 返回请求是否被取消
isDone() 返回是否执行完成，包含取消和失败
getResult() 返回执行结果HttpResult对象，若请求未执行完，则挂起当前线程直到执行完成再返回

取消一个异步请求示例：

HttpCall call = http.async("/users/1").get();

System.out.println(call.isCanceled());     // false

boolean success = call.cancel();           // 取消请求

System.out.println(success);               // true
System.out.println(call.isCanceled());     // true

4 构建HTTP任务

HTTP对象的sync与async方法返回一个HttpTask对象，该对象提供了可链式调用的addXXX与setXXX系列方法用于构建任务本身。

addHeader(String name, String value) 添加请求头
addHeader(Map<String, String> headers) 添加请求头
addPathParam(String name, Object value) 添加路径参数：替换URL里的{name}占位符
addPathParam(Map<String, ?> params) 添加路径参数：替换URL里的{name}占位符
addUrlParam(String name, Object value) 添加URL参数：拼接在URL的?之后（查询参数）
addUrlParam(Map<String, ?> params) 添加URL参数：拼接在URL的?之后（查询参数）
addBodyParam(String name, Object value) 添加Body参数：以表单key=value&的形式放在报文体内（表单参数）
addBodyParam(Map<String, ?> params) 添加Body参数：以表单key=value&的形式放在报文体内（表单参数）
addJsonParam(String name, Object value) 添加Json参数：请求体为Json（支持多层结构）
addJsonParam(Map<String, ?> params) 添加Json参数：请求体为Json（支持多层结构）
setRequestJson(Object json) 设置请求体的Json字符串或待转换为 Json的 JavaBean
setRequestJson(Object bean, String dateFormat) 设置请求体的Json字符串或待转换为 Json的 JavaBean
addFileParam(String name, String filePath) 上传文件
addFileParam(String name, File file) 上传文件
addFileParam(String name, String type, InputStream inputStream) 上传文件
addFileParam(String name, String type, String fileName, InputStream input) 上传文件
addFileParam(String name, String type, byte[] content) 上传文件
addFileParam(String name, String type, String fileName, byte[] content) 上传文件
setTag(String tag) 为HTTP任务添加标签
setRange(long rangeStart) 设置Range头信息，用于断点续传
setRange(long rangeStart, long rangeEnd) 设置Range头信息，用于分块下载

5 使用标签

有时候我们想对HTTP任务加以分类，这时候可以使用标签功能：

http.async("/users")    //（1）
        .setTag("A").get();
        
http.async("/users")    //（2）
        .setTag("A.B").get();
        
http.async("/users")    //（3）
        .setTag("B").get();
        
http.async("/users")    //（4）
        .setTag("B.C").get();
        
http.async("/users")    //（5）
        .setTag("C").get();

当使用标签后，就可以按标签批量的对HTTP任务进行取消：

int count = http.cancel("B");              //（2）（3）（4）被取消（取消标签包含"B"的任务）
System.out.println(count);                 // 输出 3

同样的，只有异步HTTP任务才可以被取消。标签除了可以用来取消任务，在预处理器中它也可以发挥作用，请参见下文[6.4 并行预处理器]与[6.5 串行预处理器]。

6 配置 HTTP

6.1 设置 BaseUrl

HTTP http = HTTP.builder()
        .baseUrl("http://api.demo.com")    // 设置 BaseUrl
        .build();

配置了BaseUrl之后，具体的请求便可以省略BaseUrl部分，使得代码更加简洁，例如：

http.sync("/users").get()                  // http://api.demo.com/users

http.sync("/auth/signin")                  // http://api.demo.com/auth/signin
        .addBodyParam("username", "Jackson")
        .addBodyParam("password", "xxxxxx")
        .post()                            // POST请求

配置了BaseUrl之后，如有特殊请求，仍然可以使用全路径的方式，一点都不妨碍：

http.sync("https://www.baidu.com").get()

6.2 回调执行器

如何想改变执行回调函数的线程时，可以配置回调执行器。例如在Android里，让所有的回调函数都在UI线程执行，则可以在构建HTTP时配置如下：

HTTP http = HTTP.builder()
        .callbackExecutor((Runnable run) -> {
            runOnUiThread(run);            // 在UI线程执行
        })
        .build();

该配置影响的回调为：OnResponse、OnException和OnComplete。

6.3 配置 OkHttpClient

与其他封装 OkHttp 的框架不同，HttpUtils 并不会遮蔽 OkHttp 本身就很好用的功能，如下：

HTTP http = HTTP.builder()
    .config((Builder builder) -> {
        // 配置连接池 最小10个连接（不配置默认为 5）
        builder.connectionPool(new ConnectionPool(10, 5, TimeUnit.MINUTES));
        // 配置连接超时时间
        builder.connectTimeout(20, TimeUnit.SECONDS);
        // 配置拦截器
        builder.addInterceptor((Chain chain) -> {
            Request request = chain.request();
            // 必须同步返回，拦截器内无法执行异步操作
            return chain.proceed(request);
        });
        // 其它配置: SSL、缓存、代理、事件监听...
    })
    .build();

6.4 并行预处理器

预处理器（Preprocessor）可以让我们在请求发出之前根据业务对请求本身做一些处理，但与 OkHttp 的拦截器（Interceptor）不同：预处理器可以让我们异步处理这些问题。

例如，当我们想为请求任务自动添加Token头信息，而Token只能通过异步方法requestToken获取时，这时使用Interceptor就很难处理了，但可以使用预处理器轻松解决：

HTTP http = HTTP.builder()
        .addPreprocessor((PreChain chain) -> {
            HttpTask<?> task = chain.getTask();// 获得当前的HTTP任务
            if (!task.isTagged("Auth")) {      // 根据标签判断该任务是否需要Token
                return;
            }
            requestToken((String token) -> {   // 异步获取 Token
                task.addHeader("Token", token);// 为任务添加头信息
                chain.proceed();               // 继续当前的任务
            });
        })
        .build();

和Interceptor一样，Preprocessor也可以添加多个。

6.5 串行预处理器

普通预处理器都是可并行处理的，然而有时我们希望某个预处理器同时只处理一个任务。比如当Token过期时我们需要去刷新获取新Token，而刷新Token这个操作只能有一个任务去执行，因为如果n个任务同时执行的话，那么必有n-1个任务刚刷新得到的Token可能就立马失效了，而这是我们所不希望的。

为了解决这个问题，HttpUtils 提供了串行预处理器，它可以让HTTP任务排好队，一个一个地进入预处理器：

HTTP http = HTTP.builder()
        .addSerialPreprocessor((PreChain chain) -> {
            HttpTask<?> task = chain.getTask();
            if (!task.isTagged("Auth")) {
                return;
            }
            // 检查过期，若需要则刷新Token
            requestTokenAndRefreshIfExpired((String token) -> {
                task.addHeader("Token", token);  
                chain.proceed();               // 调用此方法前，不会有其它任务进入该处理器
            });
        })
        .build();

串行预处理器实现了让HTTP任务排队串行处理的功能，但值得一提的是：它并没有因此而阻塞任何线程！

7 使用 HttpUtils 类

类HttpUtils本是 1.x 版本里的最重要的核心类，由于在 2.x 版本里抽象出了HTTP接口，使得它的重要性已不如往昔。但合理的使用它，仍然可以带来不少便利，特别是在没有IOC容器的环境里，比如在Android开发和一些工具项目的开发中。

类HttpUtils共定义了四个静态方法：

async(String url) 开始一个异步请求（内容通过一个HTTP单例实现）
sync(String url) 开始一个同步请求（内容通过一个HTTP单例实现）
cancel(String tag) 按标签取消请求（内容通过一个HTTP单例实现）
of(HTTP http) 配置HttpUtils持有的HTTP实例（不调用此方法前默认使用一个没有没有经过任何配置的HTTP懒实例）

也就是说，能使用http实例的地方，都可以使用HttpUtils类，例如：

// 在配置HTTP实例之前，只能使用全路径方式
List<Role> roles = HttpUtils.sync("http://api.demo.com/roles")
        .get().getBody().toList(Role.class);

// 配置HTTP实例,全局生效
HttpUtils.of(HTTP.builder()
        .baseUrl("http://api.demo.com")
        .build());

// 内部使用新的HTTP实例
List<User> users = HttpUtils.sync("/users")
        .get().getBody().toList(User.class);

下篇文章：OkHttp 优雅封装 HttpUtils 之上传下载解密

曾经在代码里放荡不羁，如今在博文中日夜兼行，只为今天与你分享成果。如果觉得本文有用，记得关注我，我将带给你更多。

OkHttp 优雅封装 HttpUtils 之 气海雪山初探

曾经在代码里放荡不羁，如今在博文中日夜兼行，只为今天与你分享成果。如果觉得本文有用，记得关注我，我将带给你更多。

介绍

安装教程

Maven

Gradle

使用说明

1 简单示例

1.1 构建 HTTP

1.2 同步请求

1.3 异步请求

2 请求方法（GET|POST|PUT|DELETE）

3 解析请求结果

3.1 回调函数

3.2 HttpResult

3.3 HttpCall

4 构建HTTP任务

5 使用标签

6 配置 HTTP

6.1 设置 BaseUrl

6.2 回调执行器

6.3 配置 OkHttpClient

6.4 并行预处理器

6.5 串行预处理器

7 使用 HttpUtils 类

OkHttp 优雅封装 HttpUtils 之气海雪山初探