开发环境搭建：Android项目中集成Retrofit依赖与网络权限配置

聊聊环境搭建这件事

我刚开始用Retrofit那会，被各种依赖版本冲突搞得焦头烂额。其实后来发现，只要理清楚几个关键配置项，五分钟就能搞定。这章咱们就把环境搭建这件事拆开揉碎了讲。

第一步：添加Gradle依赖

Retrofit本身是个轻量级的HTTP客户端，但它依赖OkHttp做底层网络请求。你需要在build.gradle（模块级别）里做三件事：

• 添加Retrofit核心库
• 添加转换器（Converter）——用来把JSON/XML转成Java对象
• 添加OkHttp日志拦截器（方便调试，我个人习惯加上）

我直接给你们看一个典型配置。别小看这几行，版本号选错能让你卡一整天。

dependencies {
    // Retrofit 核心库
    implementation 'com.squareup.retrofit2:retrofit:2.9.0'
    
    // Gson 转换器 —— 把 JSON 自动转成数据类
    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'
    
    // OkHttp 日志拦截器（调试时非常有用）
    implementation 'com.squareup.okhttp3:logging-interceptor:4.9.3'
}

第二步：网络权限与网络安全配置

Android 项目默认不允许在主线程做网络请求（这其实是 OkHttp 的规则）。但权限是另一个独立的问题——你必须先在 AndroidManifest.xml 中声明网络权限。

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

为什么需要 ACCESS_NETWORK_STATE？因为有时需要检查网络是否可用，避免无意义的请求。嗯，这里要注意：从 Android 9（API 28）开始，系统默认禁止明文 HTTP 请求。如果你测试用的是 HTTP 接口，必须配网络安全配置。

<application
    android:networkSecurityConfig="@xml/network_security_config"
    ... >

// res/xml/network_security_config.xml
<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true">
        <trust-anchors>
            <certificates src="system" />
        </trust-anchors>
    </base-config>
</network-security-config>

第三步：初始化 OkHttpClient 和 Retrofit

通常我会创建一个单例工具类来管理 Retrofit 实例。这样做的好处是整个应用只维护一个实例，节省资源。

public class RetrofitClient {
    private static final String BASE_URL = "https://api.example.com/";
    private static Retrofit retrofit = null;

    public static Retrofit getClient() {
        if (retrofit == null) {
            // 配置日志拦截器
            HttpLoggingInterceptor logging = new HttpLoggingInterceptor();
            logging.setLevel(HttpLoggingInterceptor.Level.BODY);

            OkHttpClient client = new OkHttpClient.Builder()
                    .addInterceptor(logging)
                    .connectTimeout(30, TimeUnit.SECONDS)
                    .readTimeout(30, TimeUnit.SECONDS)
                    .build();

            retrofit = new Retrofit.Builder()
                    .baseUrl(BASE_URL)
                    .client(client)
                    .addConverterFactory(GsonConverterFactory.create())
                    .build();
        }
        return retrofit;
    }
}

代码里我设了 30 秒超时，这个值你可以根据实际网络情况调。我在一个弱网环境下踩过坑——默认超时是 10 秒，结果用户总说请求失败，后来改到 45 秒才好。

核心流程一览

看看下面这张图，你就能把三步走通的东西串起来了：

常见问题排查表

为什么这样配？背后的逻辑

说白了，Retrofit 只是帮你把网络请求封装成 Java 接口调用。真正干活的是 OkHttp。你想想看，如果不配日志拦截器，出错了连请求参数和返回数据都看不到，那调试得多痛苦。我早期一个项目就是忘了加日志，查了一个下午才发现服务器返回了 500 但客户端没处理。

还有一个容易被忽略的点：baseUrl 的结尾必须带斜杠 /。这是 Retrofit 的硬性要求，否则启动就 crash。我见过不止一个新手问为什么一运行就闪退，其实就是少了那一个 /。