Retrofit 介绍 | Baeldung中文网

1. 概述

Retrofit 是由 Square 公司（同时开发了 Dagger 和 Okhttp）打造的类型安全 HTTP 客户端，适用于 Android 和 Java 开发。

本文将深入讲解 Retrofit 的核心功能，重点介绍：

✅ 同步/异步 API 使用
✅ 认证机制集成
✅ 日志功能配置
✅ 最佳建模实践

2. 环境搭建

首先添加 Retrofit 和 Gson 转换器依赖：

<dependency>
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>retrofit</artifactId>
    <version>2.3.0</version>
</dependency>  
<dependency>  
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>converter-gson</artifactId>
    <version>2.3.0</version>
</dependency>

💡 最新版本请查阅 Maven Central 仓库

3. API 建模

Retrofit 通过 Java 接口描述 REST 接口，简洁直观。以 GitHub 用户 API 为例：

{
  login: "mojombo",
  id: 1,
  url: "https://api.github.com/users/mojombo",
  ...
}

3.1 数据模型定义

public class User {
    private String login;
    private long id;
    private String url;
    // ...

    // 标准 getter/setter
}

⚠️ 关键特性：

只映射需要的字段，多余字段自动忽略
模型新增字段不影响解析

3.2 接口声明

public interface UserService {

    @GET("/users")
    public Call<List<User>> getUsers(
      @Query("per_page") int per_page, 
      @Query("page") int page);

    @GET("/users/{username}")
    public Call<User> getUser(@Path("username") String username);
}

注解解析：

@GET：指定 HTTP 方法和资源路径
/ 开头表示绝对路径（如 https://api.github.com/users）
@Query：可选查询参数，传 null 时自动忽略
@Path：路径参数替换

4. 同步/异步 API

4.1 构建 Retrofit 实例

OkHttpClient.Builder httpClient = new OkHttpClient.Builder();
Retrofit retrofit = new Retrofit.Builder()
  .baseUrl("https://api.github.com/")
  .addConverterFactory(GsonConverterFactory.create())
  .client(httpClient.build())
  .build();

核心组件说明： | 组件 | 作用 | |------|------| | baseUrl | 所有接口的基准 URL | | ConverterFactory | 数据序列化/反序列化（支持 JSON/XML/Protobuf） | | OkHttpClient | 底层 HTTP 客户端 |

4.2 同步调用

UserService service = retrofit.create(UserService.class);
Call<User> callSync = service.getUser("eugenp");

try {
    Response<User> response = callSync.execute();
    User user = response.body();
} catch (Exception ex) { ... }

⚠️ 注意：

execute() 会阻塞当前线程
适用于后台任务或测试场景

4.3 异步调用

UserService service = retrofit.create(UserService.class);
Call<User> callAsync = service.getUser("eugenp");

callAsync.enqueue(new Callback<User>() {
    @Override
    public void onResponse(Call<User> call, Response<User> response) {
        User user = response.body();
    }

    @Override
    public void onFailure(Call<User> call, Throwable throwable) {
        System.out.println(throwable);
    }
});

✅ 优势：

在独立线程执行
通过回调处理结果
适合 UI 线程调用

5. 封装 ServiceGenerator 类

避免重复构建 Retrofit，创建可复用的生成器：

public class GitHubServiceGenerator {

    private static final String BASE_URL = "https://api.github.com/";

    private static Retrofit.Builder builder
      = new Retrofit.Builder()
        .baseUrl(BASE_URL)
        .addConverterFactory(GsonConverterFactory.create());

    private static Retrofit retrofit = builder.build();

    private static OkHttpClient.Builder httpClient
      = new OkHttpClient.Builder();

    public static <S> S createService(Class<S> serviceClass) {
        return retrofit.create(serviceClass);
    }
}

使用示例：

UserService service 
  = GitHubServiceGenerator.createService(UserService.class);

6. 认证机制

扩展 ServiceGenerator 支持 JWT 认证：

public static <S> S createService(Class<S> serviceClass, final String token ) {
   if ( token != null ) {
       httpClient.interceptors().clear();
       httpClient.addInterceptor( chain -> {
           Request original = chain.request();
           Request request = original.newBuilder()
             .header("Authorization", token)
             .build();
           return chain.proceed(request);
       });
       builder.client(httpClient.build());
       retrofit = builder.build();
   }
   return retrofit.create(serviceClass);
}

🔑 关键点：

通过 OkHttp 拦截器添加认证头
支持 OAuth/Basic 等多种认证方式
动态重建 Retrofit 实例

7. 日志功能

添加调试日志支持：

7.1 依赖引入

<dependency>
    <groupId>com.squareup.okhttp3</groupId>
    <artifactId>logging-interceptor</artifactId>
    <version>5.0.0-alpha.12</version>
</dependency>

7.2 完整实现

public class GitHubServiceGenerator {

    private static final String BASE_URL = "https://api.github.com/";

    private static Retrofit.Builder builder
      = new Retrofit.Builder()
        .baseUrl(BASE_URL)
        .addConverterFactory(GsonConverterFactory.create());

    private static Retrofit retrofit = builder.build();

    private static OkHttpClient.Builder httpClient
      = new OkHttpClient.Builder();

    private static HttpLoggingInterceptor logging
      = new HttpLoggingInterceptor()
        .setLevel(HttpLoggingInterceptor.Level.BASIC);

    public static <S> S createService(Class<S> serviceClass) {
        if (!httpClient.interceptors().contains(logging)) {
            httpClient.addInterceptor(logging);
            builder.client(httpClient.build());
            retrofit = builder.build();
        }
        return retrofit.create(serviceClass);
    }

    public static <S> S createService(Class<S> serviceClass, final String token) {
        if (token != null) {
            httpClient.interceptors().clear();
            httpClient.addInterceptor( chain -> {
                Request original = chain.request();
                Request.Builder builder1 = original.newBuilder()
                  .header("Authorization", token);
                Request request = builder1.build();
                return chain.proceed(request);
            });
            builder.client(httpClient.build());
            retrofit = builder.build();
        }
        return retrofit.create(serviceClass);
    }
}

📝 日志级别说明：

BASIC：记录请求方法/URL/状态码/耗时
HEADERS：增加请求/响应头信息
BODY：完整请求/响应体（生产环境慎用）

8. 总结

本文系统讲解了 Retrofit 的核心能力：

✅ 通过注解声明式定义 REST 接口
✅ 同步/异步调用方式
✅ 认证拦截器实现
✅ 日志调试集成

💡 进阶建议：结合 RxJava 实现响应式编程（参考 Retrofit+RxJava 教程）

完整示例代码见 GitHub 仓库

Persistence

REST

Security