OkHttp对Interceptor的正式介绍

Interceptors are a powerful mechanism that can monitor, rewrite, and retry calls. Here's a simple interceptor that logs the outgoing request and the incoming response.

拦截器是一种强大的机制，可以监视、重写和重试调用。下面是一个简单的拦截器，它记录发出的请求和传入的响应。

class LoggingInterceptor implements Interceptor {
  @Override public Response intercept(Interceptor.Chain chain) throws IOException {
    Request request = chain.request();

    long t1 = System.nanoTime();
    logger.info(String.format("Sending request %s on %s%n%s",
        request.url(), chain.connection(), request.headers()));

    Response response = chain.proceed(request);

    long t2 = System.nanoTime();
    logger.info(String.format("Received response for %s in %.1fms%n%s",
        response.request().url(), (t2 - t1) / 1e6d, response.headers()));

    return response;
  }
}

A call to chain.proceed(request) is a critical part of each interceptor’s implementation. This simple-looking method is where all the HTTP work happens, producing a response to satisfy the request.

对chain.proceed(request)的调用是每个拦截器实现的关键部分。这个看起来简单的方法是所有HTTP工作发生的地方，生成响应以满足请求。

Interceptors can be chained. Suppose you have both a compressing interceptor and a checksumming interceptor: you'll need to decide whether data is compressed and then checksummed, or checksummed and then compressed. OkHttp uses lists to track interceptors, and interceptors are called in order.

拦截器可以链接起来。假设您有一个压缩拦截器和一个checksumming拦截器:您需要决定数据是压缩后再进行checksum，还是checksum再进行压缩。OkHttp使用列表跟踪拦截器，并按顺序调用拦截器。

Application Interceptors

应用程序拦截器

Interceptors are registered as either application or network interceptors. We'll use the LoggingInterceptor defined above to show the difference.

拦截器注册为应用程序或网络拦截器。我们将使用上面定义的LoggingInterceptor来显示区别。

Register an application interceptor by calling addInterceptor() on OkHttpClient.Builder:

通过在OkHttpClient.Builder上调用addInterceptor()注册应用程序拦截器:

OkHttpClient client = new OkHttpClient.Builder()
    .addInterceptor(new LoggingInterceptor())
    .build();

Request request = new Request.Builder()
    .url("http://www.publicobject.com/helloworld.txt")
    .header("User-Agent", "OkHttp Example")
    .build();

Response response = client.newCall(request).execute();
response.body().close();

The URL http://www.publicobject.com/helloworld.txt redirects to https://publicobject.com/helloworld.txt, and OkHttp follows this redirect automatically. Our application interceptor is called once and the response returned from chain.proceed() has the redirected response:

URL http://www.publicobject.com/helloworld.txt重定向到https://publicobject.com/helloworld.txt，并且OkHttp自动跟随这个重定向。我们的应用程序拦截器被调用一次，从chain.proceed()返回的响应具有重定向响应:

INFO: Sending request http://www.publicobject.com/helloworld.txt on null
User-Agent: OkHttp Example

INFO: Received response for https://publicobject.com/helloworld.txt in 1179.7ms
Server: nginx/1.4.6 (Ubuntu)
Content-Type: text/plain
Content-Length: 1759
Connection: keep-alive

We can see that we were redirected because response.request().url() is different from request.url(). The two log statements log two different URLs.

我们可以看到我们被重定向了，因为response.request().url()与request.url()不同。两个日志语句记录两个不同的url。

Network Interceptors

网络拦截器

Registering a network interceptor is quite similar. Call addNetworkInterceptor() instead of addInterceptor():

注册网络拦截器非常类似。调用addNetworkInterceptor()而不是addInterceptor():

OkHttpClient client = new OkHttpClient.Builder()
    .addNetworkInterceptor(new LoggingInterceptor())
    .build();

Request request = new Request.Builder()
    .url("http://www.publicobject.com/helloworld.txt")
    .header("User-Agent", "OkHttp Example")
    .build();

Response response = client.newCall(request).execute();
response.body().close();

When we run this code, the interceptor runs twice. Once for the initial request to http://www.publicobject.com/helloworld.txt, and another for the redirect to https://publicobject.com/helloworld.txt.

当我们运行这段代码时，拦截器会运行两次。第一次是请求http://www.publicobject.com/helloworld.txt，第二次是重定向到https://publicobject.com/helloworld.txt。

INFO: Sending request http://www.publicobject.com/helloworld.txt on Connection{www.publicobject.com:80, proxy=DIRECT hostAddress=54.187.32.157 cipherSuite=none protocol=http/1.1}
User-Agent: OkHttp Example
Host: www.publicobject.com
Connection: Keep-Alive
Accept-Encoding: gzip

INFO: Received response for http://www.publicobject.com/helloworld.txt in 115.6ms
Server: nginx/1.4.6 (Ubuntu)
Content-Type: text/html
Content-Length: 193
Connection: keep-alive
Location: https://publicobject.com/helloworld.txt

INFO: Sending request https://publicobject.com/helloworld.txt on Connection{publicobject.com:443, proxy=DIRECT hostAddress=54.187.32.157 cipherSuite=TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA protocol=http/1.1}
User-Agent: OkHttp Example
Host: publicobject.com
Connection: Keep-Alive
Accept-Encoding: gzip

INFO: Received response for https://publicobject.com/helloworld.txt in 80.9ms
Server: nginx/1.4.6 (Ubuntu)
Content-Type: text/plain
Content-Length: 1759
Connection: keep-alive

The network requests also contain more data, such as the Accept-Encoding: gzip header added by OkHttp to advertise support for response compression. The network interceptor's Chain has a non-null Connection that can be used to interrogate the IP address and TLS configuration that were used to connect to the webserver.

网络请求还包含更多的数据，比如Accept-Encoding:由OkHttp添加的gzip头来声明对响应压缩的支持。网络拦截器的链具有非空连接，可用于查询用于连接到web服务器的IP地址和TLS配置。

Choosing between application and network interceptors

选择应用程序和网络拦截器

Each interceptor chain has relative merits.

每个拦截链都有相对的优点。

Application interceptors

应用程序拦截器

• Don't need to worry about intermediate responses like redirects and retries.
• 不需要担心中间响应，比如重定向和重试。
• Are always invoked once, even if the HTTP response is served from the cache.
• 总是调用一次，即使从缓存中提供HTTP响应。
• Observe the application's original intent. Unconcerned with OkHttp-injected headers like If-None-Match.
• 观察应用程序的原始意图。不关心像If - None-Match这样的okhttp注入头。
• Permitted to short-circuit and not call Chain.proceed().
• 允许短路和不调用 Chain.proceed()。
• Permitted to retry and make multiple calls to Chain.proceed().
• 允许重试并对Chain.proceed()进行多次调用。

Network Interceptors

网络拦截器

• Able to operate on intermediate responses like redirects and retries.
• 能够操作中间响应，如重定向和重试。
• Not invoked for cached responses that short-circuit the network.
• 不会为了缓存响应而去调用网络短路。
• Observe the data just as it will be transmitted over the network.
• 观察数据，就像它将通过网络传输一样。
• Access to the Connection that carries the request.
• 访问有承载请求的Connection连接。

Rewriting Requests

重写请求

Interceptors can add, remove, or replace request headers. They can also transform the body of those requests that have one. For example, you can use an application interceptor to add request body compression if you're connecting to a webserver known to support it.

拦截器可以添加、删除或替换请求头。它们还可以转换具有一个请求的主体。例如，如果您连接到一个已知支持它的web服务器，您可以使用一个应用程序拦截器来添加请求体压缩。

/** This interceptor compresses the HTTP request body. Many webservers can't handle this! */
final class GzipRequestInterceptor implements Interceptor {
  @Override public Response intercept(Interceptor.Chain chain) throws IOException {
    Request originalRequest = chain.request();
    if (originalRequest.body() == null || originalRequest.header("Content-Encoding") != null) {
      return chain.proceed(originalRequest);
    }

    Request compressedRequest = originalRequest.newBuilder()
        .header("Content-Encoding", "gzip")
        .method(originalRequest.method(), gzip(originalRequest.body()))
        .build();
    return chain.proceed(compressedRequest);
  }

  private RequestBody gzip(final RequestBody body) {
    return new RequestBody() {
      @Override public MediaType contentType() {
        return body.contentType();
      }

      @Override public long contentLength() {
        return -1; // We don't know the compressed length in advance!
      }

      @Override public void writeTo(BufferedSink sink) throws IOException {
        BufferedSink gzipSink = Okio.buffer(new GzipSink(sink));
        body.writeTo(gzipSink);
        gzipSink.close();
      }
    };
  }
}

Rewriting Responses

重写的响应

Symmetrically, interceptors can rewrite response headers and transform the response body. This is generally more dangerous than rewriting request headers because it may violate the webserver's expectations!

对称地说，拦截器可以重写响应头并转换响应主体。这通常比重写请求头更危险，因为它可能违反web服务器的预期!

If you're in a tricky situation and prepared to deal with the consequences, rewriting response headers is a powerful way to work around problems. For example, you can fix a server's misconfigured Cache-Control response header to enable better response caching:

如果您处于一种棘手的情况，并且准备好处理后果，那么重写响应标头是解决问题的一种有效方法。例如，您可以修复服务器配置错误的Cache-Control响应头，以启用更好的响应缓存:

/** Dangerous interceptor that rewrites the server's cache-control header. */
private static final Interceptor REWRITE_CACHE_CONTROL_INTERCEPTOR = new Interceptor() {
  @Override public Response intercept(Interceptor.Chain chain) throws IOException {
    Response originalResponse = chain.proceed(chain.request());
    return originalResponse.newBuilder()
        .header("Cache-Control", "max-age=60")
        .build();
  }
};

Typically this approach works best when it complements a corresponding fix on the webserver!

通常，这种方法在补充web服务器上的相应修复时效果最好!

Availability可用性

OkHttp's interceptors require OkHttp 2.2 or better. Unfortunately, interceptors do not work with OkUrlFactory, or the libraries that build on it, including Retrofit ≤ 1.8 and Picasso ≤ 2.4.

OkHttp的拦截器需要OkHttp 2.2或更高版本。不幸的是,拦截器不是使用OkUrlFactory来进行工作的,或库的构建也不是拦截器来做的,包括Retrofit ≤ 1.8 and Picasso ≤ 2.4的版本也不能使用拦截器。