Android中OkHttp的使用

Android中OkHttp的使用

官方网站 | Javadoc

1 简介

OkHttp是Square出的Http通讯库，支持HTTP和HTTP/2，用于Android应用和Java应用。
OkHttp是非常优秀的Http通讯库，将Http连接中各种繁杂的问题，对并发的支持，对常见异常的处理等封装在底层，提供简单易用的API供应用中调用。与之相比，HttpUrlConnection的使用过于复杂，Appache的HttpClient在Android平台上的运行又有各种问题，在Android 6.0之后，已经将HttpClient库从SDK中删除，全面转向使用OkHttp。
目前有很多知名的Android三方框架都使用OkHttp作为网络连接的默认基栈，例如Volley，Glide，Retrofit等，从中也能看出学习OkHttp的必要性。

2 快速上手

2.1项目中添加对OkHttp的依赖

在需要使用OkHttp的模块的build.gradle文件中，添加如下依赖：(版本号可能变更)
compile 'com.squareup.okhttp3:okhttp:3.2.0'

2.2 初始化

OkHttp框架的核心类是OkHttpClient，此类可直接实例化。由于OkHttpClient内部处理了并发，多线程和Socket重用等问题，为了节省资源，整个应用中使用一个OkHttpClient对象即可，可以对它做Singleton封装。

OkHttpClient okHttpClient = new OkHttpClient();

2.3 Http请求的构建

代表Http请求的类是Request，该类使用构造器模式，最简单的构造GET请求如下：

Request request = new Request.Builder()
      .url(url)
      .build();

要构造Post请求，在构建Request时增加请求体即可：

RequestBody formBody = new FormEncodingBuilder()
    .add("name", "Cuber")
    .add("age", "26")
    .build();

Request request = new Request.Builder()
      .url(url)
      .post(RequestBody)
      .build();

2.4 Http请求的发送

请求的发送有两种形式，一种是直接同步执行，阻塞调用线程，直接返回结果；另一种是通过队列异步执行，不阻塞调用线程，通过回调方法返回结果。如下所示：

同步执行：

// 如果返回null，代表超时或没有网络连接
Response response = client.newCall(request).execute();

异步回调：

Response response = client.newCall(request).enqueue(new Callback() {

    @Override
    public void onFailure(Request request, IOException e) {
        //超时或没有网络连接
        //注意：这里是后台线程！
    }

    @Override
        public void onResponse(Response response) throws IOException {
        //成功
        //注意：这里是后台线程！
    }
});

以上这些就是快速上手OkHttp需要知道的全部内容，可以从中看出，它的API非常简单易用。

3 Call模型

Http客户端的任务是处理请求和响应，这说起来简单，但实际过程很复杂。

  • 请求：Http请求包含一个URL，请求方法(例如GET或者POST)，请求头。还可能包含请求体，可以是数据流也可以是指定的内容类别。
  • 响应：用一个响应码来回应请求(例如200代表成功，404代表页面未找到)，响应头和响应体。

3.1 请求的重写

为了保证正确性和传输效率，OkHttp会在发送你的请求之前重写它，例如：
OkHttp可能会添加原始请求中缺失的头信息，包括Content-Length, Transfer-Encoding, User-Agent, Host, Connection, 和 Content-Type。
为了实现透明的响应压缩(transparent response compression)，OkHttp会增加Accept-Encoding头信息。
如果你收到了cookie，OkHttp会增加Cookie头信息。
某些请求可能会对响应做缓存。如果被缓存的响应不是最新的，OkHttp能做一个有条件的GET请求来下载更新后的响应。此功能需要添加If-Modified-Since和If-None-Match等头信息。

3.2 响应的重写

如果使用了透明压缩，OkHttp会去掉对应响应的Content-Encoding和Content-Length头信息，因为它们不能应用于解压后的响应体。
如果有条件的GET成功了，网络侧的响应和缓存的响应会被自动合并。

3.3 重定向

如果你请求的URL被移动了，服务器会返回类似于302这样的响应码，来指明新的URL。OkHttp能跟随新的URL，获取到最终的响应。

3.4 请求的重试

有时会发生连接失败：可能网络连接状况不好，或者服务器不可达。OkHttp会自动使用不同的路由来重试请求。

3.5 Call模型

由于以上的重写，重定向和重试等操作，你的一个简单请求可能会产生多个请求和响应。OkHttp使用Call这一概念对此来建模：不论为了满足你的请求任务，中间做了多少次请求和响应，都算作一个Call。
Call有两种方式来执行：

  • 同步方式：你的线程会被阻塞，知道响应可读。
  • 异步方式：你在任意线程将请求排队，当响应可读时，会在另一个线程拿到回调。

Call可以在任意线程取消，如果请求没有完成，调用取消方法会导致请求失败，读写请求体和响应体的代码会产生IOException。

3.6 Call的分派

对于同步调用，你自己需要负责对线程和并发请求的管理。太多的同时存在的连接会浪费资源，太少则会影响延迟性能。
对于异步调用，Dispatcher实现了对最大并发请求数的管理。你可以设置最大的单服务器并发数(默认是5)，和最大的总并发数(默认是64)。

4 基本使用方法

以下是一些简单的代码样例，用来阐明如何用OkHttp解决常见问题。

4.1 同步Get请求

private final OkHttpClient client = new OkHttpClient();

public void run() throws Exception {
    Request request = new Request.Builder()
        .url("http://publicobject.com/helloworld.txt")
        .build();

    // 下载文件
    Response response = client.newCall(request).execute();
    if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

    // 打印响应的头信息
    Headers responseHeaders = response.headers();
    for (int i = 0; i < responseHeaders.size(); i++) {
      System.out.println(responseHeaders.name(i) + ": " + responseHeaders.value(i));
    }

    // 将文件内容作为字符串输出
    System.out.println(response.body().string());
}

响应体的string()方法对于小文件来说非常方便和高效，但如果响应体较大(例如大于1M)，要避免使用这一方法，因为它会将文件内容全部加载在内存上。在这种情况下，使用流来处理响应体。

4.2 异步Get请求

下载一个文件，当响应可读时获得回调。具体收到回调的时间是当响应头准备好时，读取响应体仍然可能会阻塞。当前OkHttp没有提供异步API来接受响应体的各部分。

private final OkHttpClient client = new OkHttpClient();

public void run() throws Exception {
    Request request = new Request.Builder()
            .url("http://publicobject.com/helloworld.txt")
            .build();

    client.newCall(request).enqueue(new Callback() {
        @Override
        public void onFailure(Request request, IOException throwable) {
            throwable.printStackTrace();
        }

        @Override
        public void onResponse(Response response) throws IOException {
            if (!response.isSuccessful())
                throw new IOException("Unexpected code " + response);

            Headers responseHeaders = response.headers();
            for (int i = 0; i < responseHeaders.size(); i++) {
                System.out.println(responseHeaders.name(i) + ": " + responseHeaders.value(i));
            }

            System.out.println(response.body().string());
        }
    });
}

4.3 获取头信息

private final OkHttpClient client = new OkHttpClient();

public void run() throws Exception {
    Request request = new Request.Builder()
            .url("https://api.github.com/repos/square/okhttp/issues")
            .header("User-Agent", "OkHttp Headers.java")
            .addHeader("Accept", "application/json; q=0.5")
            .addHeader("Accept", "application/vnd.github.v3+json")
            .build();

    Response response = client.newCall(request).execute();
    if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

    System.out.println("Server: " + response.header("Server"));
    System.out.println("Date: " + response.header("Date"));
    System.out.println("Vary: " + response.headers("Vary"));
}

4.4 Post字符串

以下的例子显示了如何Post一个字符串给服务器，同样，不要使用此API传送大文件(> 1M)。

private final OkHttpClient client = new OkHttpClient();

public void run() throws Exception {
    String postBody = ""
            + "Releases\n"
            + "--------\n"
            + "\n"
            + " * _1.0_ May 6, 2013\n"
            + " * _1.1_ June 15, 2013\n"
            + " * _1.2_ August 11, 2013\n";

    Request request = new Request.Builder()
            .url("https://api.github.com/markdown/raw")
            .post(RequestBody.create(MEDIA_TYPE_MARKDOWN, postBody))
            .build();

    Response response = client.newCall(request).execute();
    if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

    System.out.println(response.body().string());
}

4.5 Post流

下面的例子使用了Okio的buffered sink。如果想使用OutputStream，可以通过
BufferedSink.outputStream()方法。

public static final MediaType MEDIA_TYPE_MARKDOWN
        = MediaType.parse("text/x-markdown; charset=utf-8");

public static final MediaType MEDIA_TYPE_MARKDOWN
        = MediaType.parse("text/x-markdown; charset=utf-8");

private final OkHttpClient client = new OkHttpClient();

public void run() throws Exception {
    RequestBody requestBody = new RequestBody() {
        @Override public MediaType contentType() {
            return MEDIA_TYPE_MARKDOWN;
        }

        @Override public void writeTo(BufferedSink sink) throws IOException {
            sink.writeUtf8("Numbers\n");
            sink.writeUtf8("-------\n");
            for (int i = 2; i <= 997; i++) {
                sink.writeUtf8(String.format(" * %s = %s\n", i, factor(i)));
            }
        }

        private String factor(int n) {
            for (int i = 2; i < n; i++) {
                int x = n / i;
                if (x * i == n) return factor(x) + " × " + i;
            }
            return Integer.toString(n);
        }
    };

    Request request = new Request.Builder()
            .url("https://api.github.com/markdown/raw")
            .post(requestBody)
            .build();

    Response response = client.newCall(request).execute();
    if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

    System.out.println(response.body().string());
}

4.6 Post文件

public static final MediaType MEDIA_TYPE_MARKDOWN
        = MediaType.parse("text/x-markdown; charset=utf-8");

private final OkHttpClient client = new OkHttpClient();

public void run() throws Exception {
    File file = new File("README.md");

    Request request = new Request.Builder()
            .url("https://api.github.com/markdown/raw")
            .post(RequestBody.create(MEDIA_TYPE_MARKDOWN, file))
            .build();

    Response response = client.newCall(request).execute();
    if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

    System.out.println(response.body().string());
}

4.7 Post form参数

private final OkHttpClient client = new OkHttpClient();

public void run() throws Exception {
    RequestBody formBody = new FormBody.Builder()
            .add("search", "Jurassic Park")
            .build();
    Request request = new Request.Builder()
            .url("https://en.wikipedia.org/w/index.php")
            .post(formBody)
            .build();

    Response response = client.newCall(request).execute();
    if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

    System.out.println(response.body().string());
}

4.8 Post多部分请求

MultipartBody.Builder可以构建复杂的请求体，多部分请求体的每一个部分都是一个单一的请求体，可以定义它自身的请求头。

private static final String IMGUR_CLIENT_ID = "...";
private static final MediaType MEDIA_TYPE_PNG = MediaType.parse("image/png");

private final OkHttpClient client = new OkHttpClient();

public void run() throws Exception {
    // Use the imgur image upload API as documented at https://api.imgur.com/endpoints/image
    RequestBody requestBody = new MultipartBody.Builder()
            .setType(MultipartBody.FORM)
            .addFormDataPart("title", "Square Logo")
            .addFormDataPart("image", "logo-square.png",
                    RequestBody.create(MEDIA_TYPE_PNG, new File("website/static/logo-square.png")))
            .build();

    Request request = new Request.Builder()
            .header("Authorization", "Client-ID " + IMGUR_CLIENT_ID)
            .url("https://api.imgur.com/3/image")
            .post(requestBody)
            .build();

    Response response = client.newCall(request).execute();
    if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

    System.out.println(response.body().string());
}

4.9 使用Gson来解析JSON响应

以下代码使用Gson库来解析服务器响应的JSON信息，注意ResponseBody.charStream()方法使用响应头中的Content-Type字段来选择使用何种字符集，如果没有指明，默认将使用UTF-8。

Gson的依赖
compile 'com.google.code.gson:gson:2.6.2'

private final OkHttpClient client = new OkHttpClient();
private final Gson gson = new Gson();

public void run() throws Exception {
    Request request = new Request.Builder()
            .url("https://api.github.com/gists/c2a7c39532239ff261be")
            .build();
    Response response = client.newCall(request).execute();
    if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

    Gist gist = gson.fromJson(response.body().charStream(), Gist.class);
    for (Map.Entry<String, GistFile> entry : gist.files.entrySet()) {
        System.out.println(entry.getKey());
        System.out.println(entry.getValue().content);
    }
}

static class Gist {
    Map<String, GistFile> files;
}

static class GistFile {
    String content;
}

4.10 Call的取消

使用Call.cancel()来停止一个执行中的请求。如果线程正在写请求或读响应，则会收到IOException。使用此方法，在一个Call已经不需要时取消它，可以节省网络流量。

5 更多内容

以上是对OkHttp的基本了解，更多内容包括：

  • 处理鉴权和Cookie。
  • 使用HTTPS。
  • 使用拦截器。
  • 等等...

6 FAQ

OkHttp如何设置超时？

设置超时的方法很简单：

OkHttpClient client = new OkHttpClient.Builder()
    .connectTimeout(10, TimeUnit.SECONDS)  // 连接超时
    .writeTimeout(10, TimeUnit.SECONDS)    // Socket写超时
    .readTimeout(30, TimeUnit.SECONDS)     // Socket读超时
    .build();

注意readTimeout和writeTimeout被用于OkHttp内部的Connection类，用在setSoTimeout方法上来设置Socket。
另外，在2.5.0版本之后，读、写、连接超时的默认值是10s。

OkHttp是否支持自签名SSL证书？

支持，需要自定义javax.net.ssl.SSLSocketFactory实例，传给OkHttpClient.setSslSocketFactory(SSLSocketFactory sslSocketFactory)方法。可以使用来自你自己Keystore的证书。

OkHttp中，Callback的回调方法onFailure和onResponse是在主线程执行码？

不是，OkHttp是一个Java库，不是Android库，它对Android主线程一无所知，所以这两个回调方法自然是在后台线程执行。实际开发中，常常对OkHttp做二次封装，来直接将结果传递给主线程。

在OkHttp中可以禁止自动重定向吗？

在2.3.0版本中提供了设置的方法：
final OkHttpClient client = new OkHttpClient();
client.setFollowRedirects(false);
但在3.x版本中这一方法不存在了，所以暂时没有简单的方法来直接禁止自动重定向。

OKHttp既有同步api也有异步api，考虑下面两种方法来实现异步请求，有什么区别？哪一种更好？

  1. 使用AsyncTask和OKhttp同步api；
  2. 直接使用OKHttp异步api；

这两种方法区别很大！
为了HTTP请求而使用AsyncTask，在Android中是很糟糕的做法。它会造成很多缺陷，最好避免这样做。例如，你无法在执行期间撤销一 个请求。另外，AsyncTask的使用模式常常会泄露Activity的引用，这是Android开发中容易引起内存泄漏的罪魁祸首之一。

OKHttp的异步方法从多个方面来讲都优越得多：

  1. 异步api支持本地撤销请求。如果请求是在连接过程中，Callback的引用会被释放，不会再被调用；如果请求还没有开始，则不会被执行。如果你使用的是HTTP/2或者SPDY协议，我们就能实质上的在请求过程中撤销它，节省流量和电量。
  2. 异步api支持给多个请求添加标记，并在一个方法中撤销全部被标记的请求。例如，在一个Activity中做出的所有请求，都可以用该Activity的实例做标记。然后，在onPause或onStop方法中，你可以撤销所有用该Activity实例标记的请求。
    3.如果你在使用HTTP/2或者SPDY，多个请求或者响应是复用单一连接传输到服务器的，在这种情况下，使用异步调用机制比阻塞的方式要高效得多。所以，如果可以，尽量使用Call.enqueue！

更多问题见stackoverflow(翻墙)。

最后编辑于 ：
©著作权归作者所有,转载或内容合作请联系作者
  • 人面猴
    序言：七十年代末，一起剥皮案震惊了整个滨河市，随后出现的几起案子，更是在滨河造成了极大的恐慌，老刑警刘岩，带你破解...
    沈念sama阅读 202,056评论 5赞 474
  • 死咒
    序言：滨河连续发生了三起死亡事件，死亡现场离奇诡异，居然都是意外死亡，警方通过查阅死者的电脑和手机，发现死者居然都...
    沈念sama阅读 84,842评论 2赞 378
  • 救了他两次的神仙让他今天三更去死
    文/潘晓璐 我一进店门，熙熙楼的掌柜王于贵愁眉苦脸地迎上来，“玉大人，你说我怎么就摊上这事。” “怎么了？”我有些...
    开封第一讲书人阅读 148,938评论 0赞 335
  • 道士缉凶录：失踪的卖姜人
    文/不坏的土叔 我叫张陵，是天一观的道长。 经常有香客问我，道长，这世上最难降的妖魔是什么？ 我笑而不...
    开封第一讲书人阅读 54,296评论 1赞 272
  • 港岛之恋（遗憾婚礼）
    正文 为了忘掉前任，我火速办了婚礼，结果婚礼上，老公的妹妹穿的比我还像新娘。我一直安慰自己，他们只是感情好，可当我...
    茶点故事阅读 63,292评论 5赞 363
  • 恶毒庶女顶嫁案：这布局不是一般人想出来的
    文/花漫 我一把揭开白布。 她就那样静静地躺着，像睡着了一般。 火红的嫁衣衬着肌肤如雪。 梳的纹丝不乱的头发上，一...
    开封第一讲书人阅读 48,413评论 1赞 281
  • 城市分裂传说
    那天，我揣着相机与录音，去河边找鬼。 笑死，一个胖子当着我的面吹牛，可吹牛的内容都是我干的。 我是一名探鬼主播，决...
    沈念sama阅读 37,824评论 3赞 393
  • 双鸳鸯连环套：你想象不到人心有多黑
    文/苍兰香墨 我猛地睁开眼，长吁一口气：“原来是场噩梦啊……” “哼！你这毒妇竟也来了？” 一声冷哼从身侧响起，我...
    开封第一讲书人阅读 36,493评论 0赞 256
  • 万荣杀人案实录
    序言：老挝万荣一对情侣失踪，失踪者是张志新（化名）和其女友刘颖，没想到半个月后，有当地人在树林里发现了一具尸体，经...
    沈念sama阅读 40,686评论 1赞 295
  • 护林员之死
    正文 独居荒郊野岭守林人离奇死亡，尸身上长有42处带血的脓包…… 初始之章·张勋 以下内容为张勋视角 年9月15日...
    茶点故事阅读 35,502评论 2赞 318
  • 白月光启示录
    正文 我和宋清朗相恋三年，在试婚纱的时候发现自己被绿了。 大学时的朋友给我发了我未婚夫和他白月光在一起吃饭的照片。...
    茶点故事阅读 37,553评论 1赞 329
  • 活死人
    序言：一个原本活蹦乱跳的男人离奇死亡，死状恐怖，灵堂内的尸体忽然破棺而出，到底是诈尸还是另有隐情，我是刑警宁泽，带...
    沈念sama阅读 33,281评论 4赞 318
  • 日本核电站爆炸内幕
    正文 年R本政府宣布，位于F岛的核电站，受9级特大地震影响，放射性物质发生泄漏。R本人自食恶果不足惜，却给世界环境...
    茶点故事阅读 38,820评论 3赞 305
  • 男人毒药：我在死后第九天来索命
    文/蒙蒙 一、第九天 我趴在偏房一处隐蔽的房顶上张望。 院中可真热闹，春花似锦、人声如沸。这庄子的主人今日做“春日...
    开封第一讲书人阅读 29,873评论 0赞 19
  • 一桩弑父案，背后竟有这般阴谋
    文/苍兰香墨 我抬头看了看天上的太阳。三九已至，却和暖如春，着一层夹袄步出监牢的瞬间，已是汗流浃背。 一阵脚步声响...
    开封第一讲书人阅读 31,109评论 1赞 258
  • 情欲美人皮
    我被黑心中介骗来泰国打工， 没想到刚下飞机就差点儿被人妖公主榨干…… 1. 我叫王不留，地道东北人。 一个月前我还...
    沈念sama阅读 42,699评论 2赞 348
  • 代替公主和亲
    正文 我出身青楼，却偏偏与公主长得像，于是被迫代替她去往敌国和亲。 传闻我的和亲对象是个残疾皇子，可洞房花烛夜当晚...
    茶点故事阅读 42,257评论 2赞 341