Deep Dive into OkHttp: Core Principles, Interceptor Chain, and Practical Usage

OkHttp is widely used in Java and Android for HTTP communication; studying its source code helps developers understand its design and improve coding skills.

1. Background – Interceptors offer an elegant way to uniformly modify requests or responses, such as adding headers.

2. Core Principles

2.1 A simple synchronous GET request example:

OkHttpClient client = new OkHttpClient();
public String getSync(String url) throws IOException {
    OkHttpClient client = new OkHttpClient();
    // 2.创建一个Request对象
    Request request = new Request.Builder()
            .url(url)
            .build();
    // 3.创建一个Call对象并调用execute()方法
    try (Response response = client.newCall(request).execute()) {
        return response.body().string();
    }
}

The entry point is the execute() method of RealCall :

@Override
public Response execute() throws IOException {
    synchronized (this) { // 同步锁定当前对象，将当前对象标记为“已执行”
        if (executed) throw new IllegalStateException("Already Executed");
        executed = true;
    }
    captureCallStackTrace(); // 捕获调用栈
    eventListener.callStart(this); // 事件监听器记录“调用开始”事件
    try {
        client.dispatcher().executed(this); // 调度器将当前对象放入“运行中”队列
        Response result = getResponseWithInterceptorChain(); // 通过拦截器发起调用并获取响应
        if (result == null) throw new IOException("Canceled");
        return result;
    } catch (IOException e) {
        eventListener.callFailed(this, e); // 异常时记录“调用失败事件”
        throw e;
    } finally {
        client.dispatcher().finished(this); // 将当前对象从“运行中”队列移除
    }
}

2.2 The method that builds the interceptor chain:

Response getResponseWithInterceptorChain() throws IOException {
    // 构建一个全栈的拦截器列表
    List
interceptors = new ArrayList<>();
    interceptors.addAll(client.interceptors());
    interceptors.add(retryAndFollowUpInterceptor);
    interceptors.add(new BridgeInterceptor(client.cookieJar()));
    interceptors.add(new CacheInterceptor(client.internalCache()));
    interceptors.add(new ConnectInterceptor(client));
    if (!forWebSocket) {
        interceptors.addAll(client.networkInterceptors());
    }
    interceptors.add(new CallServerInterceptor(forWebSocket));
    Interceptor.Chain chain = new RealInterceptorChain(interceptors, ……);
    return chain.proceed(originalRequest);
}

OkHttp’s architecture is layered (application‑interface, protocol, connection, cache, I/O) and each layer can be customized via interceptors.

2.5 Interceptor chain implementation – the proceed() method:

public Response proceed(Request request, StreamAllocation streamAllocation, HttpCodec httpCodec, RealConnection connection) throws IOException {
    if (index >= interceptors.size()) throw new AssertionError();
    // …
    RealInterceptorChain next = new RealInterceptorChain(interceptors, streamAllocation, httpCodec, connection, index + 1, request, call, eventListener, connectTimeout, readTimeout, writeTimeout);
    Interceptor interceptor = interceptors.get(index);
    Response response = interceptor.intercept(next);
    // …
    return response;
}

This method demonstrates the three steps of the chain: index check, creation of the next chain object, and invoking the interceptor’s intercept() method, which may recursively call chain.proceed() .

3. Practical Application – Adding a custom interceptor to inject an Authorization header:

public class EncryptInterceptor implements Interceptor {
    @Override
    public Response intercept(Chain chain) throws IOException {
        Request originRequest = chain.request();
        // 计算认证信息
        String authorization = this.encrypt(originRequest);
        // 添加请求头
        Request request = originRequest.newBuilder()
                .addHeader("Authorization", authorization)
                .build();
        // 向责任链后面传递
        return chain.proceed(request);
    }
}

Register the interceptor when building the client:

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

4. Summary – Understanding OkHttp’s interceptor chain, layered architecture, and design patterns (responsibility chain, decorator) enables developers to write cleaner code, troubleshoot issues efficiently, and extend the client with custom behavior for specific business needs.