3. 网络状态监听实现：ConnectivityManager / 网络回调、离线状态机设计

3.1 为什么需要主动监听网络状态

离线读写核心依赖两个前提：

• 写入层：能在无网络时可靠地把数据写入本地存储；
• 读取层：能在离线场景下优先返回本地缓存，并在在线时同步最新数据。

这两者都需要一个实时、准确、低开销的网络状态信息来源。被动捕获联网异常（如请求超时）存在延迟大、误判多的问题，因此必须通过系统级的 ConnectivityManager 或跨平台的网络回调机制主动监听。

3.2 ConnectivityManager 工作原理

3.3 典型注册与回调代码

以下片段展示在 Application 或 Service 启动时注册网络回调：

// 获取系统服务
ConnectivityManager cm = (ConnectivityManager)
    context.getSystemService(Context.CONNECTIVITY_SERVICE);

// 构建监听请求（不指定传输类型 = 监听所有网络）
NetworkRequest request = new NetworkRequest.Builder()
    .build();

// 实现回调
ConnectivityManager.NetworkCallback callback = 
    new ConnectivityManager.NetworkCallback() {
    @Override
    public void onAvailable(Network network) {
        // 网络可用 → 触发离线状态机 → “在线态”
        NetworkStateManager.getInstance().onNetworkAvailable();
    }

    @Override
    public void onLost(Network network) {
        // 网络断开 → 触发离线状态机 → “离线态”
        NetworkStateManager.getInstance().onNetworkLost();
    }

    @Override
    public void onCapabilitiesChanged(
            Network network, 
            NetworkCapabilities capabilities) {
        // 网络能力变化（如从WiFi切到蜂窝）
        boolean isMetered = !capabilities
            .hasCapability(NetworkCapabilities.NET_CAPABILITY_NOT_METERED);
        NetworkStateManager.getInstance()
            .onMeteredChanged(isMetered);
    }
};

// 注册（建议在 onStart 时调用）
cm.registerNetworkCallback(request, callback);

3.4 离线状态机设计

网络状态不是简单的“在线/离线”二元态，因为还存在弱网、计量网络、正在切换等中间态。我们设计一个四状态机：

3.5 状态机驱动实现

// NetworkStateManager.java 单例
public class NetworkStateManager {
    private final StateMachine stateMachine;
    private volatile NetworkState currentState = NetworkState.ONLINE;

    public enum NetworkState {
        ONLINE, OFFLINE, METERED, PENDING_SYNC
    }

    public synchronized void onNetworkAvailable() {
        // 从 OFFLINE → PENDING_SYNC，然后启动同步
        if (currentState == NetworkState.OFFLINE) {
            currentState = NetworkState.PENDING_SYNC;
            startSyncForPending();
        } else if (currentState == NetworkState.METERED) {
            // 如果之前是计量网络，直切 ONLINE 但标记计量
            currentState = NetworkState.ONLINE;
        }
    }

    public synchronized void onNetworkLost() {
        currentState = NetworkState.OFFLINE;
        // 清空待发送队列、停止同步
    }

    public synchronized void onMeteredChanged(boolean isMetered) {
        if (isMetered && currentState == NetworkState.ONLINE) {
            currentState = NetworkState.METERED;
        } else if (!isMetered && currentState == NetworkState.METERED) {
            currentState = NetworkState.ONLINE;
        }
    }

    public synchronized void onSyncCompleted() {
        if (currentState == NetworkState.PENDING_SYNC) {
            currentState = NetworkState.ONLINE;
        }
    }

    public boolean isOffline() {
        return currentState == NetworkState.OFFLINE;
    }

    public boolean isMetered() {
        return currentState == NetworkState.METERED;
    }
}

3.6 性能与稳定性要点

3.7 常见错误与调试