企业官网建设流程全解析

• 文档
• 教程
• 知识库

本文基于 android-tech-frontier 仓库中 issue-49/Android上的网络响应日志技巧.md 的译文内容整理扩写，并结合仓库内 高效地配置OkHttp、在Android调试模式中使用Stetho、剖析OkHttp缓存机制 等关联译文进行源码级与工程级补充。它系统梳理了 Android 开发中监听与查看网络响应的三条主线：Retrofit 1.x 的内置LogLevel、Retrofit 2.x 迁移到 OkHttp 的HttpLoggingInterceptor，以及以 OkLog 为代表的「把响应变成可点击 URL」的创新方案，并对比了 Facebook Stetho 的 Chrome DevTools 调试路径。读完本文，你将能够根据自身项目所处的 Retrofit 版本选择最合适的响应日志方案，并掌握只在 debug 构建中输出日志的正确姿势。

一、为什么需要网络响应日志

在开发 Android 应用的过程中，从远端服务器加载数据是常态。开发阶段最频繁的动作之一，就是反复确认「应用到底从网络拿到了什么内容」——响应是否完整、JSON 结构是否符合预期、字段是否缺失、编码是否正确。

如果你近几年在写 Android 网络层，几乎必然接触过（或至少听说过）Retrofit 来处理网络请求。那么问题来了：使用 Retrofit 时，监听网络请求有哪些成熟、低成本的选择？这正是本文要回答的核心问题。

一个重要的前提是：日志功能的位置随 Retrofit 版本发生了迁移。Retrofit 1.x 内置日志开关，而 Retrofit 2.x 将 HTTP 底层委托给 OkHttp 3，日志能力随之转移到 OkHttp 的拦截器（Interceptor）体系。理解这条演进脉络，是正确选用方案的第一步。

二、Retrofit 1.x：内置 LogLevel 枚举

如果你还在使用较老的 Retrofit 1.x 版本，可以在创建RestAdapter时，通过RestAdapter.Builder的setLogLevel方法直接开启响应日志：

LogLevel logLevel = LogLevel.FULL; new RestAdapter.Builder() .setClient(client) .setEndpoint(endpoint) .setConverter(converter) .setErrorHandler(errorHandler) .setLogLevel(logLevel) .build();

LogLevel是一个表示日志细节程度的枚举，取值如下：

你可以根据"每个网络请求需要打印多少内容"按需设置对应级别。需要注意，Retrofit 1.x 的日志输出由 Retrofit 自身完成，它并不直接依赖 OkHttp——在 1.x 时代，只要 HTTP 客户端实现了 Retrofit 的客户端接口，就可以自由更换底层实现。

仓库中的 高效地配置OkHttp 展示了 1.x 时代的配套做法：如果你想让 Retrofit 1.9.x 复用自己配置好的OkHttpClient，需要将其包裹进OkClient再传给RestAdapter.Builder.setClient：

restAdapterBuilder.setClient(new OkClient(httpClient));

这意味着在 1.x 中，日志、缓存、超时等能力的配置点是相对分散的——日志归LogLevel管，网络行为归OkHttpClient管。

三、Retrofit 2.x：日志能力迁移到 OkHttp 的 HttpLoggingInterceptor

Retrofit 2.0 稳定版发布后变化巨大。升级后你会发现一个显著差异：无法再直接通过Retrofit.Builder设置 Log Level。

原因在于架构调整：Retrofit 2.x 直接依赖 Square 的另一个库 OkHttp 3 来做实际的 HTTP 网络调用；而 1.x 并未直接依赖 OkHttp，因而可以自由更换 HTTP 客户端。正是这一变化，把日志功能从 Retrofit 迁移到了 OkHttp 中。

现在，要获得与 Retrofit 1.x 等同的日志能力，你需要使用 OkHttp 官方配套的拦截器HttpLoggingInterceptor（它位于 OkHttp 仓库的okhttp-logging-interceptor模块，独立分发）。

3.1 添加 Gradle 依赖

由于它以独立构件形式分发，必须先显式声明：

compile 'com.squareup.okhttp3:logging-interceptor:<latest>'

（项目若使用 Gradle 较新语法，可写为implementation 'com.squareup.okhttp3:logging-interceptor:3.x.x'，其中<latest>需替换为你实际使用的 OkHttp 3 版本号。）

3.2 将拦截器挂到 OkHttpClient

Level logLevel = Level.BODY; HttpLoggingInterceptor interceptor = new HttpLoggingInterceptor(); interceptor.setLevel(logLevel); new OkHttpClient.Builder() .addInterceptor(interceptor) .build();

HttpLoggingInterceptor的Level枚举与 1.x 的LogLevel语义几乎一一对应：

用OkHttpClient.Builder().addInterceptor(...)注册的是应用拦截器（Application Interceptor），它会看到一次完整的请求-响应往返，包括重定向与缓存命中情况；这也正是后续 OkLog 所采用的挂载点。若需要观察更底层的网络细节，OkHttp 还提供了addNetworkInterceptor(...)，在 高效地配置OkHttp 中，Stetho 的StethoInterceptor就是通过networkInterceptors().add(...)挂载的——这是两条截然不同的观测层级，后文对比时值得留意。

3.3 日志的输出效果与痛点

启用Level.BODY后，网络响应的 body 会以纯文本形式出现在 Logcat 中。日志通常被分隔成若干行，往往难以阅读。你通常需要拷贝整段响应文本，再手动剔除开头的时间戳、包名与 Tag；如果遇到的是 JSON 响应，还要借助外部 JSON 格式化工具（如 JsonFormatter、在线 JSON 查看器）才能提高可读性。

原作者的亲身感受是：每次检查网络请求都既繁琐又耗时——这正是他决定创建自己的拦截器、简化整个流程的直接动因，由此诞生了 OkLog。

四、OkLog：把网络响应变成可点击的 URL

OkLog 是针对 OkHttp 网络响应的日志记录拦截器，专为简化开发阶段的响应调试而设计。它的核心创意是：写出一条可访问的 URL，把网络响应内容作为 URL 路径的一部分。这样你就能在 Android Studio 的 Logcat 中直接点击这条日志链接，在浏览器里查看该响应的对应文本——无需复制粘贴，无需手动格式化。

另一个额外的好处是：这些 URL 可以分享给其他开发者（尤其是 REST API 的开发人员），让对方在浏览器中直接看到某个请求的真实响应内容。

OkLog 按 OkHttp 主版本拆分为两个独立构件：

• oklog：对应 OkHttp 2.x（pre-OkHttp3 时代）；
• oklog3：对应 OkHttp 3.x。

4.1 工作原理：gzip + Base64 的 URL 化管线

OkLog 通过实现自己的**应用拦截器（Application Interceptor）**截获 OkHttp 的纯网络响应，处理管线如下：

1. 拿到响应纯文本：拦截器在chain.proceed(request)之后读取响应 body；
2. gzip 压缩：纯文本响应首先经过 gzip 压缩，让字符串尽可能短；
3. Base64 编码：将压缩后的字节流进行 Base64 编码，得到 URL 友好的字符串；
4. 拼装 URL 并输出日志：把编码串作为 URL 路径的一部分，整条 URL 通过日志系统打印出来。

日志通道方面，OkLog 支持两种方式：默认情况下，如果项目依赖了 Timber，它会优先走 Timber 输出；否则回退到 Android 内置的Log方法（也可以强制其使用内置Log）。你甚至可以自定义LogInterceptor来完全接管日志输出行为。

4.2 点击 URL 后发生了什么

默认情况下，生成的 URL 指向一个名为ResponseEcho的 Spring Web 应用托管实例。这个应用的工作恰好与 OkLog 相反：对 URL 路径字符串参数做 Base64 解码、再对参数做 gzip 解压，然后作为普通 HTTP 响应返回。如果解压出来的恰好是 JSON，Web 应用还会返回格式化规整的 JSON，让浏览器阅读起来更友好。

如果你愿意，也可以自行搭建这套 Web 应用，并配置 OkLog 使用你自己的主机名前缀——适合对数据隐私或域名可控性有要求的团队。

4.3 使用步骤

原文档给出的基本使用流程如下：

第一步：添加依赖

// pre-OkHttp3 compile 'com.github.simonpercic:oklog:<latest>' // OkHttp3 compile 'com.github.simonpercic:oklog3:<latest>'

第二步：通过 builder() 构造 OkLogInterceptor

OkLogInterceptor interceptor = OkLogInterceptor.builder() // set desired custom options .build();

第三步：把拦截器加入 OkHttpClient

// for pre-OkHttp3 List<Interceptor> clientInterceptors = okHttpClient.interceptors(); Collections.addAll(clientInterceptors, okLogInterceptor); // for OkHttp3 new OkHttpClient.Builder().addInterceptor(okLogInterceptor).build();

第四步：让 Retrofit 复用这个 OkHttpClient 实例

通常的做法是：通过配置好的okHttpClient实例来构造 Retrofit 2 实例，例如new Retrofit.Builder().client(okHttpClient).baseUrl(...).build()。这样，OkLog 拦截器就自然作用于所有经 Retrofit 发起的请求。同样的复用思想在 高效地配置OkHttp 中有完整工程实践：建议用 Dagger 的@Provides @Singleton保证全局只有一个OkHttpClient，供 Retrofit、Picasso 等组件共享，从而让拦截器、缓存、超时配置集中生效。

4.4 已知限制：4000 字符日志上限

OkLog 走的是 AndroidLog系统，而 Android 日志系统存在约 4000 字符的长度限制。即使 URL 已经过 gzip 压缩和 Base64 编码，遇到较大的网络响应时，生成的 URL 仍可能超出日志行限制。

目前并没有针对性的解决方案，不过大多数情况下一切正常。有一个补救技巧：OkLog 可以选择集成 Timber，而 Timber 会对超长日志进行切片分割，所以你仍能看到超出长度限制的响应内容。如果 URL 被分割成多行，可以手动把所有行串接起来，拼接出完整的有效 URL。

五、另一种实现方式：Facebook Stetho

与直接在 Logcat 打印文本不同，Facebook 的Stetho走的是另一条完全不同的观测路径。

Stetho 并不直接在 Logcat 中输出请求内容，而是依赖 OkHttp/3 的网络拦截器（Network Interceptor），把请求数据桥接到 Chrome Developer Tools，让你在 Chrome 里像调试网页一样查看 Android 应用发起的每一个网络请求：请求头、响应头、时序、耗时一目了然。

在 高效地配置OkHttp 中可以找到极简接入方式：

okHttpClient.networkInterceptors().add(new StethoInterceptor());

随后在 Chrome 中导航到chrome://inspect，会出现设备和应用 id 的列表，点击inspect打开 Developer Tools，切到 Network 标签即可观察 OkHttp 的请求。该文还提醒：这个拦截器能顺带确认服务端返回的 HTTP 头是否允许缓存、以及存在缓存数据时是否会发起网络请求，等于同时给了你一层网络观测 + 缓存行为验证能力。

Stetho 的另外一大能力是访问应用内的 SQLite 数据库和 View 层级，这在 在Android调试模式中使用Stetho 中有专门介绍。关键工程要点是：Stetho 这类调试工具应当只进入 debug 构建。原文给出的做法是：

dependencies { // your other dependencies here... debugCompile 'com.facebook.stetho:stetho:1.0.0' }

再配合src/debug/java源码目录中继承自MyApplication的MyDebugApplication完成Stetho.initialize(...)，并通过src/debug下的AndroidManifest.xml用tools:replace="android:name"替换主 Manifest 中的android:name。这样一来，Stetho 只在 debug 构建中被激活，release 构建中既不会激活、也不留任何痕迹。这套「debug-only 源码目录 + Manifest 合并」的技巧，同样适用于 OkLog、HttpLoggingInterceptor 等所有调试期网络日志工具。

Chrome Developer Tools 无疑非常强大，能展示与网络活动相关的海量信息。但它的定位也更重：如果你只是希望快速瞄一眼某个请求的响应，它未必是最快的路径；而且你无法便捷地把这些信息分享给他人——除非手动复制。

六、如何选择：组合拳与 debug-only 铁律

原作者的观点很明确：并不存在放之四海而皆准的标准，不同场景有不同的最佳方案。他个人项目中的实践是：

• 使用 OkHttp 的HttpLoggingInterceptor，在 Logcat 中直接输出与请求相关的基本信息——胜在零成本、全局可见；
• 同时使用 OkLog，在浏览器中快速查看具体网络响应，并方便地与同事共享——胜在可读性与可分享性；
• 如果团队更看重完整的请求生命周期、时序分析与数据库调试，Stetho + Chrome DevTools 是强有力的补充。

给出一个便于决策的小结：

无论选择哪一种，有一条铁律必须遵守：只能在自己的 debug 版本中打印网络响应，绝不要在 release 版本中输出任何日志。release 版本中的日志不仅可能泄露接口结构、业务数据等敏感信息，还会带来无谓的性能开销——这正是调试工具必须用debugCompile依赖 +src/debug源码目录隔离的根本原因。

七、延伸：OkHttp 拦截器与缓存机制的底层联动

既然日志拦截器都挂在 OkHttp 上，理解 OkHttp 的请求处理模型会让你的日志配置更精准。结合仓库内的 剖析OkHttp缓存机制 可以看到：OkHttp 的缓存判断核心在CacheStrategy与HttpEngine，CacheStrategy.getCandidate()会基于缓存候选响应的Date、Expires、Last-Modified、ETag、Age等报头计算新鲜度，并决定是直接命中缓存、发起条件请求（If-None-Match/If-Modified-Since）还是强制网络请求。

这对日志调试有两个实际影响：

1. 观察点选择：应用拦截器（addInterceptor，OkLog、HttpLoggingInterceptor 的挂载点）能看到「应用视角」的完整往返结果，包括缓存命中的响应；网络拦截器（addNetworkInterceptor，Stetho 的挂载点）则能看到实际发到网络上的请求。同样是"看响应"，二者看到的层级不同。
2. 离线与强制刷新语义：Cache-Control: only-if-cached能让报文永不触网、无缓存时抛 504；Cache-Control: max-stale=[seconds]允许在新鲜期外继续用缓存；no-cache则强制走网络。理解这些语义后，你会发现"日志里有时看不到请求"很可能不是日志失效，而是缓存策略让请求根本没出网——这是排障时最常见的误判之一。

结语

从 Retrofit 1.x 的LogLevel，到 Retrofit 2.x 时代 OkHttp 的HttpLoggingInterceptor，再到把响应塞进 URL 的 OkLog、用 Chrome DevTools 观天下的 Stetho，Android 网络响应日志的演进始终围绕两个诉求：看得清与拿得快。本文所梳理的代码均出自 issue-49/Android上的网络响应日志技巧.md，工程化补充来自 高效地配置OkHttp、在Android调试模式中使用Stetho 与 剖析OkHttp缓存机制，可直接在当前仓库中对照原文继续深入。选好工具、锁死 debug 构建，你的网络调试效率将迎来肉眼可见的提升。

• 文档
• 教程
• 知识库