Android网络架构实战：MVVM+Retrofit+协程Flow的封装与踩坑记录

1. 先定边界：MVVM + Retrofit 常用网络架构要解决的第一件事

最近一次技术复盘，我把 Android 项目里基于 MVVM + Retrofit 的主流网络架构整体过了一遍。说是架构，其实并没有多新鲜的东西：View 层只负责把用户事件交出去，ViewModel 负责准备界面状态，Repository 统一暴露数据，Retrofit 负责真正的 HTTP 通信。让我想动笔记录的原因，是很多新同学一上来就盯着 Retrofit 封装，比如单例怎么写、拦截器怎么加、Service 怎么定义，却没有考虑这套网络能力在整个工程里到底应该暴露给谁，最后看着很完整，页面一多又回到了复制粘贴改状态。

这篇文章不是标准文档，更像是我把项目从老式 MVP 迁移到 MVVM + Retrofit 架构后的选型笔记。适合正在搭新项目、或者想把现有网络层从 Activity 里捞出来的 Android 开发。如果你刚接触 MVVM 也没关系，我会把边界、代码、异常处理和踩坑过程一起讲清楚，你直接照着一层一层搭也可以。

1.1 为什么 ViewModel 不能直接持有 Retrofit Service

网上很多 Demo 长这样：Activity 创建 ViewModel，ViewModel 里直接放一个 UserApi，登录按钮点击后调用 api.login()，拿到结果塞进 LiveData。三个接口的时候很爽，二十个页面的时候就难过了。

痛点并不在 Retrofit 本身，而在职责。ViewModel 的本职是“为界面准备状态”，不是“发起网络请求并到处处理异常”。如果它直接持有 Retrofit Service，它就必须知道 BaseUrl 拼接规则、Header 里放了什么、Token 过期怎么处理、业务码怎么映射。页面一多，这些事就会在多个 ViewModel 里重复出现。更麻烦的是测试，你要 mock 的是 Retrofit Service 本身，而不是一个“业务仓库”，导致 UI 层的测试很容易被网络细节绑架。

所以我的第一个结论是：页面和 ViewModel 不应该看到 Retrofit，网络库应该被挡在 Repository 后面。ViewModel 只面向“业务数据”和“业务状态”编程，至于这些数据来自网络、本地缓存还是内存，它完全不用关心。

1.2 Repository 和 RemoteDataSource 该根据什么来拆

Repository 是 MVVM 里特别容易被省略的一层。省略后你看到的就是各个 ViewModel 重复调用同一个 ServiceCreator。表面上是 MVVM，实际上只是把 Activity 的代码搬了个家。

我习惯再把数据访问拆成两层：

• RemoteDataSource：只管网络请求本身，包括参数构造、调用 Retrofit Service、把服务端 DTO 转换成领域模型。
• Repository：组合远程数据源和本地数据源，向 ViewModel 暴露更贴近业务的挂起函数或 Flow；它可以先查本地缓存，缓存没有再走网络，再写回缓存。

这样拆有一个非常实际的好处：以后服务端接口从 HTTP 换成 WebSocket，或者给某个接口加一层 Room 缓存，View 和 ViewModel 层的方法签名不会变。依赖方向永远是 ViewModel -> Repository -> DataSource，不允许反向。我在项目里最常听到的一句话是“这个接口我只在页面里用一下，不建 Repository 了”，但只要有一次打破边界，后面就会不断有人模仿。

1.3 真正要传递的是状态，不只是数据

关于网络请求，我最想强调的一点：请求结果不是“成功返回 JSON”这一个瞬间。用户会看到 loading，接口可能返回空列表，token 会失效，弱网会超时，后端会返回业务层 error。如果这些状态都靠 try/catch 去猜，ViewModel 会越来越难维护。

我最终会定义一个状态容器，类似 sealed interface LoadState，里面包含 Idle、Loading、Success、Empty、Error。ViewModel 对外暴露的通常是一个 StateFlow<XxxUiState>，而不是一个 StateFlow<User>。View 层只需要订阅一个状态流，请求中、请求成功、请求失败这些切换全部收在 ViewModel 内部。有人会问 LiveData 加多个 MutableLiveData 不行吗？也能写，但是 _loading 和 _error 两个流天然存在先后顺序，页面经常要同时监听两个值才能推断出当前界面应该显示什么，时间久了全靠约定维持。用统一状态容器，分支逻辑会集中很多，也方便写单元测试。

2. 谈封装前先管好 Service 接口、OkHttpClient 和统一返回体

聊完架构边界，再回来看 Retrofit 的具体封装。很多人以为封装就是建一个单例，实际上 Retrofit 项目里最影响长期维护的是三件事：Service 接口怎么定义、OkHttpClient 的拦截器边界在哪、统一返回体怎么处理空数据。

2.1 网络单例是最容易被过度设计的地方

一个简单的网络单例，网上能写出十种风格。最朴素的版本其实够用：

kotlin复制object NetworkClient {
    private val okHttpClient by lazy {
        OkHttpClient.Builder()
            .connectTimeout(15, TimeUnit.SECONDS)
            .readTimeout(30, TimeUnit.SECONDS)
            .writeTimeout(30, TimeUnit.SECONDS)
            .addInterceptor(HeaderInterceptor())
            .apply {
                if (BuildConfig.DEBUG) {
                    addInterceptor(HttpLoggingInterceptor().apply {
                        level = HttpLoggingInterceptor.Level.BASIC
                    })
                }
            }
            .build()
    }

    val retrofit: Retrofit by lazy {
        Retrofit.Builder()
            .baseUrl(BuildConfig.SERVER_HOST)
            .client(okHttpClient)
            .addConverterFactory(GsonConverterFactory.create())
            .build()
    }

    inline fun <reified T> create(): T = retrofit.create(T::class.java)
}

注意 baseUrl 必须以 / 结尾，否则会抛 IllegalArgumentException。这算是最常见的新手报错。另一个常见问题是日志拦截器在 Release 包也开着，日志等级还设置成 BODY，会把用户手机号和 token 打到 logcat 里。真机调试久了，同事一抓包什么都看得到。我的习惯是日志只在 BuildConfig.DEBUG 下开启，等级用 BASIC，够看 URL 和响应耗时；真要排查参数问题，再临时调成 BODY，排查完立刻改回来。

单例本身我并不反对，项目不大时完全没必要引入依赖注入框架。真正要注意的是：不要为了“以后灵活”把单例方法写成五六层抽象，最后改一个超时时间要翻三个文件。常见网络架构的价值是稳定可复制，不是炫技。

2.2 Retrofit Service 方法该返回 suspend 还是 Call

Retrofit 从 2.6 开始支持 suspend 函数，现在新项目已经没必要再写 Call<T> 加 enqueue 回调了。suspend 函数会把请求放到后台线程，协程取消时网络请求也会一起取消，配合 viewModelScope 非常顺手。

kotlin复制interface UserApi {
    @GET("user/{id}")
    suspend fun getUser(@Path("id") id: Long): BaseResponse<UserDto>
}

这里有个小坑需要注意：如果 Service 方法的返回类型是 BaseResponse<UserDto>，那么 HTTP 层面对 2xx 以外的响应，Retrofit 会直接抛 HttpException，不会再走 BaseResponse 的解析。也就是说，业务错误码统一在 BaseResponse 里处理，HTTP 状态码错误统一靠异常来处理，两层不要混在一起。这样看起来问题不大，问题是很多后端接口不规范：明明业务失败，HTTP 状态还是 200，只是返回的 code 变成了非 0。所以你的 Repository 层在解析完 BaseResponse 后，还要判断 code，而不是见 2xx 就当成功。

我在实际代码里会把 Service 接口返回值保留成带壳子的类型，然后把“判断 code 是否成功”的逻辑放在 RemoteDataSource。每个页面不用自己写一遍 if (response.code != 0)，统一收口在一处。

2.3 拦截器只做协议层的事，业务判断交给上层

OkHttp 拦截器是很强大的扩展点，但也很容易被滥用。HeaderInterceptor 负责加公共 header 和 token，LoggingInterceptor 负责调试日志，最多再写一个处理 401 的拦截器负责 token 过期，这些都属于“协议层”。

我最怕见到的是有人在拦截器里写业务判断，比如根据接口路径去某些页面弹 toast，或者在拦截器里直接跳转登录页。网络层不该知道页面导航，不然每次弹窗文案调整都要动 OkHttp 配置，也不方便测试。正确做法是拦截器发现 401 后，只发出一个“登录态失效”的事件，或者抛出一个特定异常，由上层统一处理。如果要做 token 自动刷新，也尽量保持在网络层内部，刷新结束后重新放行原始请求，不要依赖 Activity 去重新触发一次。

还有请求重试。OkHttp 默认会对连接失败做少量重试，但业务上说的“重试”通常是接口失败后过几秒再请求，或者 token 过期刷新后再请求。这类逻辑不要放在拦截器里无脑循环，容易造成重复提交。比如创建订单接口在网络抖动时重试，用户可能收到两笔订单。我在实际项目里的原则是：幂等接口可以重试，非幂等接口只在用户主动点击时再次请求。

2.4 BaseResponse 壳子与空数据问题

绝大多数团队的接口壳子都是 code/message/data：

kotlin复制data class BaseResponse<T>(
    @SerializedName("code") val code: Int,
    @SerializedName("message") val message: String?,
    @SerializedName("data") val data: T?
)

这里的 data 一定要声明成可空，别写成 val data: T。后端接口的“成功但 data 为空”很常见，有时候是 data 本身为 null，有时候是 data 为一个空 JSON 对象。如果字段声明成非空，Gson 反序列化时可能会得到 null，等到业务代码里访问 data.xxx 才发现问题。更稳妥的做法是在 RemoteDataSource 里统一判断：

kotlin复制suspend fun getUser(id: Long): User {
    val response = api.getUser(id)
    if (response.code != 0) {
        throw ApiException(response.code, response.message ?: "unknown error")
    }
    return response.data ?: throw ApiException(response.code, "data is null")
}

有人会把 data 定义成 JsonElement，然后让 ViewModel 自己解析，这等于把类型安全弄丢了，我不推荐。除非这个接口的 data 结构频繁变化，否则还是建议每个接口写对应的 DTO，由 Retrofit 帮我们完成反序列化。代码虽然多一点，但每个数据结构都能被编译期检查，维护的时候心里有底。

3. 协程和 Flow 的接入：把网络错误翻译成界面状态

Retrofit 的 suspend 函数只是把请求切到了后台线程，真正的状态管理还是要靠 ViewModel 里的协程和 Flow。这里我用的是 MutableStateFlow + Channel 的组合，这套组合在多数业务场景里比裸 LiveData 更清晰。

3.1 UiState 的状态容器怎么落地

先看一个最常见页面的例子。登录页有四个状态：什么都不做、请求中、登录成功、登录失败。我以前会写一堆 MutableLiveData<Boolean> 和 MutableLiveData<String>，后来全换成了密封接口：

kotlin复制sealed interface LoginUiState {
    data object Idle : LoginUiState
    data object Loading : LoginUiState
    data class Success(val user: User) : LoginUiState
    data class Error(val message: String) : LoginUiState
}

对应 ViewModel:

kotlin复制class LoginViewModel(
    private val userRepository: UserRepository
) : ViewModel() {

    private val _uiState = MutableStateFlow<LoginUiState>(LoginUiState.Idle)
    val uiState: StateFlow<LoginUiState> = _uiState.asStateFlow()

    fun login(username: String, password: String) {
        viewModelScope.launch {
            _uiState.value = LoginUiState.Loading
            userRepository.login(username, password)
                .fold(
                    onSuccess = { user ->
                        _uiState.value = LoginUiState.Success(user)
                    },
                    onFailure = { throwable ->
                        _uiState.value = LoginUiState.Error(ErrorMapper.map(throwable))
                    }
                )
        }
    }
}

这样 Activity 里只做一件事：订阅 uiState，根据状态渲染页面。不需要页面自己在请求前去设置 loading，也不需要关心 ViewModel 怎么调网络。

3.2 线程切换不需要每层都写 Dispatchers.IO

很多初学者会在 viewModelScope.launch { withContext(Dispatchers.IO) { ... } } 里包网络请求。Retrofit 的 suspend 函数内部已经帮我们切到了 OkHttp 的线程池，所以 Repository 层直接调用即可，不需要 IO 上下文。真正需要 Dispatchers.IO 或 Dispatchers.Default 的场景是纯 CPU 密集或数据库非常重的操作。

Room 的 suspend DAO 同样会自动切线程，不需要你在外面再包一层 withContext(Dispatchers.IO)。正确的思路是：哪一层做耗时操作，由哪一层自己负责线程调度；上层调用方只关心挂起函数的结果。如果你在 ViewModel 里到处强制指定 IO，那 Repository 内部将来要换成别的数据源时，线程策略就会被调用方绑死。

我推荐在 Repository 内部再包一层 runCatching 或者自定义的 Result 转换，目的不是吞异常，而是让 ViewModel 不用堆满 try/catch。不过 Kotlin 的 Result 有一个注意点：runCatching 会把 CancellationException 也捕获，协程取消时容易出问题。如果 Repository 里确实要 catch，记得把 CancellationException 重新抛出去，否则协程取消后代码还会继续执行，容易产生“页面已经关闭还在改 UI”的隐患。

3.3 一次性事件要用 Channel，不能用 StateFlow

StateFlow 和 LiveData 都是粘性事件，新的订阅者一进来就会收到当前值。这对正常状态渲染非常友好，但不太适合 Toast、弹窗、跳转这类一次性事件。比如登录失败后设置了一个 Error 状态，页面根据状态弹了一个 toast；下一次用户旋转屏幕重建 Activity，重新订阅 StateFlow 时会立刻再次收到 Error，Toast 就重复弹了。这不是 bug，而是 StateFlow 的特性。

一次性事件我有两种处理方式：

1. 用一个 Channel<UiEvent>，在 ViewModel 里 send 事件，页面用 Flow.receiveAsFlow() 收集。
2. 在状态流里加一个 eventId 或者“已消费标记”，页面消费后回传。

如果项目里不想再多记一种 API，我建议最省事的方案是单独再暴露一个 SharedFlow，设置 extraBufferCapacity = 1 且 onBufferOverflow = DROP_OLDEST。这样发送的导航事件或提示事件不会在页面重建时重新播放，比用状态去模拟事件要省心很多。

4. 一套可直接复刻的工程目录与一次完整请求链路

前面把思想讲完了，现在落到工程里。我接下来按自己项目里常用的一套目录结构来写，你可以直接抄。

4.1 依赖选择和目录划分经验

依赖不必贪多，核心就这几个：

kotlin复制implementation("androidx.lifecycle:lifecycle-viewmodel-ktx:2.7.0")
implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.7.0")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
implementation("com.squareup.retrofit2:retrofit:2.9.0")
implementation("com.squareup.retrofit2:converter-gson:2.9.0")
implementation("com.squareup.okhttp3:logging-interceptor:4.12.0")

如果你的项目已经用了 Kotlin 的 Serialization，可以把 Gson 换成 converter-kotlinx-serialization；如果用到大量动态泛型，可以考虑 Moshi。Gson 不是不能用，但它对 Kotlin 空安全字段的默认值处理不太友好，尤其是 data class 字段没有默认值而服务端又返回 null 时会抛异常。所以在声明 DTO 时，可空字段一定要给默认值 = null，集合字段给 emptyList()，能省很多线下崩溃。

目录我习惯这样分：

text复制app/src/main/java/com/project/
├── data
│   ├── local
│   ├── remote
│   │   ├── api/        # Retrofit Service
│   │   ├── datasource/ # RemoteDataSource
│   │   └── model/      # DTO
│   └── repository/
├── domain
│   └── model/
├── ui
│   ├── common/
│   └── feature/
└── di/

domain 层主要放不依赖 Android SDK 的领域模型和接口。如果你的项目没到那么复杂，domain 可以先不建，但 data 和 ui 一定要分开。我见过很多项目把 DTO、Repository、Adapter 全塞在同一层，看起来省事，一旦要改接口结构，改动范围会波及 UI。

4.2 从点击到渲染：一条用户详情请求的完整链路

我用“获取用户详情”举例，把整条链路串起来。

Service 层：

kotlin复制interface UserApi {
    @GET("user/{id}")
    suspend fun getUser(@Path("id") id: String): BaseResponse<UserDto>
}

RemoteDataSource 层：

kotlin复制class UserRemoteDataSource(
    private val api: UserApi
) {
    suspend fun getUser(id: String): User {
        val response = api.getUser(id)
        if (response.code != 0) {
            throw ApiException(response.code, response.message ?: "unknown error")
        }
        return response.data?.toDomain()
            ?: throw ApiException(response.code, "empty data")
    }
}

Repository 层：

kotlin复制class UserRepository(
    private val remoteDataSource: UserRemoteDataSource
) {
    suspend fun getUser(id: String): Result<User> {
        // 以后可以在这里加缓存逻辑
        return runCatching { remoteDataSource.getUser(id) }
    }
}

注意这里用 runCatching 时，要排除协程取消造成的 CancellationException，否则会导致请求无法被真正取消。更严谨的写法是：

kotlin复制suspend fun getUser(id: String): Result<User> = try {
    Result.success(remoteDataSource.getUser(id))
} catch (e: CancellationException) {
    throw e
} catch (e: Exception) {
    Result.failure(e)
}

ViewModel 层：

kotlin复制class UserDetailViewModel(
    private val repository: UserRepository
) : ViewModel() {

    private val _uiState = MutableStateFlow<UserDetailUiState>(UserDetailUiState.Loading)
    val uiState: StateFlow<UserDetailUiState> = _uiState.asStateFlow()

    fun loadUser(id: String) {
        viewModelScope.launch {
            _uiState.value = UserDetailUiState.Loading
            repository.getUser(id)
                .onSuccess { user ->
                    _uiState.value = UserDetailUiState.Success(user)
                }
                .onFailure { e ->
                    _uiState.value = UserDetailUiState.Error(e.toReadableMessage())
                }
        }
    }
}

Activity 或 Fragment 只负责收集：

kotlin复制repeatOnLifecycle(Lifecycle.State.STARTED) {
    viewModel.uiState.collect { state ->
        when (state) {
            is Loading -> showLoading()
            is Success -> showUser(state.user)
            is Error -> showError(state.message)
        }
    }
}

这条链路的层次感很清晰：页面不碰 DTO，不碰 Retrofit，不碰 OkHttp。哪天后端把用户名从 nickname 改成 name，只需要改 DTO 和 toDomain()，其他层不动。

4.3 分页列表加载更多如何管理状态

列表页是网络架构里最容易出乱的地方，因为除了一开始的加载状态，还有下拉刷新、上拉加载、没有更多、加载更多失败四种状态要同时管理。

我用一个简单的 PagingState 来统一：

kotlin复制data class PagingState<T>(
    val isLoadingFirst: Boolean = false,
    val isLoadingMore: Boolean = false,
    val isRefreshing: Boolean = false,
    val hasMore: Boolean = true,
    val errorMessage: String? = null,
    val items: List<T> = emptyList()
)

代码片段：

kotlin复制fun refresh() {
    viewModelScope.launch {
        _pagingState.update { it.copy(isRefreshing = true, errorMessage = null) }
        repository.getPage(1)
            .onSuccess { list ->
                _pagingState.update {
                    it.copy(
                        isRefreshing = false,
                        items = list,
                        hasMore = list.size >= PAGE_SIZE
                    )
                }
            }
            .onFailure { e ->
                _pagingState.update { it.copy(isRefreshing = false, errorMessage = e.toReadableMessage()) }
            }
    }
}

fun loadMore() {
    val state = _pagingState.value
    if (state.isLoadingMore || !state.hasMore || state.items.isEmpty()) return
    viewModelScope.launch {
        _pagingState.update { it.copy(isLoadingMore = true) }
        repository.getPage(state.items.size / PAGE_SIZE + 1)
            .onSuccess { list ->
                _pagingState.update {
                    it.copy(
                        isLoadingMore = false,
                        items = it.items + list,
                        hasMore = list.size >= PAGE_SIZE
                    )
                }
            }
            .onFailure { e ->
                _pagingState.update { it.copy(isLoadingMore = false, errorMessage = e.toReadableMessage()) }
            }
    }
}

为什么不用 Paging3？如果用 Paging3，上面的状态确实由官方库帮我们处理了很多，但它也带来了 RemoteMediator 和 LoadResult 的学习成本。如果你的项目是后端返回 pageNum 和 pageSize 的简单分页，手写状态并不复杂，反而更可控。项目足够大、列表数据需要跟 Room 深度联动再考虑 Paging3。

5. 项目排坑记录：这些场景也是网络架构的一部分

写这篇文章时我把项目里踩过的坑翻了一遍，发现网络架构是否舒服，往往不在于正常返回路径，而在异常和边界场景。

5.1 loading 闪烁：请求太快时 UI 反而更难做

我第一次用统一状态流时发现一个现象：用户点击登录，接口 200ms 就返回了，UI 会瞬间从 Loading 切到 Success。虽然时间很短，但很多列表页有“加载动画由透明到可见”的渐变逻辑，转场时间刚好被截断，看起来就会闪一下。

解决方案不是加一个“最短 loading 时间”去强行拖慢，而是区分场景。如果是下拉刷新，就不要把整个页面置成 Loading；如果是切页第一次加载，可以使用 debounce 或者延迟显示 loading。更常用的做法是 ViewModel 维护“当前列表是否为空”：

• 列表为空时，Loading 显示为占位骨架屏。
• 列表已经有数据时，再来请求不显示全局 Loading，只显示顶部刷新或底部加载更多的小指示器。

所以状态容器里要把“页面是否已有数据”也考虑进去，不能只用一个 Loading 字段一竿子打死。

5.2 token 失效时同时来了多个请求怎么办

我遇到的最典型问题：App 里同时发起了三个请求，三个请求都因为 token 过期返回 401。如果拦截器里每个请求都去刷新 token，那后端会收到三四个刷新请求，很容易把旧 token 返回给其中某个请求，导致刷新后的请求依然失败。

解决办法通常是单飞模式：同一时间只允许一个刷新请求执行，其他 401 请求在刷新期间等待，刷完后再带着新 token 重放。如果不引入额外的状态机，网络层代码很容易写乱。我这里采取稍简单但也可靠的策略：

• TokenManager 负责保存 token 和刷新 token。
• 刷新 token 的 suspend fun 内部用一个全局锁保证并发时只有一个协程真正执行刷新，其他协程 await 同一个结果。
• 401 拦截器只负责抛出一个自定义的 TokenExpiredException，Repository 层捕获后交给上层触发重新登录或静默刷新。

这套逻辑如果全写在 OkHttp 拦截器里会比较绕，因为 OkHttp 的 intercept 是同步模型，处理 suspend 要配合 runBlocking 或扩展。我更推荐在 Repository 层做一个“请求前检查 token 是否过期”的步骤。简单项目也可以直接在 ViewModel 统一处理：收到 401 异常后弹一个对话框，用户重新登录后重试原始请求。这样虽然体验上不是最自动，但代码最简单，也最不容易出错。

5.3 协程取消后回调还在更新 UI 的问题

使用 Retrofit suspend 请求时，协程取消后 OkHttp 请求会被取消，这是正常的行为。但有些人还在用旧的 Callback 或者自己包装的 Flow，这时就要特别小心。比如你在 ViewModel 里用 async {} 发请求，稍后 viewModelScope 因为页面关闭而取消，但如果你在顶层调用了不响应取消的 runCatching，或者 Flow 里有 catch {} 吞掉了 CancellationException，请求回调依然可能继续执行。

我加了一条硬性约定：任何 Repository 层在捕获异常后，必须重新抛出 CancellationException。这条约定不用依赖框架，就是强制在代码 review 时检查。很多诡异的“页面关闭后还弹出 Toast”其实都是协程取消没被正确传递导致的。

如果你在项目里确实有使用 kotlinx.coroutines.flow.catch {}，请记得 catch 块里判断一下：

kotlin复制.catch { e ->
    if (e is CancellationException) throw e
    _uiState.value = ErrorState(e.toReadableMessage())
}

5.4 统一返回体中 data 为空，Gson 的 null 处理

另一类是后端字段不按约定返回。我用 BaseResponse<T> 时遇到过程序崩溃，原因就是响应里 data 为 null，而我的 DTO 字段是非空类型且没有默认值。Gson 在反射构造对象时对缺失字段并不总是赋默认值，最后运行时访问到的是 null，这其实比直接崩溃更隐蔽。

后来我强制要求：所有网络 DTO 的可空字段都要声明为可空并给默认值，List 字段给 emptyList()。例如：

kotlin复制data class UserDto(
    @SerializedName("id") val id: String,
    @SerializedName("name") val name: String? = null,
    @SerializedName("tags") val tags: List<String>? = emptyList()
)

不要觉得这很啰嗦。后端少一个字段是常态，某天新增字段但旧版本 App 没定义，Gson 不会报错；反过来，后端某天把字段值返回成 null，而 DTO 声明成了非空，就会出现难以定位的调用错误。把空安全习惯做好，能省掉很多线上排查时间。

6. 对“常用网络架构”的边界思考：什么该加，什么别乱加

最后这部分是我自己的复盘，不打算给出一份“标准答案”，只聊边界和取舍。

6.1 手动注入还是 Hilt？先看团队改代码的成本

有段时间我很迷信依赖注入，一搭项目就上 Hilt。后来发现中小型项目里，手动注入 ViewModel 的 Repository 并不难，更难的是让团队每个人理解“构造函数里传进来的这个依赖是用来干什么的”。如果你的项目里只有一个 NetworkClient，手动在 ViewModel 里 UserRepository(UserRemoteDataSource(NetworkClient.create())) 看起来多，但可读性其实很高。Hilt 的价值在于模块多、依赖关系复杂时减少样板代码，它本身不会帮你把架构变好。

为了可维护性，我会至少在界面层做到看不到网络细节。如果团队已经有 DI 基础设施，可以继续用；如果没有，不要为了“以后要加”而提前引入。架构是给团队用的，不是用来收藏的。

6.2 Paging3 和手写分页的取舍

我在前面提到手写分页更可控，但如果项目里有很多 Feed 流、页面需要非常流畅地加载和回收，Paging3 仍然值得认真评估。Paging3 好处在于数据流和状态加载被官方很好地处理，后端分页模型也能通过 PagingSource 接入。

可它也要求你遵守它的数据源写法，尤其是做“下拉刷新后回到第一页”“加载更多失败后重试”这些交互时，你得理解 LoadState 的语义。否则很容易出现“官方库帮你管理了状态，你又在 UI 层维护了一堆状态”的重复。

我的建议是：团队里至少有一个人能回答 Paging3 的 LoadState 和 RemoteMediator 是怎么流转的，再决定引入；否则简单列表用 Repository 返回分页数据，配合 PagingState 一样够用。

6.3 我最后保留下来的几条约定

1. View 层不能出现 LoginApi、UserApi、Retrofit 这些词。
2. ViewModel 不做网络 DTO 到 UI Model 的转换，这个转换放在 RemoteDataSource 或 Repository。
3. Repository 的挂起函数不返回 JSON 壳子，只返回业务模型或 Result。
4. 任何 catch 不能吞协程的 CancellationException。
5. 状态容器永远比零散 LiveData 可靠，一次性事件单独走 Channel 或 SharedFlow。
6. 日志拦截器只在 Debug 打开，Release 包不做 BODY 级日志。

这些约定很朴素，但每次 project review 时我都能看到违反它们的代码，比如 ViewModel 里手写 Gson 解析，或者 Activity 里直接用 NetworkClient.create<XxxApi>()。技术本身不复杂，复杂的是不断提醒团队和自己“这个依赖为什么要从外层传进来，为什么不能让 UI 层直接摸到网络框架”。网络架构记录得再多，最后能落地的其实是这几个基本判断。希望这篇笔记能帮你少走一点弯路。