📚 课程目录第1章 Retrofit简介

1. Retrofit简介：作用、特点、基本用法

做 Android 开发，网络请求几乎是每天都在打交道的事儿。我记得刚入行那会儿，大家都在用 HttpURLConnection、Volley，后来 Retrofit 出现后，整个社区一下就风靡了。说实话，我第一次用 Retrofit 的感受就是：「原来网络请求可以这么优雅？」今天我们就来聊聊 Retrofit 是什么、它解决了什么问题，以及怎么把它用起来。

Retrofit 的核心作用

Retrofit 是一个类型安全的 HTTP 客户端，专门为 Android 和 Java 设计。它的本质其实是 OkHttp 的上层封装——你定义好接口和方法注解，Retrofit 就能自动帮你把 Java 方法调用转换成真实的网络请求，并把返回的 JSON/XML 等数据反序列化成 Java 对象。

说白了，它帮你省掉了以下工作：

手动拼接 URL 和请求参数
处理 HTTP 状态码和异常
手动解析响应体（配合 Gson/Moshi）
切换线程（配合 RxJava/协程）

它的核心思想就是「注解驱动 + 接口约定」。你只需要定义好接口，Retrofit 会通过动态代理生成具体的实现类。

Retrofit 的特点

我在项目中对比过多种网络库，Retrofit 能成为事实标准，离不开这几个特点：

特点	解释
类型安全	编译期就能检查 URL、参数、返回值是否匹配，运行时不会因为拼写错误而崩溃
注解驱动	@GET、@POST、@Path、@Query 等注解清晰描述请求意图，代码即文档
插件化架构	Converter 负责序列化/反序列化（Gson、Moshi、Kotlin Serialization），CallAdapter 负责异步模型（RxJava、协程 Future）
与 OkHttp 深度集成	底层完全依赖 OkHttp，拦截器、缓存、连接池等高级功能直接可用
轻量小巧	核心包不到 200KB，编译期无侵入

基本用法：三步走

1. 添加依赖

在 build.gradle 里加上：

dependencies {
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
}

2. 定义接口

用注解声明 API 端点：

public interface GitHubService {
    @GET("users/{user}/repos")
    Call<List<Repo>> listRepos(@Path("user") String user);
}

3. 创建 Retrofit 实例并调用

// 构建 Retrofit 对象
Retrofit retrofit = new Retrofit.Builder()
        .baseUrl("https://api.github.com/")
        .addConverterFactory(GsonConverterFactory.create())
        .build();

// 生成接口实现
GitHubService service = retrofit.create(GitHubService.class);

// 发起请求（同步示例，实际项目推荐异步）
Call<List<Repo>> call = service.listRepos("octocat");
List<Repo> repos = call.execute().body();

我个人习惯把 baseUrl 的结尾斜杠写死，比如 https://api.github.com/，然后在 @GET 里用相对路径。这样避免出现双斜杠或缺少斜杠的问题。

我踩过的几个坑

@Path 里的值忘记用花括号包裹：我之前写 @GET("users/{user}/repos") 时，少写了大括号，结果 API 一直 404。记住：{user} 是占位符，@Path("user") 必须匹配花括号内的名字。
baseUrl 结尾没加斜杠：如果 baseUrl 是 https://api.github.com（没斜杠），@GET 里是 /users/octocat，那么拼接后变成两个斜杠。Retrofit 2.0 之后会自动处理，但最佳实践还是统一加斜杠。
同步请求在主线程：call.execute() 是同步阻塞的，安卓主线程调用会抛 NetworkOnMainThreadException。我建议刚入门的朋友直接使用 call.enqueue() 做异步回调，或者配合 Kotlin 协程的 suspend 函数。

一句话总结：Retrofit 的核心价值在于「用接口和注解定义网络请求，剩下的交给框架」。它不解决网络协议本身，但把开发者的心智负担降到了最低。

好了，Retrofit 的基本概念和用法就这些。接下来你会看到我们怎么利用它来搭建 Mock 回放测试框架——说白了，就是让 Retrofit 在测试环境下「造假数据」，这样不依赖真实服务器也能跑自动化测试。嗯，这其实就是本课程最核心的实战内容。