Retrofit入门指南：Android开发者的HTTP通信利器

关注

原创最新推荐文章于 2026-08-17 12:30:42 发布 1.3k 阅读 AI 写同款· GEO 优化 ›

使用retrofit来封装高效的http请求工具，吊打okhttp、httpClient等工具 Retrofit是Square公司开源的一款类型安全的HTTP客户端库，它通过简洁的接口定义将HTTP API转换为Java接口，极大地简化了网络请求的编写。本文将介绍如何使用Retrofit来构建一个高效、易用的HTTP请求工具，并通过一个完整的示例来展示其实现过程。http相关注解可参考官方文档：retrofit官方文档地址。Retrofit是适用于Android和Java且类型安全的HTTP客户端，其最大的特性的是支持通过接口的方式发起HTTP请求。而是使用最广泛的Java开发框架，但是。阅读详情

前言

在当今移动应用开发中，网络通信几乎是不可或缺的一部分。无论是获取远程数据、上传用户信息还是与后端API交互，都需要一个可靠高效的HTTP客户端。而在Android开发领域，Retrofit无疑是最受欢迎的选择之一！

作为Square公司开源的类型安全HTTP客户端，Retrofit不仅简化了网络请求的编写，还提供了强大的类型转换和请求适配功能。如果你还在使用传统的HttpURLConnection或者觉得OkHttp使用起来有些繁琐，那么Retrofit绝对值得你花时间学习（这将为你节省大量开发时间）！

今天就让我们一起深入了解Retrofit的基本用法和一些进阶技巧。无需任何网络通信基础，跟着本文一步步操作，你也能轻松掌握这个强大工具！

Retrofit是什么？

简单来说，Retrofit是一个RESTful的HTTP网络请求框架的封装。它基于OkHttp构建，使网络请求的实现更加简单、方便。

Retrofit的核心优势：

声明式API定义 - 只需定义接口，无需关心具体实现
类型安全 - 编译时就能发现潜在问题
支持同步/异步请求 - 灵活适应不同场景
可扩展性强 - 支持多种数据格式转换
与RxJava完美结合 - 处理复杂的异步操作

准备工作

在开始使用Retrofit之前，我们需要先在项目中添加相关依赖。打开你的app模块的build.gradle文件，添加以下依赖：

dependencies {
    // Retrofit核心库
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    
    // Gson转换器（用于JSON数据解析）
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
    
    // 可选：RxJava适配器
    implementation 'com.squareup.retrofit2:adapter-rxjava3:2.9.0'
}

别忘了在AndroidManifest.xml中添加网络权限：

<uses-permission android:name="android.permission.INTERNET" />

基础用法：四步上手Retrofit

第一步：创建API接口

Retrofit的核心理念是通过Java接口定义HTTP请求。假设我们要调用一个获取用户信息的API：

public interface UserApiService {
    @GET("users/{id}")
    Call<User> getUser(@Path("id") int userId);
}

这个简单的接口告诉Retrofit：

使用GET请求
请求路径是"users/{id}"，其中{id}是一个动态参数
返回的数据将被转换为User对象

第二步：创建数据模型

根据API返回的JSON结构，我们需要创建对应的Java类：

public class User {
    private int id;
    private String name;
    private String email;
    
    // 生成getter和setter方法（省略）
}

第三步：创建Retrofit实例

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.example.com/")  // 设置API的基础URL
    .addConverterFactory(GsonConverterFactory.create())  // 添加Gson转换器
    .build();
    
UserApiService apiService = retrofit.create(UserApiService.class);

这里我们配置了：

API的基础URL
使用Gson来转换JSON响应

第四步：发起请求

现在我们可以使用创建好的apiService发起网络请求：

// 创建调用对象
Call<User> call = apiService.getUser(1);

// 异步执行请求
call.enqueue(new Callback<User>() {
    @Override
    public void onResponse(Call<User> call, Response<User> response) {
        if (response.isSuccessful()) {
            User user = response.body();
            // 处理获取到的用户数据
            Log.d("Retrofit", "用户名: " + user.getName());
        } else {
            // 处理错误
            Log.e("Retrofit", "错误码: " + response.code());
        }
    }

    @Override
    public void onFailure(Call<User> call, Throwable t) {
        // 处理网络请求失败
        Log.e("Retrofit", "请求失败: " + t.getMessage());
    }
});

就是这么简单！四步就完成了一个完整的网络请求流程。不过Retrofit的强大远不止于此，接下来我们来看一些更实用的功能。

常用注解详解

Retrofit使用注解来配置HTTP请求的各个方面，这是它的一大特色。以下是一些常用的注解：

HTTP方法注解

@GET：GET请求
@POST：POST请求
@PUT：PUT请求
@DELETE：DELETE请求
@PATCH：PATCH请求
@HEAD：HEAD请求
@OPTIONS：OPTIONS请求

参数注解

@Path：URL路径中的参数，如users/{id}中的id
@Query：URL查询参数，如?page=1
@QueryMap：多个查询参数
@Body：请求体，通常用于POST/PUT请求
@Field：表单字段，与@FormUrlEncoded配合使用
@FieldMap：多个表单字段
@Header：添加请求头
@HeaderMap：添加多个请求头
@Part：多部分请求体，用于上传文件
@PartMap：多个部分

让我们看几个常见场景的例子：

带查询参数的GET请求

@GET("users")
Call<List<User>> getUsers(@Query("page") int page, @Query("sort") String sortBy);

// 调用方式
Call<List<User>> call = apiService.getUsers(1, "name");
// 最终请求: GET https://api.example.com/users?page=1&sort=name

发送表单数据的POST请求

@FormUrlEncoded
@POST("users/new")
Call<User> createUser(@Field("name") String name, @Field("email") String email);

// 调用方式
Call<User> call = apiService.createUser("John Doe", "john@example.com");

发送JSON数据的POST请求

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

// 调用方式
User newUser = new User();
newUser.setName("John Doe");
newUser.setEmail("john@example.com");
Call<User> call = apiService.createUser(newUser);

上传文件

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

// 调用方式
File file = new File(path);
RequestBody requestFile = RequestBody.create(MediaType.parse("multipart/form-data"), file);
MultipartBody.Part body = MultipartBody.Part.createFormData("file", file.getName(), requestFile);
RequestBody description = RequestBody.create(MediaType.parse("text/plain"), "文件描述");

Call<ResponseBody> call = apiService.uploadFile(description, body);

进阶用法

自定义请求头

有时我们需要为所有请求添加统一的请求头（如认证信息），可以通过OkHttp的Interceptor实现：

OkHttpClient client = new OkHttpClient.Builder()
    .addInterceptor(new Interceptor() {
        @Override
        public okhttp3.Response intercept(Chain chain) throws IOException {
            Request original = chain.request();
            
            // 添加请求头
            Request request = original.newBuilder()
                .header("Authorization", "Bearer YOUR_TOKEN_HERE")
                .header("Accept", "application/json")
                .method(original.method(), original.body())
                .build();
                
            return chain.proceed(request);
        }
    })
    .build();
    
Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .client(client)  // 使用自定义的OkHttpClient
    .addConverterFactory(GsonConverterFactory.create())
    .build();

处理复杂的嵌套JSON

有时API返回的JSON结构可能很复杂，或者我们只关心其中一部分数据。可以使用Gson的注解来简化映射：

public class ApiResponse<T> {
    @SerializedName("status")
    private String status;
    
    @SerializedName("code")
    private int code;
    
    @SerializedName("data")
    private T data;
    
    // getter和setter方法
}

public interface ApiService {
    @GET("users/{id}")
    Call<ApiResponse<User>> getUser(@Path("id") int userId);
}

与RxJava结合使用

Retrofit与RxJava的结合使用可以更优雅地处理异步操作和复杂的数据流：

// 添加RxJava适配器
Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.example.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .addCallAdapterFactory(RxJava3CallAdapterFactory.create())
    .build();

// 修改接口返回类型
public interface UserApiService {
    @GET("users/{id}")
    Observable<User> getUser(@Path("id") int userId);
}

// 使用RxJava处理请求
apiService.getUser(1)
    .subscribeOn(Schedulers.io())
    .observeOn(AndroidSchedulers.mainThread())
    .subscribe(
        user -> {
            // 处理成功响应
            textView.setText(user.getName());
        },
        error -> {
            // 处理错误
            Toast.makeText(context, "加载失败: " + error.getMessage(), Toast.LENGTH_SHORT).show();
        }
    );

错误处理

在实际应用中，适当的错误处理非常重要。可以统一处理常见的HTTP错误和网络问题：

call.enqueue(new Callback<User>() {
    @Override
    public void onResponse(Call<User> call, Response<User> response) {
        if (response.isSuccessful()) {
            // 处理200-299范围的响应
            User user = response.body();
            // 处理数据...
        } else {
            // 处理错误响应
            try {
                // 尝试解析错误消息
                JSONObject errorBody = new JSONObject(response.errorBody().string());
                String errorMessage = errorBody.getString("message");
                Toast.makeText(context, errorMessage, Toast.LENGTH_SHORT).show();
            } catch (Exception e) {
                // 无法解析错误消息，使用HTTP状态码
                Toast.makeText(context, "错误: " + response.code(), Toast.LENGTH_SHORT).show();
            }
            
            // 根据状态码做不同处理
            switch (response.code()) {
                case 401:
                    // 未授权，可能需要重新登录
                    startLoginActivity();
                    break;
                case 404:
                    // 资源不存在
                    showNotFoundMessage();
                    break;
                // 其他错误码...
            }
        }
    }

    @Override
    public void onFailure(Call<User> call, Throwable t) {
        // 网络错误
        if (t instanceof SocketTimeoutException) {
            Toast.makeText(context, "连接超时，请检查网络", Toast.LENGTH_SHORT).show();
        } else if (t instanceof UnknownHostException) {
            Toast.makeText(context, "无法连接到服务器", Toast.LENGTH_SHORT).show();
        } else {
            Toast.makeText(context, "网络错误: " + t.getMessage(), Toast.LENGTH_SHORT).show();
        }
    }
});

实战案例：构建完整的网络层

最后，让我们通过一个完整的例子来展示如何在实际项目中使用Retrofit构建网络层：

1. 创建API服务接口

public interface GithubApiService {
    @GET("users/{username}")
    Call<GithubUser> getUser(@Path("username") String username);
    
    @GET("users/{username}/repos")
    Call<List<Repository>> getRepositories(@Path("username") String username);
    
    @GET("search/repositories")
    Call<SearchResult> searchRepositories(@Query("q") String query);
}

2. 创建模型类

public class GithubUser {
    private String login;
    private long id;
    private String avatar_url;
    private String name;
    private String bio;
    private int public_repos;
    private int followers;
    private int following;
    
    // getter和setter
}

public class Repository {
    private long id;
    private String name;
    private String description;
    private String html_url;
    private int stargazers_count;
    private int forks_count;
    
    // getter和setter
}

public class SearchResult {
    private int total_count;
    private List<Repository> items;
    
    // getter和setter
}

3. 创建API客户端类

public class GithubApiClient {
    private static final String BASE_URL = "https://api.github.com/";
    private static GithubApiClient instance;
    private GithubApiService apiService;
    
    private GithubApiClient() {
        // 创建OkHttpClient并添加拦截器
        OkHttpClient client = new OkHttpClient.Builder()
            .addInterceptor(new HttpLoggingInterceptor().setLevel(HttpLoggingInterceptor.Level.BODY))
            .connectTimeout(15, TimeUnit.SECONDS)
            .readTimeout(15, TimeUnit.SECONDS)
            .build();
            
        // 创建Retrofit实例
        Retrofit retrofit = new Retrofit.Builder()
            .baseUrl(BASE_URL)
            .client(client)
            .addConverterFactory(GsonConverterFactory.create())
            .build();
            
        // 创建API服务
        apiService = retrofit.create(GithubApiService.class);
    }
    
    // 单例模式
    public static synchronized GithubApiClient getInstance() {
        if (instance == null) {
            instance = new GithubApiClient();
        }
        return instance;
    }
    
    // API方法
    public void getUser(String username, Callback<GithubUser> callback) {
        apiService.getUser(username).enqueue(callback);
    }
    
    public void getRepositories(String username, Callback<List<Repository>> callback) {
        apiService.getRepositories(username).enqueue(callback);
    }
    
    public void searchRepositories(String query, Callback<SearchResult> callback) {
        apiService.searchRepositories(query).enqueue(callback);
    }
}

4. 在Activity中使用

public class MainActivity extends AppCompatActivity {
    private TextView userInfoTextView;
    private RecyclerView repositoriesRecyclerView;
    private RepositoryAdapter adapter;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        
        userInfoTextView = findViewById(R.id.user_info);
        repositoriesRecyclerView = findViewById(R.id.repositories_list);
        repositoriesRecyclerView.setLayoutManager(new LinearLayoutManager(this));
        adapter = new RepositoryAdapter();
        repositoriesRecyclerView.setAdapter(adapter);
        
        // 加载用户信息
        loadUserInfo("octocat");
    }
    
    private void loadUserInfo(String username) {
        // 显示加载中状态
        showLoading(true);
        
        // 获取用户信息
        GithubApiClient.getInstance().getUser(username, new Callback<GithubUser>() {
            @Override
            public void onResponse(Call<GithubUser> call, Response<GithubUser> response) {
                if (response.isSuccessful()) {
                    GithubUser user = response.body();
                    userInfoTextView.setText(
                        "用户名: " + user.getName() + "\n" +
                        "简介: " + user.getBio() + "\n" +
                        "仓库数: " + user.getPublic_repos() + "\n" +
                        "粉丝数: " + user.getFollowers()
                    );
                    
                    // 加载仓库列表
                    loadRepositories(username);
                } else {
                    showError("用户信息加载失败: " + response.code());
                    showLoading(false);
                }
            }

            @Override
            public void onFailure(Call<GithubUser> call, Throwable t) {
                showError("网络错误: " + t.getMessage());
                showLoading(false);
            }
        });
    }
    
    private void loadRepositories(String username) {
        GithubApiClient.getInstance().getRepositories(username, new Callback<List<Repository>>() {
            @Override
            public void onResponse(Call<List<Repository>> call, Response<List<Repository>> response) {
                showLoading(false);
                if (response.isSuccessful()) {
                    List<Repository> repositories = response.body();
                    adapter.setRepositories(repositories);
                } else {
                    showError("仓库列表加载失败: " + response.code());
                }
            }

            @Override
            public void onFailure(Call<List<Repository>> call, Throwable t) {
                showLoading(false);
                showError("网络错误: " + t.getMessage());
            }
        });
    }
    
    private void showLoading(boolean isLoading) {
        // 显示或隐藏加载进度条
    }
    
    private void showError(String message) {
        Toast.makeText(this, message, Toast.LENGTH_SHORT).show();
    }
}