OkHttp Interceptors（一）

本文中源码基于OkHttp 3.6.0

• 《OkHttp Request 请求执行流程》
• 《OkHttp - Interceptors（一）》
• 《OkHttp - Interceptors（二）》
• 《OkHttp - Interceptors（三）》
• 《OkHttp - Interceptors（四）》

上一篇文章《OkHttp Request 请求执行流程》中分析我们知道 OkHttp 的请求是一个链式的过程，在 RealCall 的 getResponseWithInterceptorChain() 方法中构建了一个请求处理链，链上的每一个节点都有相对独立的功能，当它们完成自己的请求任务后就把处理结果返回给上一个节点，直到最后返回给发起请求的用户。这些处理请求的节点就是 Interceptor，它们由下面几种类型构成：

1. 自定义 Interceptors ，由用户自定义的 Interceptor，最早接收到 Request、最后完成对 Response 的处理；
2. RetryAndFollowupInterceptor，负责处理链接失败时的重试及重定向请求；
3. BridgeInterceptor， 负责处理请求的 headers、cookie、gzip；
4. CacheInterceptor，负责匹配请求的缓存、验证缓存有效性、及保存响应的缓存；
5. ConnectInterceptor，负责创建到服务器的链接；
6. 自定义 Network Interceptors，同样由用户自定义，与之前的 Interceptor 最大的区别就是，请求执行到这里已经与服务器建立上了连接；
7. CallServerInterceptor，对服务器发起实际的请求，接收返回结果。

下面我们按照顺序依次来分析各个系统 Interceptor 对请求的处理。

---

RetryAndFollowupInterceptor

RetryAndFollowupInterceptor 是第一个接收到 Request 的系统 Interceptor ，它的主要作用是在后续 Interceptor 处理请求遇到错误时，重新构造一个新的 Request 并再次发起请求，下面我们来看看它的 intercept 方法。

public Response intercept(Chain chain) throws IOException {
  Request request = chain.request();
  // 构建一个 StreamAllocation，其提供建立连接、管理复用连接的能力
  streamAllocation = new StreamAllocation(
      client.connectionPool(), createAddress(request.url()), callStackTrace);

  // 重定向次数计数器，默认超过20次就直接抛出错误
  int followUpCount = 0;
  Response priorResponse = null;
  while (true) {
    if (canceled) {
      streamAllocation.release();
      throw new IOException("Canceled");
    }

    Response response = null;
    boolean releaseConnection = true;
    try {
      // 交给下一个 Interceptor 处理请求
      response = ((RealInterceptorChain) chain).proceed(request, streamAllocation, null, null);
      releaseConnection = false;
    } catch (RouteException e) {
      // 连接失败，判断是否可以恢复连接，若不可恢复，直接抛出异常结束请求。此时还没有发送请求
      if (!recover(e.getLastConnectException(), false, request)) {
        throw e.getLastConnectException();
      }
      releaseConnection = false;
      continue;
    } catch (IOException e) {
      // 在与服务器的通信过程中发生错误，判断是否可以恢复连接，此时可能已经向服务器发送了请求
      boolean requestSendStarted = !(e instanceof ConnectionShutdownException);
      if (!recover(e, requestSendStarted, request)) throw e;
      releaseConnection = false;
      continue;
    } finally {
      // 其他异常不处理，关闭连接释放资源。
      if (releaseConnection) {
        streamAllocation.streamFailed(null);
        streamAllocation.release();
      }
    }
    // Attach the prior response if it exists. Such responses never have a body.
    if (priorResponse != null) {
      response = response.newBuilder()
          .priorResponse(priorResponse.newBuilder()
              .body(null)
              .build())
          .build();
    }

    // 根据服务器返回响应构造一个新的 Request
    Request followUp = followUpRequest(response);
    // 如果不支持重试，直接返回服务器结果
    if (followUp == null) {
      if (!forWebSocket) {
        streamAllocation.release();
      }
      return response;
    }

    closeQuietly(response.body());

    if (++followUpCount > MAX_FOLLOW_UPS) {
      streamAllocation.release();
      throw new ProtocolException("Too many follow-up requests: " + followUpCount);
    }

    if (followUp.body() instanceof UnrepeatableRequestBody) {
      streamAllocation.release();
      throw new HttpRetryException("Cannot retry streamed HTTP body", response.code());
    }

    // 如果不能复用一条连接，需要使用新的地址重新构建一个连接
    if (!sameConnection(response, followUp.url())) {
      streamAllocation.release();
      streamAllocation = new StreamAllocation(
          client.connectionPool(), createAddress(followUp.url()), callStackTrace);
    } else if (streamAllocation.codec() != null) {
      throw new IllegalStateException("Closing the body of " + response
          + " didn't close its backing stream. Bad interceptor?");
    }

    request = followUp;
    priorResponse = response;
  }
}
复制代码

在将请求交由下一个节点处理之前，RetryAndFollowupInterceptor 创建了一个 StreamAllocation ，这个对象用来创建并维护客户端到服务器的链接，在分析 ConnectInterceptor 的时候我们再来详细地讲解其功能实现。

在请求执行的过程中，由于网络等原因，可能会出现与服务器链接失败、数据传输失败等情况，为了尽量保证请求的可靠性，OkHttp 会自动对失败的请求进行重试。这时通过 recover() 判断客户端是否可以恢复与服务器的连接，如果可以恢复，那么会使用 StreamAllocation 选择另外一个 Route 重新创建一个连接；如果不能恢复则只能关闭连接，抛出异常。

private boolean recover(IOException e, boolean requestSendStarted, Request userRequest) {
  streamAllocation.streamFailed(e);

  // 如果在 OkHttpClient 中设置了retryOnConnectionFailure，表示我们不允许进行请求重试
  if (!client.retryOnConnectionFailure()) return false;

  // 如果请求中包含不能重复提交的内容，则不允许重试
  if (requestSendStarted && userRequest.body() instanceof UnrepeatableRequestBody) return false;

  // 根据错误类型判断是否能够重试
  if (!isRecoverable(e, requestSendStarted)) return false;

  // 连接中并不存在下一个路由地址，则不能重试
  if (!streamAllocation.hasMoreRoutes()) return false;

  // For failure recovery, use the same route selector with a new connection.
  return true;
}
复制代码

在我们正常连接到服务器并发起请求的情况下，服务器返回的 Response 任然有可能不是我们需要的结果，比如发生服务器需要身份认证（401）、重定向（30x）的时候。那么下面我们再来看看 OkHttp 中对这一部分逻辑的处理。

private Request followUpRequest(Response userResponse) throws IOException {
  if (userResponse == null) throw new IllegalStateException();
  Connection connection = streamAllocation.connection();
  Route route = connection != null
      ? connection.route()
      : null;
  int responseCode = userResponse.code();

  final String method = userResponse.request().method();
  switch (responseCode) {
    // 407，代理认证，表示需要经过代理服务器的授权
    case HTTP_PROXY_AUTH:
      Proxy selectedProxy = route != null
          ? route.proxy()
          : client.proxy();
      if (selectedProxy.type() != Proxy.Type.HTTP) {
        throw new ProtocolException("Received HTTP_PROXY_AUTH (407) code while not using proxy");
      }
      // 交由 OkHttpClient 中设置的代理认证处理，默认未设置
      return client.proxyAuthenticator().authenticate(route, userResponse);

    // 401，基本认证，访问被拒绝，需要授权
    case HTTP_UNAUTHORIZED:
      // 交由用户设置的认证处理，默认未设置
      return client.authenticator().authenticate(route, userResponse);

    // 308，永久迁移
    case HTTP_PERM_REDIRECT:
    // 307，临时迁移
    case HTTP_TEMP_REDIRECT:
      // 服务器为了禁止一味地使用重定向，将这几个状态码区分开，如果该请求不是 GET 或者 HEAD，那么不进行自动重定向，交给用户自己处理
      if (!method.equals("GET") && !method.equals("HEAD")) {
        return null;
      }
    // 300，请求的资源存在多个候选地址，同时返回一个选项列表
    case HTTP_MULT_CHOICE:
    // 301，资源被移动到新的位置
    case HTTP_MOVED_PERM:
    // 302，类似301
    case HTTP_MOVED_TEMP:
    // 303，类似301、302
    case HTTP_SEE_OTHER:
      // 如果设置禁止重定向，则返回 null
      if (!client.followRedirects()) return null;

      String location = userResponse.header("Location");
      if (location == null) return null;
      // 解析 Location 中地址
      HttpUrl url = userResponse.request().url().resolve(location);

      // Don't follow redirects to unsupported protocols.
      if (url == null) return null;

      // 这里判断原始请求地址和重定向的地址是否使用相同协议（同为 Http 或 Https）
      boolean sameScheme = url.scheme().equals(userResponse.request().url().scheme());
      // 判断 OkHttp 中配置是否允许跨协议的重定向
      if (!sameScheme && !client.followSslRedirects()) return null;

      // Most redirects don't include a request body.
      Request.Builder requestBuilder = userResponse.request().newBuilder();
      // 这里处理重定向请求中的实体部分
      if (HttpMethod.permitsRequestBody(method)) {
        // 重定向中是否允许携带实体（PROPFIND方法允许携带实体，其他方法不允许携带实体，需要将请求改为 GET 请求）
        final boolean maintainBody = HttpMethod.redirectsWithBody(method);
        if (HttpMethod.redirectsToGet(method)) {
          requestBuilder.method("GET", null);
        } else {
          RequestBody requestBody = maintainBody ? userResponse.request().body() : null;
          requestBuilder.method(method, requestBody);
        }
        if (!maintainBody) {
          requestBuilder.removeHeader("Transfer-Encoding");
          requestBuilder.removeHeader("Content-Length");
          requestBuilder.removeHeader("Content-Type");
        }
      }

      // When redirecting across hosts, drop all authentication headers. This
      // is potentially annoying to the application layer since they have no
      // way to retain them.
      if (!sameConnection(userResponse, url)) {
        requestBuilder.removeHeader("Authorization");
      }
      // 使用重定向指定地址构建一个新的 request
      return requestBuilder.url(url).build();

    // 408，请求超时，不修改请求，直接重试
    case HTTP_CLIENT_TIMEOUT:
      // 408's are rare in practice, but some servers like HAProxy use this response code. The
      // spec says that we may repeat the request without modifications. Modern browsers also
      // repeat the request (even non-idempotent ones.)
      if (userResponse.request().body() instanceof UnrepeatableRequestBody) {
        return null;
      }

      return userResponse.request();

    default:
      return null;
  }
}
复制代码

RetryAndFollowupInterceptor 在接收到来自服务器的 Response 后，通过 followUpRequest() 方法判断是否需要对该请求进行重试，如果需要重试，则构建一个新的 Request 以便再次发起请求；如果拿到的 Response 就是最终的结果，就直接将 Response 返回给用户，完成请求。

BridgeInterceptor

BridgeInterceptor 中的源码理解起来相对比较简单，在将请求交付给下一个处理节点前，它的主要作用是在 Request 的 Header 中添加缺失的头部信息（Content-Type、本地存储的 Cookie 信息），以及在接收到服务器返回的 Response 后存储 Header 中的 Cookie，并解压响应实体（如果是 gzip 的话）。

public Response intercept(Chain chain) throws IOException {
  Request userRequest = chain.request();
  Request.Builder requestBuilder = userRequest.newBuilder();

  RequestBody body = userRequest.body();
  if (body != null) {
    MediaType contentType = body.contentType();
    if (contentType != null) {
      // 设置 Content-Type（text、image、video 等）
      requestBuilder.header("Content-Type", contentType.toString());
    }

    // contentLength 用于标识实体实体大小，便于服务器判断实体是否传输完毕。
    // 如果指定了 contentLength，则在 header 中添加；如果没有指定，则使用 Transfer-Encoding: chunked 分块编码方式。
    long contentLength = body.contentLength();
    if (contentLength != -1) {
      requestBuilder.header("Content-Length", Long.toString(contentLength));
      requestBuilder.removeHeader("Transfer-Encoding");
    } else {
      requestBuilder.header("Transfer-Encoding", "chunked");
      requestBuilder.removeHeader("Content-Length");
    }
  }

  // 设置 Host
  if (userRequest.header("Host") == null) {
    requestBuilder.header("Host", hostHeader(userRequest.url(), false));
  }

  // 请求保持连接
  if (userRequest.header("Connection") == null) {
    requestBuilder.header("Connection", "Keep-Alive");
  }

  // If we add an "Accept-Encoding: gzip" header field we're responsible for also decompressing
  // the transfer stream.
  boolean transparentGzip = false;
  if (userRequest.header("Accept-Encoding") == null && userRequest.header("Range") == null) {
    transparentGzip = true;
    requestBuilder.header("Accept-Encoding", "gzip");
  }

  // 获取对应 url 下的 cookie
  List<Cookie> cookies = cookieJar.loadForRequest(userRequest.url());
  if (!cookies.isEmpty()) {
    requestBuilder.header("Cookie", cookieHeader(cookies));
  }

  if (userRequest.header("User-Agent") == null) {
    requestBuilder.header("User-Agent", Version.userAgent());
  }

  // 后续 Interceptor 处理请求
  Response networkResponse = chain.proceed(requestBuilder.build());

  // 保持 Response 中的 cookie
  HttpHeaders.receiveHeaders(cookieJar, userRequest.url(), networkResponse.headers());

  Response.Builder responseBuilder = networkResponse.newBuilder()
      .request(userRequest);

  // 如果请求中设置了 Content-Encoding: gzip,完成对 body 的解压
  if (transparentGzip
      && "gzip".equalsIgnoreCase(networkResponse.header("Content-Encoding"))
      && HttpHeaders.hasBody(networkResponse)) {
    GzipSource responseBody = new GzipSource(networkResponse.body().source());
    Headers strippedHeaders = networkResponse.headers().newBuilder()
        .removeAll("Content-Encoding")
        .removeAll("Content-Length")
        .build();
    responseBuilder.headers(strippedHeaders);
    responseBuilder.body(new RealResponseBody(strippedHeaders, Okio.buffer(responseBody)));
  }

  return responseBuilder.build();
}
复制代码