Retrofit实战指南：从原理、注解到拦截器与高频坑解析

接手一个老项目的第一周，我在代码里翻到一个 AsyncTask，类名叫 LoadDataTask，里面用 HttpURLConnection 写了两百多行网络请求。connection 手动开关、InputStream 手动读、JSON 手动解析、错误手动分类，测一次要吐一次。我当时就跟同事说：这玩意儿早该用 Retrofit 了。

先简单交代一下背景：Retrofit 是 Square 团队开源的 JAVA/Android 网络请求框架，底层把 HTTP 细节交给 OkHttp，自己专门解决“接口声明”和“请求封装”之间的翻译问题。对，它不是网络协议库，而是一个让代码变优雅的翻译官。这篇实战文章会围绕原理、注解、转换器、拦截器和高频坑来写，适合刚接触 Retrofit 的新人，也适合正在把老项目网络层重构到 Retrofit 的工程师。接下来我会从最笨的写法讲起，对照着看，你才会真正理解 Retrofit 的每一层设计到底省了什么。

1. 为什么说 Retrofit 几乎成了 Android 网络层的默认选项？别再从最笨的写法开始了

1.1 没有框架的年代，一个网络请求要写多少行

先还原一下最原始的写法。问题是：向https://api.example.com/users?page=1发一个 GET 请求，拿回一个 JSON 数组，解析成 List ，展示到界面上。

用 HttpURLConnection 的话，你至少要做这些事：拼 URL、处理编码、打开连接、设置请求方法、设置头、判断响应码、读 InputStream、把响应流转成字符串、把字符串交给 JSON 解析器、解析完还要自己切回主线程、处理各种异常。

private void loadUsers(int page) { new AsyncTask<Integer, Void, List<User>>() { @Override protected List<User> doInBackground(Integer... params) { HttpURLConnection connection = null; try { URL url = new URL("https://api.example.com/users?page=" + params[0]); connection = (HttpURLConnection) url.openConnection(); connection.setRequestMethod("GET"); connection.setConnectTimeout(10000); int code = connection.getResponseCode(); if (code != 200) throw new IOException("HTTP " + code); InputStream in = connection.getInputStream(); String json = readStream(in); return new Gson().fromJson(json, new TypeToken<List<User>>() {}.getType()); } catch (Exception e) { e.printStackTrace(); return null; } finally { if (connection != null) connection.disconnect(); } } @Override protected void onPostExecute(List<User> users) { if (users != null) updateUi(users); } }.execute(page); }

这段代码有很多隐患：连接没复用、线程管理靠 AsyncTask、错误处理基本靠 printStackTrack、JSON 解析和传输层耦合在一起。项目里接口一旦多起来，每个接口都要复制粘贴一遍，维护成本直接原地爆炸。

1.2 Retrofit 和 OkHttp 的关系：不是替代，是分工

很多人刚接触时会把 Retrofit 和 OkHttp 搞混。其实两者是配合关系，不是二选一。

• OkHttp：真正的 HTTP 客户端。它负责连接管理、读写超时、连接池复用、HTTP/2、缓存、拦截器这些底层的网络传输细节。
• Retrofit：一个“接口翻译层”。它做的事是把你声明的 Java 接口方法，翻译成一个 OkHttp 的 Request，然后发起调用，再把 ResponseBody 转换成你要的返回类型。

简单说，OkHttp 是引擎，Retrofit 是方向盘和仪表盘。你可以在项目里直接用 OkHttp，也能用 Retrofit，但没有人会闲到用 Retrofit 去替代 OkHttp。两者的分工也让 Retofit 足够轻，因为底层的优秀能力全部由 OkHttp 提供。

1.3 用上 Retrofit 之后，同样的需求长什么样

换成 Retrofit 后，代码变成两部分：接口声明 + 调用。

public interface ApiService { @GET("users") Call<List<User>> listUsers(@Query("page") int page); }

调用方只需要：

ApiService api = retrofit.create(ApiService.class); api.listUsers(1).enqueue(new Callback<List<User>>() { @Override public void onResponse(Call<List<User>> call, Response<List<User>> response) { updateUi(response.body()); } @Override public void onFailure(Call<List<User>> call, Throwable t) { handleError(t); } });

对比一下这两版代码：业务代码里已经看不到 URL 拼接、看不到 InputStream、看不到 JSON 手动解析，你要做的就是“像调用本地方法一样调用远程接口”。这样的抽象，才是网络请求框架真正给人带来的价值。

2. 动态代理与注解解析：一行接口声明是怎么变成一次完整HTTP请求的？

2.1 Retrofit 的魔法核心：动态代理

Retrofit 最容易被忽略、也最值得搞明白的一点是：它并没有为你的ApiService接口生成一个实现类。你写接口，它返回接口实例，这件事完全是靠 Java 的动态代理做到的。

动态代理是 JDK 提供的能力，java.lang.reflect.Proxy可以在运行时为你指定的接口生成一个“影子实现”。这个影子实现的每个方法被调用时，都会进入同一个InvocationHandler.invoke方法。Retrofit 的create方法大致长这样：

public <T> T create(final Class<T> service) { return (T) Proxy.newProxyInstance( service.getClassLoader(), new Class<?>[] { service }, new InvocationHandler() { @Override public Object invoke(Object proxy, Method method, Object[] args) throws Throwable { ServiceMethod<T, ?> serviceMethod = loadServiceMethod(method); return serviceMethod.invoke(args); } }); }

这段是简化示意，但逻辑是真的：你调用api.listUsers(1)，实际上会进到invoke方法里，然后由ServiceMethod去构造网络请求并返回Call对象。这个设计解决了接口实现类的维护问题——接口改了，代理逻辑不用动，注解一变，请求就跟着变。

2.2 ServiceMethod 的构建与缓存

loadServiceMethod做的事是从一个ConcurrentHashMap里查方法对应的ServiceMethod，查不到就现场构建。

构建过程可以理解成“注解翻译”：

1. 读取方法上的注解，比如@GET("users")，得到 HTTP 方法和相对路径。
2. 读取参数注解，比如@Query("page") int page，得到参数在 URL 上的位置和名字。
3. 读取返回值类型，比如Call<List<User>>，确定这个方法的“请求壳”和“返回类型”。
4. 把这些信息攒进RequestBuilder，最终转成okhttp3.Request。
5. 发起 OkHttp 请求，拿到ResponseBody后，再根据返回类型用Converter做转换。

这里有个很关键的设计：方法的解析发生在第一次调用时，之后从缓存里读取。所以你不用担心反射开销。项目里几十个接口，每个接口真正被调用过一次之后，后续所有请求都是走的缓存，性能上没有任何问题。

2.3 为什么这个设计让人舒服

从工程角度讲，这种做法的核心价值是“接口即契约”。

写接口的人只需要声明“我要 GET 哪个路径、参数叫什么、返回什么类型”，完全不需要关心 HTTP 底层。调用方看到的也是类型安全的方法签名，参数错了在编译期就报错，而不是等到运行时才小心翼翼拼字符串。

这套设计还方便测试。因为接口实现是动态代理出来的，你甚至可以传入一个假的Retrofit，让所有方法返回 mock 数据，业务代码完全不用改。这也是 Retrofit 能在各类项目里经久不衰的重要原因。

3. 注解体系全拆解：从@GET到@Multipart，每个符号背后都有规则

3.1 请求方法注解

Retrofit 提供了@GET、@POST、@PUT、@PATCH、@DELETE、@HEAD、@OPTIONS，以及一个通用的@HTTP。

@HTTP的典型用法是动态指定请求方法，比如有时候你要根据配置决定走DELETE还是POST：

@HTTP(method = "DELETE", path = "users/{id}", hasBody = false) Call<ResponseBody> deleteUser(@Path("id") long id);

绝大多数情况建议直接用@GET、@POST这种语义化注解，代码读起来更清楚。

3.2 参数注解：各自负责放对位置

下面这个是参数注解的核心表格，建议先收藏，等用到时直接对照：

一个包含多种参数的真实示例：

@POST("users/{id}/update") Call<User> updateUser( @Path("id") long id, @Query("debug") boolean debug, @Header("Authorization") String token, @Body UpdateUserRequest request);

这段请求最终会被解析成类似这样的形式：POSThttps://api.example.com/users/123/update?debug=true，同时带Authorization请求头，请求体是UpdateUserRequest的 JSON 序列化结果。

3.3 表单与文件上传：切对模式才能用对参数

三个最容易搞混的请求体格式是 JSON、表单、multipart。

• JSON：用@Body，不额外加方法注解，默认通过 Converter 把对象序列化成 JSON。这是目前最常用的模式。
• 普通表单：方法上加@FormUrlEncoded，参数用@Field。
• 文件上传：方法上加@Multipart，文件参数用@Part MultipartBody.Part，文本参数用@Part("key") RequestBody或@PartMap。

@Multipart @POST("upload") Call<UploadResult> uploadFile( @Part("description") RequestBody description, @Part MultipartBody.Part file);

注意：没有@FormUrlEncoded却用了@Field，或者没有@Multipart却用了@Part，在构建请求时会直接抛出异常。这类错误在编译期发现不了，建议接口定义一写好就先跑一次 mock 调用，确认注解组合没问题。

3.4 参数规则里的易错点

说三个我实际踩过、也被问过无数次的点。

第一，@Query值为 null 时参数会被忽略。如果你需要“传空字符串”让后端感知这个参数存在，要传""而不是 null。

第二，@Path占位符{id}里的变量默认会做 URL 编码。拿@Path("key")传一个a/b，最终路径里是a%2Fb，不是a/b。如果你确实想让这个斜杠变成路径分隔符之一，要仔细确认后端到底期望哪种形态。

第三，@Url和@Path不能同时出现，因为@Url会直接决定最终请求地址，路径占位符没有意义。有动态拼接路径需求的场景，优先考虑在@Url外面先拼好完整地址，或者干脆用两个不同的接口方法。

4. Converter与CallAdapter：让入参和返回值都变成你想要的形状

4.1 响应体转换链路

默认情况下，Retrofit 的方法返回类型可以是Call<ResponseBody>，这时拿到的ResponseBody是 OkHttp 原始响应体，你必须自己调用response.body().string()去读字符串，再手动查 JSON。

这样用太麻烦，所以 Retrofit 设计了 Converter。注册一个GsonConverterFactory之后，Call<List<User>>里的List<User>就能直接从响应体转换过来。

转换链路是这样的：OkHttp 拿到响应后，Retrofit 根据方法声明的返回类型，从已注册的 Converter 列表里找到一个能处理ResponseBody -> List<User>的转换器，转换完成后通过CallAdapter包装成Call、Observable或协程挂起返回值。注意这里有个顺序问题：注册在前的 Converter 优先被使用。所以如果你有几个自定义 Converter 或第三方 Converter，一定要把最具体、最不该被“抢占”的注册放在前面。

4.2 常见 Converter 怎么选

Retrofit 官方和第三方提供了一些常用实现：

• GsonConverterFactory：最普及，配合 Gson 使用。
• MoshiConverterFactory：Square 自家出品，运行时开销更小，配合 Moshi 使用。
• JacksonConverterFactory：适合从 Java 后端背景来的团队。
• ScalarsConverterFactory：支持直接返回String、Integer、Long等简单类型。

我的建议很简单：如果项目已经深度使用 Gson 和它的注解体系，就继续用 Gson；如果新项目且对性能敏感，可以试试 Moshi，但不要频繁换。统一序列化库，比追求某个库的微性能重要得多。

4.3 CallAdapter：决定返回值的外壳

Converter 负责转换数据本身，CallAdapter 负责处理“怎么把这个请求交出去”。默认 Retrofit 能返回Call<T>、Call<T>的子类以及suspend函数（2.6.0 之后内置支持）。

接入 RXJava 时注册RxJava2CallAdapterFactory，接口就可以写成：

@GET("users") Observable<List<User>> listUsers(@Query("page") int page);

接入协程后，接口又能写成：

@GET("users") suspend fun listUsers(@Query("page") int page): List<User>

注意：suspend是内置支持的，不需要额外 CallAdapter。它的原理是 Retrofit 把你的挂起函数翻译成启动一个异步请求，然后通过续体在合适的时候恢复。使用协程版本后，不需要enqueue，直接调用就能拿到结果，代码像同步一样写，性能上是异步的。

4.4 实战：自己写一个能把响应体转成String的Converter

很多项目在接口固定返回 JSON 的前提下，仍然会遇到“只需要一个原始字符串”的场景。Retrofit 默认并不支持Call<String>，因为内置 Converter 只处理ResponseBody和Void。这时自己写一个很小巧的 Converter 就很有用。

public class StringConverterFactory extends Converter.Factory { @Override public Converter<ResponseBody, ?> responseBodyConverter( Type type, Annotation[] annotations, Retrofit retrofit) { if (type == String.class) { return new Converter<ResponseBody, String>() { @Override public String convert(ResponseBody value) throws IOException { return value.string(); } }; } return null; } }

注册顺序记得放在第一个：

new Retrofit.Builder() .baseUrl("https://api.example.com/") .addConverterFactory(new StringConverterFactory()) .addConverterFactory(GsonConverterFactory.create()) .build();

结果就是：接口里写Call<String>能正常工作，而Call<List<User>>仍然走 Gson。这个例子的意义不在于你非要这么做，而在于你理解了“Converter 是个插槽”之后，遇到任何不常见的返回类型都能自己接招。

5. 拦截器体系与网络优化：日志、缓存、Token刷新、重试一次配齐

5.1 日志拦截器：开发调试第一帮手

在 OkHttpClient 上添加HttpLoggingInterceptor是最常见的做法。

HttpLoggingInterceptor logging = new HttpLoggingInterceptor(); logging.setLevel(HttpLoggingInterceptor.Level.BODY); OkHttpClient client = new OkHttpClient.Builder() .addInterceptor(logging) .build();

Level.BODY会打印完整的 URL、请求头、请求体、响应头和响应体。这在调试阶段非常好用，但生产环境千万不要开 BODY，尤其是有敏感字段的接口。可以在 BuildConfig 里根据 debug/release 切换日志级别。

5.2 统一 Token 注入与刷新

统一加 Header 最简单的方式是写一个应用拦截器：

class AuthInterceptor implements Interceptor { @Override public Response intercept(Chain chain) throws IOException { Request request = chain.request(); Request newRequest = request.newBuilder() .header("Authorization", "Bearer " + tokenProvider.getToken()) .build(); return chain.proceed(newRequest); } }

如果遇到 401 需要自动刷新 Token，OkHttp 提供了Authenticator，它能拿到被拒绝的响应和重试机会。一个稳妥做法是：先用旧的 Token 发起请求，拿到 401 后去刷新 Token，刷新成功后再用新 Token 重试一次。这里要注意两点：刷新 Token 的请求本身不要也套进认证逻辑里，防止递归；加锁控制并发刷新，别让几十个请求同时去刷新 Token。

5.3 缓存策略：离线也能看上一份数据

OkHttp 的缓存默认只缓存 GET 请求，而且是否真正使用缓存由Cache-Control响应头控制。为了让效果更可控，可以手动配置。

File cacheDir = new File(context.getCacheDir(), "http_cache"); Cache cache = new Cache(cacheDir, 50 * 1024 * 1024); OkHttpClient client = new OkHttpClient.Builder() .cache(cache) .addInterceptor(new CacheInterceptor()) .build();

在拦截器里统一设置：

public Response intercept(Chain chain) throws IOException { Request request = chain.request(); if (!isNetworkAvailable()) { request = request.newBuilder() .header("Cache-Control", "only-if-cached, max-stale=" + 60 * 60 * 24) .build(); } return chain.proceed(request); }

这样在无网络环境下，客户端能读取一天之内的缓存。给离线页面兜底，体验提升非常明显。

5.4 超时与重试

Retrofit 本身没有超时参数，超时设置都走 OkHttpClient：

OkHttpClient client = new OkHttpClient.Builder() .connectTimeout(10, TimeUnit.SECONDS) .readTimeout(15, TimeUnit.SECONDS) .writeTimeout(15, TimeUnit.SECONDS) .build();

重试要注意幂等性。GET 请求重试相对安全，POST 请求如果后端没有做幂等，盲目重试可能造成重复下单、重复扣费等事故。比较稳妥的做法是在拦截器里判断请求类型和业务场景，只对可重试的请求重试，并且设置最大重试次数。

public Response intercept(Chain chain) throws IOException { Request request = chain.request(); int tryCount = 0; while (tryCount < MAX_RETRY) { try { return chain.proceed(request); } catch (IOException e) { if (!"GET".equals(request.method())) break; tryCount++; } } throw new IOException("retry exhausted"); }

重试次数不要设太高，三次以内就够了，不然网络抖动激烈时，整条链路会被拖垮。

6. 实战中的高频坑与排查链路：从baseUrl斜杠到泛型Type丢失

6.1 baseUrl 必须以 / 结尾

这是 Retrofit 最经典的报错之一：IllegalArgumentException: baseUrl must end in /。原因很好理解：Retrofit 要先把 baseUrl 解析成HttpUrl，再和服务接口里的相对路径拼接。如果 baseUrl 写成https://api.example.com/api，相对路径users拼出来会变成https://api.example.com/users，丢掉了api前缀。

正确写法：

new Retrofit.Builder() .baseUrl("https://api.example.com/api/") .build();

相对路径部分不要以/开头，否则会重置路径。@GET("users")和@GET("/users")最终拼出来的 url 是不同的，前者是https://api.example.com/api/users，后者会变成https://api.example.com/users。这是很多团队在联调时才发现问题的原因。

6.2 泛型 Type 丢失：小心你的自定义转换器

Retrofit 本身对接口方法声明里的泛型类型处理得很好，Call<List<User>>里的List<User>是通过方法的泛型签名拿到的，不会丢。真正容易丢泛型的地方，是你在业务代码里“手搓”转换的时候。

比如你从ResponseBody里取出字符串，然后调用Gson().fromJson(json, data.getClass())。data.getClass()对泛型类Data<T>来说，运行时只能拿到裸类型，T会被当成Object处理，字段根本不是你以为的类型。解决办法是显式用TypeToken：

Type type = new TypeToken<Data<User>>() {}.getType(); User user = new Gson().fromJson(json, type);

另外一个和 Retrofit 搭配常见的坑是：接口返回类型声明成了Call或Call<ResponseBody>，但你想直接得到业务对象。这时如果没注册GsonConverterFactory，运行时会报“无法将 ResponseBody 转换为你想要的类型”。遇到这类错误，先回方法声明处检查返回类型到底声明了什么。

6.3 线程问题：回调到底在哪条线程，别被带偏

默认情况下，Call.enqueue的onResponse/onFailure回调会回到 Android 主线程，你可以在里面直接更新 UI。所以很多人形成一种印象“Retrofit 的请求是在后台，回调在主线程”。

这句话只对了一半。enqueue是异步的，请求确实在 OkHttp 的线程池里跑，但回调的线程是由Retrofit里的 callbackExecutor 决定的。Android 平台默认用主线程 Handler 把回调派发回主线程。如果你在某个平台没有注入主线程执行器，回调查看文档时需要留意环境差异化。

协程版本略有不同：挂起函数返回时，恢复上下文取决于你调用的协程上下文，不再依赖 Retrofit 的主线程派发。这时候少了一个“默认在主线程”的保障，更新 UI 前要自己确保切回主线程。我在项目里的习惯是：统一在 ViewModel 层用viewModelScope发起请求，协程库里通过withContext(Dispatchers.Main)切回，避免底层线程模型不一致导致的问题。

6.4 大文件上传下载进度怎么实现

Retrofit 本身不提供进度回调，但我们可以用 OkHttp 的拦截器或自定义 RequestBody / ResponseBody 来包装数据流。

上传进度：写一个CountingRequestBody，重写writeTo方法，在写入时把已写入字节数回调出去。下载进度更常见：自定义ResponseBody包装原始 body，用ForwardingSource统计读取字节数。

public class ProgressResponseBody extends ResponseBody { private final ResponseBody delegate; private final ProgressListener listener; private BufferedSource bufferedSource; public ProgressResponseBody(ResponseBody delegate, ProgressListener listener) { this.delegate = delegate; this.listener = listener; } @Override public long contentLength() { return delegate.contentLength(); } @Override public MediaType contentType() { return delegate.contentType(); } @Override public BufferedSource source() { if (bufferedSource == null) { bufferedSource = Okio.buffer(new ForwardingSource(delegate.source()) { long totalBytesRead = 0L; @Override public long read(Buffer sink, long byteCount) throws IOException { long bytesRead = super.read(sink, byteCount); totalBytesRead += bytesRead != -1 ? bytesRead : 0; listener.onProgress(totalBytesRead, delegate.contentLength()); return bytesRead; } }); } return bufferedSource; } }

注意大文件下载时不要在回调里频繁刷新 UI，做好节流，至少几百毫秒触发一次，否则界面会卡。

6.5 一次 URL 参数被篡改的完整排查链路

最后分享一个真实排查案例。当时有个搜索接口，用户输入类似C++这样的关键字时，后端始终返回 404。接口日志里能看到请求打到了https://api.example.com/search?keyword=C++，但从服务端视角收到的却像keyword=C，加号不见了。

排查链路是这样的：

1. 先抓包看实际发出的 URL，发现请求 URL 里的加号没有做编码，变成了普通加号。
2. 查 Retrofit 的默认行为，@Query应该是会做 URL 编码的，为什么这里没有？仔细看代码才发现，这个接口不是用@Query，而是在@Url里手动拼了个"keyword=" + input。
3. 手动拼接字符串时，加号没有转成%2B，而 URL 标准里加号在 query 中表示空格。后端解析器把C++解析成C 空间，自然找不到资源。

修复方案也很简单：不要手动拼 query，统一用@Query或@QueryMap让 Retrofit 负责编码。就算必须手动拼接完整 URL，也要先用HttpUrl转换或手动把特殊字符encode一下。

从这个案例得到的教训是：能用框架能力完成的拼接，绝不自己用字符串去做。很多藏在 URL 参数里的诡异 bug，都是手动拼字符串拼出来的。

我个人在项目里的习惯是把 Retrofit 的接口层统一命名成ApiService，然后所有请求都走这一个入口。接口声明、DTO、拦截器、Converter 各管一摊，维护起来特别省心。之前那个两百行 AsyncTask 的老项目，重构完网络层之后，网络相关的崩溃率降了不少，新同事接手看接口文件就能猜出请求结构。Retrofit 真正让人舒服的地方，不是少写了多少行代码，而是它把网络请求的边界划得清清楚楚，你只管声明，剩下的交给框架。