Android Studio 中的网络请求
一. 实现顶部应用栏的显示和影藏
val scrollBehavior = TopAppBarDefaults.enterAlwaysScrollBehavior()
该代码的作用是在Jepack Componse中用于让你的顶部应用栏在用户滚动页面时,能优雅的响应,自动隐藏和显示。简单来说这行代码实现了滚动时“始终显示/进入”的效果。
这句代码的作用是创建一个符合 Material Design 3 规范的 TopAppBarScrollBehavior 对象。这个对象定义了一套明确的规则:
-
向上滚动时:内容向上滚动,应用栏会立即收起/隐藏,为内容腾出更多屏幕空间
-
向下滚动时:内容向下滚动,应用栏会立即重新显示
-
工作原理:一个观察者模式
- 声明行为:
val scrollBehavior = TopAppBarDefaults.enterAlwaysScrollBehavior()这行代码就是创建了一个滚动行为的配置和监听器。 - **链接到应用栏:**将创建好的
scrollBehavior对象通过参数传递给TopAppBar组件。应用栏收到这个对象后,便知道要监听并响应滚动事件了。
CenterAlignedTopAppBar(
// ... 其他参数
scrollBehavior = scrollBehavior // 👈 关键:将行为连接到应用栏
)
- 连接到滚动内容:使用
Modifier.nestedScroll()修饰符,将scrollBehavior提供的nestedScrollConnection连接到可滚动的内容上(如LazyColumn或Column),形成嵌套滚动联动
LazyColumn(
modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection) // 👈 关键:连接到滚动内容
) {
// 列表内容...
}
这样,当内容滚动时,滚动事件就会被这个“连接器”捕获,并实时改变应用栏的偏移量,从而产生对应的UI变化。
TopAppBarDefaults有三种滚动模式, 可以根据具体的情况选择:

通常情况下,enterAlwaysScrollBehavior 因其灵敏的响应和节省屏幕空间的特性使用最广。
完整实例如下:
@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun MyScreen() {
// 1. 创建滚动行为实例
val scrollBehavior = TopAppBarDefaults.enterAlwaysScrollBehavior(
state = rememberTopAppBarState() // 保留滚动状态的推荐用法
)
// 2. 将行为传递给 Scaffold,并将 nestedScroll 连接到根布局
Scaffold(
modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
topBar = {
CenterAlignedTopAppBar(
title = { Text("我的应用标题") },
scrollBehavior = scrollBehavior // 3. 将行为传递给应用栏
// ... 其他参数
)
}
) { innerPadding ->
// 4. 内容区域,无需再显式添加 nestedScroll,Scaffold 会处理
LazyColumn(contentPadding = innerPadding) {
items(100) { index ->
Text("这是第 $index 项")
}
}
}
}
二. 网络服务
2.1. 网络服务简介
我将为网络服务创建一个层,与后端服务器进行通信并提取所需要的数据。你将使用Retrofit 三方库来完成任务。ViewModel与该数据进行通信,其余应用对此实现是透明的。

MarsViewModel负责发出网络调用以获取网络数据。在ViewModel中,你使用MutableState以在数据发生变更的时候更新UI。
2.2. 添加 Retrofit 依赖项
- 打开模块级 Gradle 文件 build.gradle.kts (Module :app)。
- 在 dependencies 部分,为 Retrofit 库添加以下几行代码:

这两个库协同工作。第一个依赖项用于Retrofit 2库本身,而第二个依赖项则用于Retrofit标量转换器。Retrofit2是Retrofit库的更新版本。此标量转换器允许Retrofit将JSON结果作为String返回。JSON是一种在客户端和服务器之间存储和传输数据的格式.
2.3. 链接互联网
首先我们需要实现网络请求的API
- 创建一个数据源:
MarsApiService类 - 使用基准网址和转换器工厂创建
Retrofit对象, 以转换字符串。 - 创建一个可说明
Retrofit如何与网络服务器通信的接口 - 创建一个
Retrofit服务并向应用的其余API公开实例
2.3.1. 创建请求API
package com.example.marsphotos.network
import retrofit2.Retrofit
import retrofit2.converter.scalars.ScalarsConverterFactory
import retrofit2.create
import retrofit2.http.GET
// 基础请求URL
private const val BASE_URL = "https://android-kotlin-fun-mars-server.appspot.com";
// 添加Retrofit的构建器,用于构建和创建Retrofit对象
// Retrofit 需要 Web 服务的基础 URI 和转换器工厂来构建 Web 服务 API。
// 转换器会告知 Retrofit 如何处理它从 Web 服务获取的数据。
// 在这种情况下,您需要 Retrofit 从 Web 服务提取 JSON 响应,并将该响应作为 String 返回。
// Retrofit 包含一个 ScalarsConverter,它支持字符串和其他基元类型。
private val retrofit = Retrofit.Builder()
.addConverterFactory(ScalarsConverterFactory.create())
.baseUrl(BASE_URL) // 设置基础请求地址
.build() // 使用build创建对象
interface MarsApiService {
// 从服务器获取响应字符串
// 使用 @GET 注解告知 Retrofit 这是 GET 请求,并为该 Web 服务方法指定端点。在这种情况下,端点为 photos
@GET("photos")
fun getPhotos(): String
}
// 对象申明 在Kotlin中声明一个单例对象,使用object关键字, 并提供一个该对象的全局访问点。
object MarsApi {
// 使用懒加载加载请求对象
// 在内存、速度和性能方面,对 Retrofit 对象调用 create() 函数的成本很高
// 这里只需要一个 Retrofit API 服务实例
val retrofitService: MarsApiService by lazy {
// Retrofit 的核心方法:传入一个接口的 Class 对象,动态生成该接口的代理实现,用于发起 HTTP 请求。
// MarsApiService::class.java 是 Kotlin 的类引用语法,等价于 Java 中的 MarsApiService.class
// 最终创建的 MarsApiService 对象内部会包含所有用 @GET、@POST 等注解定义的方法的具体实现。
retrofit.create(MarsApiService::class.java)
}
}
- 注解说明:

Retrofit的工作原理:
你写一个interface ApiService,Retrofit用动态代理自动生成实现类。
调用api.login(params)时,Retrofit读取POST("login")注解,自动构建HTTP请求发给服务器。
2.3.2. 在VM中调用请求API
ViewModelScope是为应用中的每个ViewModel定义的内置协程作用域。在此作用域内启动协程会在ViewModel被清除时自动取消。
您可以使用viewModelScope启动协程,并在后台发出Web服务请求。由于viewModelScope属于ViewModel,因此,即使应用发生配置更改,请求也会继续发出。
fun getMarsPhotos() {
// 启动ViewModel的内部协程
viewModelScope.launch {
// 调用api请求获取服务器结果
val listResult = MarsApi.retrofitService.getPhotos()
// 把服务器获取的结果,赋值给state
marsUiState = listResult
}
}
当我们实现后,开始运行项目,会报如下错误:

此错误消息表示可能缺少INTENT权限。
2.3.3. 添加权限和异常处理
2.3.3.1 Android权限
Android 上的权限旨在保护 Android 用户的隐私。Android 应用必须声明或请求访问敏感用户数据(如联系人、通话记录和某些系统功能,如相机或互联网)的权限。
应用需要INTENT权限才能访问网络。链接互联网会引发安全问题,因此我们默认应用没有链接互联网。您需要明确该应用需要访问互联网。系统将此声明视为正常权限。如需了解Android中其他权限, 参考Android中的权限
打开 manifests/AndroidManifest.xml。将下面这行代码添加到 标签的前面:
<uses-permission android:name="android.permission.INTERNET"/>

运行程序显示如下结果:

如果需要再项目中进项http的请求, 还需要配置另外一个参数:

2.3.3.2. 异常处理
代码中存在一个bug,当你将设备的网络关闭的时候,来模拟网络链接错误。

此错误表示应用链接并超时。在实际的应用中,该场景很常见,此错误无法解决,但是可以自行处理。
有些异常不是在编译期间发生的,而是在运行时期发生的,我们可以使用try-catch代码块在在运行时处理异常
try {
// some code that can cause an exception.
}
catch (e: SomeException) {
// handle the exception to avoid abrupt termination.
}
在 try 代码块中,您可以在预期会引发异常的位置添加代码。在您的应用中,这会是一次网络调用。在 catch 代码块中,您需要实现用于防止应用突然终止的代码。如果存在异常,系统会执行 catch 代码块,以从错误中恢复,而不是突然终止应用。
fun getMarsPhotos() {
// 启动ViewModel的内部协程
viewModelScope.launch {
try {
// 调用api请求获取服务器结果
val listResult = MarsApi.retrofitService.getPhotos()
// 把服务器获取的结果,赋值给state
marsUiState = listResult
} catch (e: IOException) {
}
}
}
2.3.4. 添加界面状态
在MarsViewModel类中,最近网络请求的状态marsUiState会保存为可变状态对象。但是这个类缺乏保存如下不同的状态功能:正在加载、成功和失败。
正在加载状态表示应用正在等待数据。成功状态表示已成功从 Web 服务检索到数据。错误状态表示存在网络或连接错误。
封装一个接口来表示这三种状态
sealed class NetworkResult<out T> {
data class Success<T>(val data: T) : NetworkResult<T>()
data class Error(val exception: Exception) : NetworkResult<Nothing>()
object Loading : NetworkResult<Nothing>()
}
然后MarsViewModel中要做如下更改:
class MarsViewModel : ViewModel() {
/** The mutable State that stores the status of the most recent request */
var marsUiState: MarsUiState by mutableStateOf(MarsUiState.Loading)
private set
init {
getMarsPhotos()
}
fun getMarsPhotos() {
// 启动ViewModel的内部协程
viewModelScope.launch {
try {
// 调用api请求获取服务器结果
val listResult = MarsApi.retrofitService.getPhotos()
// 把服务器获取的结果,赋值给state
marsUiState = MarsUiState.Success(listResult)
} catch (e: IOException) {
marsUiState = MarsUiState.Error
}
}
}
}
UI文件也需要做如下更改:
@Composable
fun HomeScreen(
marsUiState: MarsUiState,
modifier: Modifier = Modifier,
contentPadding: PaddingValues = PaddingValues(0.dp),
) {
when (marsUiState) {
is MarsUiState.Loading -> LoadingScreen(modifier = modifier.fillMaxSize())
is MarsUiState.Success -> ResultScreen(marsUiState.photos, modifier = modifier.fillMaxWidth())
is MarsUiState.Error -> ErrorScreen( modifier = modifier.fillMaxSize())
}
}
@Composable
fun LoadingScreen(modifier: Modifier = Modifier) {
Image(
modifier = modifier.size(200.dp),
painter = painterResource(R.drawable.loading_img),
contentDescription = stringResource(R.string.loading)
)
}
@Composable
fun ErrorScreen(modifier: Modifier = Modifier) {
Column(
modifier = modifier,
verticalArrangement = Arrangement.Center,
horizontalAlignment = Alignment.CenterHorizontally
) {
Image(
painter = painterResource(id = R.drawable.ic_connection_error), contentDescription = ""
)
Text(text = stringResource(R.string.loading_failed), modifier = Modifier.padding(16.dp))
}
}
/**
* ResultScreen displaying number of photos retrieved.
*/
@Composable
fun ResultScreen(photos: String, modifier: Modifier = Modifier) {
Box(
contentAlignment = Alignment.Center,
modifier = modifier
) {
Text(text = photos)
}
}
然后再次运行项目就不会发生崩溃了,然后每种状态都会显示对应的页面。
2.3.5. 使用 kotlinx.serialization 解析 JSON 响应
请求的数据通常采用XML和JSON等常见的数据格式之一。每次调用会返回格式化数据。并且您的应用需要知道结构是什么,才能从响应中读取数据。
例如此应用在输入请求网址, 你可以看到返回的如下数据:

添加kotlinx.serialization 库依赖项
- 打开
build.gradle.kts (Module :app) - 在
plugins代码块中,添加kotlinx serialization插件。
id("org.jetbrains.kotlin.plugin.serialization") version "1.8.10"
实现返回JSON数据的模型类:
package com.example.marsphotos.network
import kotlinx.serialization.Serializable
// 如果我们需要使这个类可以序列化,需要加上@Serializable 注解
@Serializable
data class MarsPhoto (
val id: String,
val imgSrc: String
)
请注意,MarsPhoto 类中的每个变量都对应于 JSON 对象中的一个键名。为了匹配特定 JSON 响应中的类型,您可以为所有值使用 String 对象。
kotlinx serialization 解析 JSON 时,它会按名称匹配键,并用适当的值填充数据对象。
@SerialName 注解
有时,JSON响应中的键名可能会使Kotlin属性引起混淆,或者可能与建议的编码样式不匹配。例如,在 JSON 文件中,img_src 键使用下划线,而按照惯例,Kotlin 属性则使用大写和小写字母(“驼峰命名法”)。
如需在数据类中使用与 JSON 响应中的键名不同的变量名称,请使用 @SerialName 注解。在下例中,数据类中变量的名称为 imgSrc。您可以使用 @SerialName(value = "img_src") 将该变量映射到 JSON 属性 img_src。
package com.example.marsphotos.network
import kotlinx.serialization.SerialName
import kotlinx.serialization.Serializable
// 如果我们需要使这个类可以序列化,需要加上@Serializable 注解
@Serializable
data class MarsPhoto (
val id: String,
@SerialName(value = "img_src")
val imgSrc: String
)
更新 MarsApiService 和 MarsViewModel
- 请注意 ScalarsConverterFactory 的未解析引用错误。这些错误是由上一部分中的 Retrofit 依赖项更改导致的。请删除 ScalarConverterFactory 的导入作业
移除:
import retrofit2.converter.scalars.ScalarsConverterFactory
修改代码如下:
import com.jakewharton.retrofit2.converter.kotlinx.serialization.asConverterFactory
import kotlinx.serialization.json.Json
import okhttp3.MediaType
private val retrofit = Retrofit.Builder()
.addConverterFactory(Json.asConverterFactory("application/json".toMediaType()))
.baseUrl(BASE_URL)
.build()
现在,您已具备 kotlinx.serialization,可以要求 Retrofit 从 JSON 数组中返回 MarsPhoto 对象列表,而不是返回 JSON 字符串。
interface MarsApiService {
@GET("photos")
suspend fun getPhotos(): List<MarsPhoto>
}
MarsViewModel中也需要做如下更改:
val listResult = MarsApi.retrofitService.getPhotos()
marsUiState = MarsUiState.Success(
"Success: ${listResult.size} Mars photos retrieved"
)
上述数据的解析是我们定义的模型和返回的数据完全一致,但是如果服务器返回的数据跟我们定义的模型数据不一致, 比如返回的属性多余我们定义的属性,那么如何配置Json?

**ignoreUnknownKeys = true为什么重要?**服务器返回的JSON可能包含你不需要的字段(如服务器新增了字段,但你没更新APP)。不加这个配置,解析时会直接崩溃。加上后,多余的字段会被忽略哈。
本文详解在Android Studio中使用Retrofit实现网络请求的完整流程,包括添加依赖、定义API接口、配置kotlinx.serialization解析JSON、处理Android网络权限、协程中调用API、异常捕获与界面状态管理(加载/成功/失败)。重点涵盖动态代理机制、@SerialName字段映射、ignoreUnknownKeys容错配置及滚动联动TopAppBar的无关内容已剔除。
785

被折叠的 条评论
为什么被折叠?



