原生移动开发 / 系统课时
网络权限与 Retrofit
网络权限与 Retrofit
本篇完成一个最小可验证的 Android 网络客户端:先声明联网权限并加入 Retrofit 依赖,再定义接口和数据模型,最后请求公开 HTTPS API,并通过 Logcat 确认状态码与解析结果。完成后即可把同样结构迁移到自己的后端接口。
学习目标
- 正确声明 Android 联网权限并添加 Retrofit 与 JSON 转换依赖
- 能用
Retrofit.Builder、接口注解和数据类创建类型安全的 API 客户端 - 能发起一次异步请求,并根据状态码、解析结果和失败回调定位问题
配置权限与依赖
Android 应用访问网络需要在 AndroidManifest.xml 声明 INTERNET 权限。它属于普通权限,不需要像相机或定位权限那样在运行时弹窗申请。示例使用 HTTPS,因此不需要放开明文 HTTP。
下面是片段示例,应把权限节点放在现有 <application> 节点之外,而不是用它替换整个 Manifest。
<uses-permission android:name="android.permission.INTERNET" />这段配置没有控制台输出。生效后的验证方法是运行实际网络请求;若遗漏权限,请求将无法正常建立网络连接。
在应用模块的 build.gradle.kts 中加入 Retrofit 与 Gson 转换器。下面同样是依赖配置片段,应合并到现有 dependencies 中。
dependencies {
implementation("com.squareup.retrofit2:retrofit:3.0.0")
implementation("com.squareup.retrofit2:converter-gson:3.0.0")
}Gradle 同步成功后,项目就可以使用 Retrofit 核心 API 与 Gson JSON 转换器。如果同步失败,应先检查仓库配置、网络和依赖坐标,再继续编写接口代码。
定义接口并创建客户端
Retrofit 把 HTTP 接口声明成 Kotlin 方法。@GET 描述请求方法和相对路径,@Path 把参数写入路径;GsonConverterFactory 负责把 JSON 转成 Post。baseUrl 必须以 / 结尾。
下面是片段示例,可以保存到项目中的独立 Kotlin 文件;包名按当前项目调整。
import retrofit2.Call
import retrofit2.Retrofit
import retrofit2.converter.gson.GsonConverterFactory
import retrofit2.http.GET
import retrofit2.http.Path
data class Post(
val userId: Int,
val id: Int,
val title: String,
val body: String
)
interface ApiService {
@GET("posts/{id}")
fun getPost(@Path("id") id: Int): Call<Post>
}
object ApiClient {
val service: ApiService = Retrofit.Builder()
.baseUrl("https://jsonplaceholder.typicode.com/")
.addConverterFactory(GsonConverterFactory.create())
.build()
.create(ApiService::class.java)
}这段客户端定义不会自行发送请求。验证方法是在 Activity、ViewModel 或 Repository 中调用 ApiClient.service.getPost(...),并检查回调结果。
发起请求并检查结果
以下示例可放入项目现有的 MainActivity.kt。它不修改界面,只把结果写入 Logcat,因此可以专注验证网络权限、Retrofit 配置和 JSON 解析是否正常。
import android.app.Activity
import android.os.Bundle
import android.util.Log
import retrofit2.Call
import retrofit2.Callback
import retrofit2.Response
class MainActivity : Activity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
ApiClient.service.getPost(1).enqueue(object : Callback<Post> {
override fun onResponse(call: Call<Post>, response: Response<Post>) {
if (response.isSuccessful) {
val post = response.body()
Log.d("NetworkDemo", "code=${response.code()}, id=${post?.id}")
} else {
Log.e("NetworkDemo", "HTTP ${response.code()}")
}
}
override fun onFailure(call: Call<Post>, t: Throwable) {
Log.e("NetworkDemo", "request failed: ${t.message}")
}
})
}
}预期结果是请求成功后出现类似日志;时间、进程号等前缀会因设备而不同。
<TIME> <PID> <ID> D NetworkDemo: code=200, id=1也可以在连接设备或模拟器后,只查看本示例的日志标签。
adb logcat -s NetworkDemo预期输出会持续显示 NetworkDemo 标签的日志,其中成功请求应包含下面这行核心内容。
D NetworkDemo: code=200, id=1处理最常见的失败
如果回调进入 onFailure,优先检查设备是否联网、Manifest 是否声明 INTERNET、域名是否可解析以及 HTTPS 证书是否有效。如果进入 onResponse 但 isSuccessful 为 false,说明服务器已经返回 HTTP 响应,此时应根据状态码和错误响应体继续排查。
如果应用访问的是 http:// 明文地址,现代 Android 的默认安全策略可能阻止请求。生产接口应优先升级为 HTTPS;只有确有受控测试需求时才单独配置 Network Security Config,而不是为了省事全局放开明文流量。
如果状态码成功但解析失败,应核对 JSON 字段类型与 Post 是否一致,并确认已经添加正确的 Converter。完成这条链路后,Retrofit 的职责就很清楚:接口注解描述请求,客户端负责发送,请求结果再由 Converter 转成 Kotlin 对象。