Connectivity Manager：是什么、方法及连接监控

什么是 Connectivity Manager？

ConnectivityManager 是 Android 操作系统中的系统服务，可通过 Context.getSystemService(Context.CONNECTIVITY_SERVICE) 访问。它提供 API 用于获取设备网络连接信息、监控网络变化和管理应用程序的网络请求。Connectivity Manager 从平台首个版本（API Level 1）起就是 Android Framework 的一部分，几十年来经历了重大变化：从简单的 getActiveNetworkInfo() 到现代反应式模型 NetworkCallback 和 NetworkRequest。

Connectivity Manager 的主要功能包括：检查活动网络连接是否存在、确定网络类型（Wi-Fi、移动数据、Ethernet、Bluetooth、VPN）、实时监控网络状态变化、获取带宽和延迟信息、管理应用程序的网络请求。ConnectivityManager 与 WorkManager 和 Repository 一起用于实现 Offline-First 架构、自适应内容加载以及根据连接质量优化应用程序性能。

从 Android 10（API 29）开始，Google 改变了使用 ConnectivityManager 的方式。getActiveNetworkInfo() 方法已被弃用，建议使用 registerDefaultNetworkCallback() 或 registerNetworkCallback() 配合 NetworkRequest。新的 API 提供更详细的网络信息，包括检测强制门户（需要认证的 Wi-Fi）和评估连接质量。ConnectivityManager 还与 Jetpack 家族集成：ConnectivityManager 库于 2024 年作为 Jetpack 的一部分发布，用于简化 Compose 应用程序中的网络监控。

Connectivity Manager 在应用程序架构中的作用

在现代 Android 架构中，Connectivity Manager 在 Repository 或 UseCase 层级用于决定网络请求。Repository Layer 在调用 API 之前检查网络状态：如果网络不可用，则从本地存储（Room）返回数据。如果网络可用，则向服务器发出请求，并将结果保存在 Room 中。ViewModel 订阅 Room 的 Flow，不涉及网络交互的细节——这使得每层可以独立进行测试。

Connectivity Manager 的工作原理

Connectivity Manager 从系统 connectivity 服务获取网络状态信息，该服务与 Linux 内核的网络接口交互。当设备连接到 Wi-Fi 或启用移动数据时，内核通知系统服务，系统服务更新内部状态并通知所有已注册的回调。ConnectivityManager 的架构基于 Observer 模式：应用程序注册 NetworkCallback 并接收网络任何变化的通知——连接出现、连接丢失、网络类型更改或质量下降。

现代 ConnectivityManager API 使用 NetworkRequest 过滤网络事件。NetworkRequest 可以指定网络要求：传输类型（Transport.WIFI、Transport.CELLULAR、Transport.ETHERNET）、互联网访问能力（NetworkCapabilities.NET_CAPABILITY_INTERNET）和其他条件。如果应用程序仅需要 Wi-Fi 来下载大型文件，它创建一个包含 Transport.WIFI 的 NetworkRequest 并注册回调。系统仅在 Wi-Fi 连接变化时通知应用程序，忽略移动网络事件。

Android 12+ 上 Connectivity Manager 的一个重要特性——基于能力的网络（capabilities-based networking）。应用程序不仅检查是否有互联网，还可以评估可用流量的类型。例如，NET_CAPABILITY_NOT_METERED 表示无限连接（Wi-Fi），NET_CAPABILITY_NOT_ROAMING 表示设备不在漫游中。这允许做出决策：仅通过 Wi-Fi 下载视频、在漫游时延迟同步、或仅对关键请求使用移动数据。

Connectivity Manager 的访问权限

在 Android 应用程序中使用 Connectivity Manager 需要权限。ACCESS_NETWORK_STATE — 读取网络信息的必要权限，在 AndroidManifest.xml 中声明。如果没有此权限，ConnectivityManager 将返回 null（对于 getActiveNetwork()）并且不会调用回调。执行网络操作还需要 INTERNET 权限。从 Android 10（API 29）开始，应用程序可以检查网络状态而无需额外的运行时权限——ACCESS_NETWORK_STATE 是普通权限（normal permission），在安装时自动授予。

Connectivity Manager 的主要方法

现代 Connectivity Manager 提供了几个处理网络的关键方法。getActiveNetwork()（API 23+）返回当前活动网络的 Network 对象，如果设备未连接则返回 null。此方法不需要回调，适用于一次性检查。Network 对象可以传递给 NetworkCapabilities 以获取详细信息：传输类型、计量状态、漫游、互联网访问能力等。

registerDefaultNetworkCallback()（API 24+）— 首选的网络监控方式。应用程序注册一个回调，当默认网络（应用程序通过其发送流量的网络）发生任何变化时调用。回调接收 Network 对象，可用于绑定套接字和 HTTP 客户端。此方法取代了已弃用的 getActiveNetworkInfo()，提供无需轮询的反应式网络监控。

registerNetworkCallback()（API 21+）允许通过 NetworkRequest 订阅特定网络类型的变化。例如，应用程序可以通过 new NetworkRequest.Builder().addTransportType(NetworkCapabilities.TRANSPORT_WIFI).build() 仅监控 Wi-Fi 网络。系统会在 Wi-Fi 连接/断开时通知应用程序，而不影响移动网络事件。NetworkCapabilities.getLinkDownstreamBandwidthKbps() 返回下游链路带宽估计值（kbps），允许根据连接速度调整内容质量。

Jetpack Compose 中的 ConnectivityManager

Jetpack Connectivity 库（androidx.core:core-ktx）提供了方便的扩展用于在 Compose 中使用 ConnectivityManager。ConnectivityManager.observeAsState() 函数返回一个 State，在网络变化时更新。@Composable NetworkStatus() 组件显示连接状态，并在变化时自动重绘。这使开发人员无需手动管理回调和 Activity/Fragment 生命周期。

NetworkCallback 和网络变化处理

ConnectivityManager.NetworkCallback 是一个抽象类，其方法在网络状态变化时由系统调用。onAvailable(Network) — 当网络变为可用时调用。应用程序接收 Network 对象，可通过 Network.bindSocket() 用于绑定套接字。onLost(Network) — 当网络变为不可用时调用。应用程序应切换到本地数据或显示无连接消息。onCapabilitiesChanged(Network, NetworkCapabilities) — 当网络特征发生变化时调用（例如从 Wi-Fi 切换到移动数据时）。

正确处理网络变化需要考虑组件的生命周期。回调应在 onStart()/onResume() 中注册并在 onStop()/onPause() 中取消。如果回调未被取消，它可能在 Activity 销毁后继续被调用，导致内存泄漏。在 Jetpack ViewModel 架构中，建议使用 lifecycleScope 注册回调，以便在 ViewModel 清理时自动取消。对于服务和后台任务，使用带有 NetworkType 限制的 WorkManager。

处理强制门户 — ConnectivityManager 从 Android 10 开始的重要功能。CAPTIVE_PORTAL — 场景：Wi-Fi 网络可用但需要通过网页进行认证（机场、酒店、咖啡馆）。NetworkCapabilities.NET_CAPABILITY_VALIDATED 指示网络具有完整的互联网访问权限。如果缺少 NET_CAPABILITY_VALIDATED，应用程序可以打开浏览器通过强制门户进行认证。用于检测强制门户的方法是 isCaptivePortal()，在 Android 11（API 30）中新增。

特定用途的网络（NetworkRequest）

ConnectivityManager 允许通过 requestNetwork() 和 bindProcessToNetwork() 为特定目的请求网络。例如，用于下载大型文件的应用程序可以请求 Wi-Fi 网络，即使移动数据处于活动状态。为此，创建一个带有 addTransportType(TRANSPORT_WIFI) 的 NetworkRequest，当 Wi-Fi 出现时系统调用 onAvailable()。应用程序通过 network.bindSocket() 或配置了 Network 对象的 OkHttp 将套接字绑定到该网络。这提供了对网络接口使用的灵活控制。

Kotlin 实现示例

让我们看一个在 Clean Architecture 中使用现代 API（NetworkCallback）的 ConnectivityManager 完整示例。NetworkMonitor — 一个围绕 ConnectivityManager 的包装类，通过 StateFlow 提供反应式网络状态。ViewModel 订阅此 Flow 并将状态传递给 UI。Repository 使用 NetworkMonitor 来决定网络请求。这种方法确保了可测试性和平台依赖的隔离。

下面的示例展示了如何正确使用 ConnectivityManager 与 registerDefaultNetworkCallback。NetworkMonitor 类封装了与系统服务的交互，并提供了一个干净的 Kotlin Flow。它在启动时注册回调，并在生命周期结束时取消它。异步工作通过协程和 callbackFlow 确保——这是 ConnectivityManager 回调风格和 Kotlin 反应式 Flow 风格之间的桥梁。

class NetworkMonitor(
    private val connectivityManager: ConnectivityManager
) {
    val isOnline: StateFlow<Boolean> = callbackFlow {
        val callback = object : ConnectivityManager.NetworkCallback() {
            override fun onAvailable(network: Network) {
                trySend(true)
            }
            override fun onLost(network: Network) {
                trySend(false)
            }
            override fun onCapabilitiesChanged(
                network: Network,
                caps: NetworkCapabilities
            ) {
                val connected = caps.hasCapability(
                    NetworkCapabilities.NET_CAPABILITY_INTERNET
                )
                trySend(connected)
            }
        }
        connectivityManager.registerDefaultNetworkCallback(callback)
        awaitClose {
            connectivityManager.unregisterNetworkCallback(callback)
        }
    }.stateIn(
        CoroutineScope(Dispatchers.Default),
        SharingStarted.WhileSubscribed(5000),
        initialValue = checkInitialState()
    )

    private fun checkInitialState(): Boolean {
        val network = connectivityManager.getActiveNetwork() ?: return false
        val caps = connectivityManager.getNetworkCapabilities(network) ?: return false
        return caps.hasCapability(
            NetworkCapabilities.NET_CAPABILITY_INTERNET
        )
    }
}

在 ViewModel 和 Repository 中使用 NetworkMonitor

ViewModel 通过 stateIn() 订阅 NetworkMonitor.isOnline 并将状态传递给 Compose。Repository 在调用 API 之前检查 isOnline.value 的当前值：如果为 false — 从 Room 返回 Flow。如果为 true — 调用 API，将结果保存到 Room 并返回 Room 的 Flow。WorkManager 使用 NetworkType.CONNECTED 限制后台任务。NetworkMonitor 的测试使用 mock ConnectivityManager 对象和 fake NetworkCallback 完成，允许在单元测试中模拟任何网络场景。

最佳实践和常见错误

使用 ConnectivityManager 的第一条规则——不要使用弃用的 API。getActiveNetworkInfo() 从 API 29 起已弃用，可能在新版 Android 上返回不正确的数据。请改用 getActiveNetwork() + getNetworkCapabilities() 进行一次性检查，使用 registerDefaultNetworkCallback() 进行持续监控。旧方法也无法区分带强制门户的网络和完整互联网，导致错误触发。

第二条规则——始终取消回调注册。如果 Activity 在 onStart() 中注册 NetworkCallback 但未在 onStop() 中取消，回调将在 Activity 销毁后继续运行。这会导致内存泄漏，以及回调尝试更新已销毁组件的 UI 时可能出现的 NullPointerException。使用 lifecycleScope 或 repeatOnLifecycle 进行自动注册管理。在 Jetpack Compose 中使用 DisposableEffect 进行回调的注册和取消。

第三个常见错误——仅检查网络是否存在而不考虑其质量。简单的有互联网并不足以做出决策。应用程序应检查 NET_CAPABILITY_NOT_METERED 以确定是否适合下载大型文件，NET_CAPABILITY_NOT_ROAMING 以确定是否适合后台同步，NET_CAPABILITY_VALIDATED 以确认互联网访问。忽略这些标志会导致应用程序试图在漫游时下载视频或通过酒店强制门户同步数据。

第四——不要使用 ConnectivityManager 来检查特定服务器的可用性。ConnectivityManager 报告设备上的网络状态，但不保证服务器可用。要检查 API 的可用性，请使用带有短超时的 HTTP 请求或 Health Check。ConnectivityManager + HTTP ping — 可靠的组合：首先检查网络是否可用，然后向服务器发出轻量级请求以确认实际可用性。

测试 ConnectivityManager

对于单元测试，使用 Robolectric 和 ShadowConnectivityManager，它可以模拟网络状态。对于集成测试 — Android Test Orchestrator 配合飞行模式切换。在测试中检查以下场景：从在线到离线的转换、在移动网络活动时 Wi-Fi 出现、请求执行期间网络丢失、强制门户、漫游。对于模块化测试中的模拟，使用包装器接口（例如 NetworkMonitorInterface），该接口可以替换为没有平台依赖的 mock 对象。