OkHttp: 使用入门

文章目录

    • 1. 领域对象
      • 1. Request
      • 2. Response
        • 2.1 请求重写
        • 2.2 重写返回
        • 2.3 跟踪请求
        • 2.4 自动重试
      • 3. Calls
    • 2. 创建连接
      • 1、URLs
      • 2、Addresses
      • 3、Routes
      • 4、Connections
    • 3. 使用案例
      • 1、同步GET请求
      • 2、异步GET请求
      • 3、发送和读取HTTP头
      • 4、POST 字符传
      • 5、POST 流
      • 6、POST 文件内容
      • 7、POST 表单
      • 8、上传
      • 9、使用Moshi在JSON和对象之间转换
      • 10、缓存Response
      • 11、取消Call调用
      • 12、超时
      • 13、设置
      • 14、Authentication
      • 15. 设置代理

1. 领域对象

HTTP客户端的作用就是接受你的请求,获取对应的返回。理论上简单的,然后实践过程会有一些陷阱。OkHttp是其中使用的比较广泛的一个。

okhttp主要包含的概念如下:

1. Request

包含请求的url,方法(GET/POST/PUT等待),HTTP头,以及请求体。

2. Response

返回的编码(200 成功, 404 页面不存在),HTTP头,以及返回体。

2.1 请求重写

我们会在高层次的描述请求哪个地址,包含什么头等等。为了正确性和高效,OkHttp会帮我们重写请求。

  • 添加缺失的HTTP头,包括Content-Lenght、Transfer-Encoding、User-Agent、Host、Connection、Content-Type
  • 动添加一个Accept-Encoding,支持自动解压gzip等压缩过的返回
  • 如果你有Cookie,OkHttp会自动添加一个Cookie的HTTP头
  • 可缓存的请求(Cache-Control、Expired、Etag等),自动添加If-Modified-Since、If-None-Match头
2.2 重写返回
  • 如果返回是压缩过的,OkHttp会自动解压,并删除Content-Encoding和Content-Length头,因为这两个值解压后已经不准确
  • 如果是条件获取(If-Modified-Since等),OkHttp会自动切换从本地缓存或者服务端获取内容
2.3 跟踪请求
  • 自动完成302跳转,获取最终结果页面内容
  • 如果配置了Authenticator,自动HTTP权限验证
2.4 自动重试
  • 连接池内连接过期或者服务器不可触达,尝试重试(重试的机制还需要深挖)

3. Calls

由于请求重写、跟踪请求、自动重试等等,你描述的请求实际上会产生多个Request/Response, OkHttp将这个操作抽象为一个Call。
Call实际上有两种执行方式

  • 同步执行,当前线程阻塞,指定请求完成
  • 异步执行,当前请求如队列,完成请求会回调注册的接口

Call可以被其他线程取消。如果Call被取消后还有线程还有代码去写Request或者读Response会抛出IOException

在同步模式下,你使用自己线程,并负责管理simultaneous,太多的simultaneous connections浪费资源,过少则影响延时
在异步模式下,Dispatcher负责管理simultaneous,你可以设置每个webserver(默认5个)以及总(默认64个)的连接数。

2. 创建连接

尽管你只提供一个URL链接,OkHttp会使用三种类型去链接WebServer,它们分别是: URL、Address、Route

1、URLs

URL是HTTP和互联网的基础,处理提供Web上资源的统一命名服务,同样指定了怎么访问Web资源。

URL是抽象的

  • 指定了请求内容是纯文本(http)还是加密的(https)
  • 没有指定加解密算法,怎么去验证证书(HostnameVerifier),哪些证书是可靠的(SSLSocketFactory)
  • 没有指定怎么使用代理服务器,以及代理服务器怎么鉴权

2、Addresses

Adress指定了一个WebServer,包括所有连接服务器所需要的信息(包括端口、HTTPS设置、倾向的网络协议,如HTTP/2、SPDY等)。

相同服务器地址的URL可能会共享底层的TCP连接,共享TCP连接会有明显的性能优势:

  • 更低延迟
  • 更高吞吐量(TCP慢启动)
  • 省电

OkHttp通过ConnectionPool自动重用连接。

3、Routes

Routes提供了自动链接WebServer里的必要信息,包括

  • IP地址,通过DNS获取
  • 确定的代理服务器,如果配置了ProxySelector的话
  • TLS(传输层安全协议)版本号

一个Adress可能会有多个Routes,比如一个跨数据中心部署的WebServer,DNS解析后肯能会有多个地址。

4、Connections

当你请求URL时,OkHttp为你做了以下操作:

  1. 使用URL和配置好的OkHttpClient创建一个Addresss,里边包含了我们怎么去连接Web服务器的信息。
  2. 尝试从ConnectionPool里获取一个对应Address的连接。
  3. 找不到连接的话,它会尝试选择一个Route,这意味着DNS解析、选择TLS版本以及代理服务器(需要的话)。
  4. 如果这是一个新的Route,它会创建一个Socket连接、TLS隧道(经过HTTPS的代理服务)、TLS连接。如果需要的话,完成TLS握手。
  5. 发生请求并读取结果。

如果连接有问题的话,OkHttp会重新选择另外一个Route并重试。这有助于OkHttp从服务端部分地址不可用时恢复。同样有助于当连接过期,或者TLS版本不支持的时候。

当响应读取完成后,连接会被退回到连接池中等待重用,一段时间没有使用后会被从连接池里清除。

3. 使用案例

我们提供了一下用OkHttp解决常见问题的样例。

1、同步GET请求

当响应结果比较小的时候(<1M),response.body().string()是方便且高效的,否则应该使用流读取。

  private final OkHttpClient client = new OkHttpClient();

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

    try (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());
    }
  }

2、异步GET请求

在OkHttp的工作线程里请求,当响应可读的时候调用回调函数。回调函数实在响应HTTP头读取后调用的,读取响应体还是需要同步完成。

private final OkHttpClient client = new OkHttpClient();

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

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

      @Override public void onResponse(Call call, Response response) throws IOException {
        try (ResponseBody responseBody = response.body()) {
          if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);

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

          System.out.println(responseBody.string());
        }
      }
    });
  }

3、发送和读取HTTP头

一般来说,HTTP头一个KEY会对应一个值,但是有的字段允许有多个值。OkHttp为这两种情况提供了支持:

  • Request.Builder.header(name,value)方法,支持单值的HTTP头,把已存在的同名HTTP头删除。
  • Request.Builder.addHeader(name,value)只是单纯的添加,不会有删除操作。
  • Response.header(name),获取多值的最后一个,没有的话返回null。
  • Response.headers(name),返回多值
 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();

    try (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、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 {
    String postBody = "* _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();

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

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

5、POST 流

使用流做为请求体,请求体内容会在发送请求的时候输出,这个例子里使用的是Okio的BufferedSink,你也可以通过BufferedSkin.outputStream获取输出流。

  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, 2*i));
        }
      }
    };

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

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

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

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();

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

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

7、POST 表单

  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();

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

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

8、上传

  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();

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

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

9、使用Moshi在JSON和对象之间转换

Moshi是一个简便的JSON转换类库。
ResponseBody.charStream()使用Content-Type里的编码解释响应内容,找不到编码默认UTF-8。

  private final OkHttpClient client = new OkHttpClient();
  private final Moshi moshi = new Moshi.Builder().build();
  private final JsonAdapter gistJsonAdapter = moshi.adapter(Gist.class);

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

      Gist gist = gistJsonAdapter.fromJson(response.body().source());

      for (Map.Entry entry : gist.files.entrySet()) {
        System.out.println(entry.getKey());
        System.out.println(entry.getValue().content);
      }
    }
  }

  static class Gist {
    Map files;
  }

  static class GistFile {
    String content;
  }

10、缓存Response

要缓存Response,你需要一个可以读写的目录,以及设置缓存的大小。 大多数应用只需要创建一次OkHttpClient对象,两个实例使用同一个缓存目录会导致冲突,甚至使程序崩溃。
Response缓存通过服务端HTTP头控制。
添加一下HTTP头可以控制缓存的行为:

  • CacheControl.FORCE_NETWORK,强制从服务端加载。
  • CacheControl.FORCE_CACHE,强制从缓存加载,当缓存中信息不可获取(不存在或者过期),返回504
 private final OkHttpClient client;

  public CacheResponse(File cacheDirectory) throws Exception {
    int cacheSize = 10 * 1024 * 1024; // 10 MiB
    Cache cache = new Cache(cacheDirectory, cacheSize);
    client = new OkHttpClient.Builder().cache(cache).build();
  }

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

    String response1Body;
    try (Response response1 = client.newCall(request).execute()) {
      if (!response1.isSuccessful()) throw new IOException("Unexpected code " + response1);

      response1Body = response1.body().string();
      System.out.println("Response 1 response:          " + response1);
      System.out.println("Response 1 cache response:    " + response1.cacheResponse());
      System.out.println("Response 1 network response:  " + response1.networkResponse());
    }

    String response2Body;
    try (Response response2 = client.newCall(request).execute()) {
      if (!response2.isSuccessful()) throw new IOException("Unexpected code " + response2);

      response2Body = response2.body().string();
      System.out.println("Response 2 response:          " + response2);
      System.out.println("Response 2 cache response:    " + response2.cacheResponse());
      System.out.println("Response 2 network response:  " + response2.networkResponse());
    }

    System.out.println("Response 2 equals Response 1? " + response1Body.equals(response2Body));
  }

11、取消Call调用

通Call.cancel()取消调用,如果另外一个线程正在写请求或者读取返回时,抛出IOException

  private final ScheduledExecutorService executor = Executors.newScheduledThreadPool(1);
  private final OkHttpClient client = new OkHttpClient();

  public void run() throws Exception {
    Request request = new Request.Builder()
        .url("http://httpbin.org/delay/2") // This URL is served with a 2 second delay.
        .build();

    final long startNanos = System.nanoTime();
    final Call call = client.newCall(request);

    // Schedule a job to cancel the call in 1 second.
    executor.schedule(new Runnable() {
      @Override public void run() {
        System.out.printf("%.2f Canceling call.%n", (System.nanoTime() - startNanos) / 1e9f);
        call.cancel();
        System.out.printf("%.2f Canceled call.%n", (System.nanoTime() - startNanos) / 1e9f);
      }
    }, 1, TimeUnit.SECONDS);

    System.out.printf("%.2f Executing call.%n", (System.nanoTime() - startNanos) / 1e9f);
    try (Response response = call.execute()) {
      System.out.printf("%.2f Call was expected to fail, but completed: %s%n",
          (System.nanoTime() - startNanos) / 1e9f, response);
    } catch (IOException e) {
      System.out.printf("%.2f Call failed as expected: %s%n",
          (System.nanoTime() - startNanos) / 1e9f, e);
    }
  }

12、超时

当端不可触达的时候,客户端连接问题、服务端不可用、或者两者之间的问题,可以通过设置超时。OkHttp支持三种超时: 连接超时,写请求超时,读返回超时。

  private final OkHttpClient client;

  public ConfigureTimeouts() throws Exception {
    client = new OkHttpClient.Builder()
        .connectTimeout(10, TimeUnit.SECONDS)
        .writeTimeout(10, TimeUnit.SECONDS)
        .readTimeout(30, TimeUnit.SECONDS)
        .build();
  }

  public void run() throws Exception {
    Request request = new Request.Builder()
        .url("http://httpbin.org/delay/2") // This URL is served with a 2 second delay.
        .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println("Response completed: " + response);
    }
  }

13、设置

所有的设置都是通过OkHttpClient完成的,包括代理、超时、缓存等等。当你需要为一个请求修改设置的时候,调用OkHttpClient.builder()方法,返回的builder和原始的OkHttpClient共享连接池、Dispatcher和配置信息,只需要修改特有的配置即可。

 private final OkHttpClient client = new OkHttpClient();

  public void run() throws Exception {
    Request request = new Request.Builder()
        .url("http://httpbin.org/delay/1") // This URL is served with a 1 second delay.
        .build();

    // Copy to customize OkHttp for this request.
    OkHttpClient client1 = client.newBuilder()
        .readTimeout(500, TimeUnit.MILLISECONDS)
        .build();
    try (Response response = client1.newCall(request).execute()) {
      System.out.println("Response 1 succeeded: " + response);
    } catch (IOException e) {
      System.out.println("Response 1 failed: " + e);
    }

    // Copy to customize OkHttp for this request.
    OkHttpClient client2 = client.newBuilder()
        .readTimeout(3000, TimeUnit.MILLISECONDS)
        .build();
    try (Response response = client2.newCall(request).execute()) {
      System.out.println("Response 2 succeeded: " + response);
    } catch (IOException e) {
      System.out.println("Response 2 failed: " + e);
    }
  }

14、Authentication

OkHttp会自动重试未授权的请求,当服务端返回401的时候,OkHttp会尝试寻找Authenticator注册信息,如果有的话通过对应信息进行验证。代码关键点:

  • response.challenges()
  • Credentials.basic
  • response.request().newBuilder()
  private final OkHttpClient client;

  public Authenticate() {
    client = new OkHttpClient.Builder()
        .authenticator(new Authenticator() {
          @Override public Request authenticate(Route route, Response response) throws IOException {
            if (response.request().header("Authorization") != null) {
              return null; // Give up, we've already attempted to authenticate.
            }

            System.out.println("Authenticating for response: " + response);
            System.out.println("Challenges: " + response.challenges());
            String credential = Credentials.basic("jesse", "password1");
            return response.request().newBuilder()
                .header("Authorization", credential)
                .build();
          }
        })
        .build();
  }

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

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

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

Authenticator返回null的时候,OkHttp会停止重试。为了避免Authentication不起效时还反复重试, 可以再重试过一次之后,返回null退出执行

  if (credential.equals(response.request().header("Authorization"))) {
    return null; // If we already failed with these credentials, don't retry.
  }

你以可以通过Response.priorResponse()来计数调用了多少次,次数满是退出重试。

  if (responseCount(response) >= 3) {
    return null; // If we've failed 3 times, give up.
  }

  private int responseCount(Response response) {
    int result = 1;
    while ((response = response.priorResponse()) != null) {
      result++;
    }
    return result;
  }

15. 设置代理

Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1",12345));
OkHttpClient client = new OkHttpClient.Builder().proxy(proxy).build();

Request request = new Request.Builder().url(url).header("Authorization", signature).post(RequestBody.create(MEDIA_JSON, postBody)).build();
Response response = client.newCall(request).execute();

 
 
 

你可能感兴趣的:(HttpClient,okhttp,java)