【Android 进阶】Retrofit2 目前最优雅的网络请求框架

最新推荐文章于 2026-07-25 07:35:28 发布

原创最新推荐文章于 2026-07-25 07:35:28 发布 · 9.3k 阅读

25 ·

本内容遵循CC 4.0 BY-SA版权协议

收录于

Android 之旅

本文介绍了Retrofit2，一个由Square开发的Android类型安全的REST网络请求框架。通过学习，我们可以利用Retrofit进行网络认证、API请求，并通过OkHttp发送网络请求。文中详细讲解了Retrofit的简单使用、REST概念、API接口的注解方法、URL操作、请求体、同步与异步调用、配置转换器等核心功能，并提供了相关依赖和混淆规则的配置指导。

身为 Geek 的我们，面对不断更新换代的技术是不是有点感到迷茫呢？其实只要掌握正确的学习方法，新的技术也就不畏惧了。
福利来了
推荐一位大牛【人称：面哥】呕心沥血的一篇经验分享：
程序员之路-学习经验总结分享
正是面哥的鞭策，我决定开始看英文的技术文档，学习新技术也是直接看官网的技术文档，本篇文章就是我在 Retrofit2 的官网看完英文文档 Retrofit 以及参考多篇博文之后总结出来的。

欢迎关注我的微信公众号
不只是原创技术文章，更多的是对生活的思考总结
这里写图片描述

Retrofit

Retrofit
是一个 Square 开发的类型安全的 REST 安卓客户端请求库。这个库为网络认证、API 请求以及用 OkHttp 发送网络请求提供了强大的框架。
Retrofit 把 REST API 返回的数据转化为 Java 对象，就像 ORM 框架那样，把数据库内的存储的数据转化为相应的 Java
bean对象。那么我们知道 Retrofit 是一个类型安全的网络框架，而且它是使用 REST API 的.

REST ：

Resources Representational State Transfer
资源表现层状态转化每一个 URI 代表一种资源
客户端和服务器之间，传递这种资源的某种表现层(“资源”具体呈现出来的形式，比如.txt，.png，.jpg)
客户端通过四个 HTTP 动词（GET 用来获取资源，POST 用来新建或更新资源，PUT 用来更新资源，DELETE 用来删除资源）对服务器端资源进行操作，实现”表现层状态转化”

Retrofit 的简单使用

这里使用官方的例子介绍，也是以github的api做测试

第零步：

添加依赖：

//okHttp
    compile 'com.squareup.okhttp3:okhttp:3.2.0'
//retrofit
    compile 'com.squareup.retrofit2:retrofit:2.0.2'
    compile 'com.squareup.retrofit2:converter-gson:2.0.2'
    compile 'com.squareup.okhttp3:logging-interceptor:3.2.0'

准备 api 接口：

https://api.github.com/users/wu-leaf/repos

需要封装的 javabean 类

其中我抽取出用来测试的属性如下4个：

public class Repo {
    private int id;
    private String name;
    private String full_name;
    private String fork;

    //get\set方法

第一步：

改造你的 HTTP API 变成一个 Java 接口。

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

第二步：

Retrofit 生成一个 GitHubService 接口的实现

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .build();

GitHubService service = retrofit.create(GitHubService.class);

来自创建的 GitHubService 的每个调用都可以向远程Web服务器发出同步或异步 HTTP 请求。

Call<List<Repo>> repos = service.listRepos("wu-leaf");

第三步：

异步调用

repos.enqueue(new Callback<List<Repo>>() {
            @Override
            public void onResponse(Call<List<Repo>> call, Response<List<Repo>> response) {
                Log.d("TAG",response.body().toString());
                response_tv.setText(response.body().toString());
            }

            @Override
            public void onFailure(Call<List<Repo>> call, Throwable t) {
                 if (call.isCanceled()){
                     Log.d("TAG",t.toString());
                 }else{
                     Log.e("TAG",t.toString());
                 }
            }
        });

同步调用：
当然不能在主线程调用

Call<Repo> clone = repos.clone();

    Response<Repo> response = clone.execute();
    Repobody = response.body();

这个例子是不是挺简单的，现在现在正式了解下常用 api 吧

常用 API 介绍

接口方法及其参数的注释指示如何处理请求。

请求方法

每个方法必须具有提供请求方法和相对 URL 的 HTTP 注释。有五个内置注释：GET，POST，PUT，DELETE和HEAD。资源的相对 URL 在注释中指定。

@GET("users/list")

您还可以在 URL 中指定查询参数。

@GET("users/list?sort=desc")

URL 相关操作

可以使用替换块（占位符）和方法上的参数动态更新请求 URL。替换块是由{and}包围母数字字符串。相应的参数必须使用相同的字符串用 @Path 注释。

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId);

也可以添加查询参数。

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort);

对于复杂的查询参数组合，可以使用 Map。

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options);

请求体

可以指定一个对象用作带有 @Body 注释的 HTTP 请求体。

@POST("users/new")
Call<User> createUser(@Body User user);

该对象也将使用 Retrofit 实例上指定的转换器进行转换。如果没有添加转换器，则只能使用 RequestBody。

提交表单和多部分数据

方法也可以声明为发送提交表单和多部分数据。

当方法上存在 @FormUrlEncoded 时，将发送表单编码的数据。每个键值对都使用包含名称的@Field和提供值的对象进行注释。

@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);

多部分请求时使用 @Multipart 存在的方法。部分使用 @Part 注释声明。

@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);

多部分使用 Retrofit 的转换器，或者它们可以实现 RequestBody 来处理自己的序列化。

请求头操作

您可以使用 @Headers 注释为方法设置静态头。

@Headers("Cache-Control: max-age=640000")
@GET("widget/list")
Call<List<Widget>> widgetList();

@Headers({
    "Accept: application/vnd.github.v3.full+json",
    "User-Agent: Retrofit-Sample-App"
})
@GET("users/{username}")
Call<User> getUser(@Path("username") String username);

请注意，请求头不会相互覆盖。具有相同名称的所有请求头将包含在请求中。

请求头可以使用 @Header 注释动态更新。必须向 @Header 提供相应的参数。如果值为 null，则将省略请求头。否则，toString 将被调用的值，并使用结果。

@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)

需要添加到每个请求的标头可以使用 OkHttp 拦截器指定。

同步 vs 异步

Call 实例可以同步或异步执行。每个实例只能使用一次，但调用 clone（）将创建一个可以使用的新实例。

在 Android 上，回调将在主线程上执行。在 JVM 上，回调将发生在执行 HTTP 请求的同一线程上。

Retrofit 配置

Retrofit 是将 API 接口转换为可调用对象的类。默认情况下，Retrofit 将为您的平台提供正常默认值，但它允许自定义。

转换器：

默认情况下，Retrofit 只能将 HTTP 主体反序列化为 OkHttp 的 ResponseBody 类型，并且它只能接受 @Body 的 RequestBody 类型。

可以添加转换器以支持其他类型。六个同级模块适应流行的序列化库为您方便使用。
- Gson: com.squareup.retrofit2:converter-gson
- Jackson: com.squareup.retrofit2:converter-jackson
- Moshi: com.squareup.retrofit2:converter-moshi
- Protobuf: com.squareup.retrofit2:converter-protobuf
- Wire: com.squareup.retrofit2:converter-wire
- Simple XML: com.squareup.retrofit2:converter-simplexml
- Scalars (primitives, boxed, and String):
- com.squareup.retrofit2:converter-scalars

下面是一个使用GsonConverterFactory类来生成GitHubService接口的实现的例子，它使用Gson进行反序列化。

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

GitHubService service = retrofit.create(GitHubService.class);

自定义转换器

如果您需要与使用 Retrofit 不支持开箱即用的内容格式（例如 YAML，txt，自定义格式）的API进行通信，或者希望使用其他库来实现现有格式，则可以轻松创建你自己的转换器。创建一个扩展 Converter.Factory 类的类，并在构建适配器时传递实例。

依赖方式：

MAVEN

<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>retrofit</artifactId>
  <version>2.2.0</version>
</dependency>

GRADLE

compile 'com.squareup.retrofit2:retrofit:2.0.2'
    compile 'com.squareup.retrofit2:converter-gson:2.0.2'

Retrofit 需要至少 Java 7 或 Android 2.3。

PROGUARD 混淆

如果在项目中使用 Proguard，请在配置中添加以下行：

# Platform calls Class.forName on types which do not exist on Android to determine platform.
-dontnote retrofit2.Platform
# Platform used when running on RoboVM on iOS. Will not be used at runtime.
-dontnote retrofit2.Platform$IOS$MainThreadExecutor
# Platform used when running on Java 8 VMs. Will not be used at runtime.
-dontwarn retrofit2.Platform$Java8
# Retain generic type information for use by reflection by converters and adapters.
-keepattributes Signature
# Retain declared checked exceptions for use by a Proxy instance.
-keepattributes Exceptions