生命周期感知组件

// ComponentActivity.java 核心实现（简化版）
public class ComponentActivity extends Activity implements LifecycleOwner {
    
    // 持有 LifecycleRegistry 实例，负责管理观察者与状态
    private final LifecycleRegistry mLifecycleRegistry = new LifecycleRegistry(this);
    
    // 实现 LifecycleOwner 接口的唯一方法
    @NonNull
    @Override
    public Lifecycle getLifecycle() {
        // 返回 LifecycleRegistry，它是 Lifecycle 的具体实现
        return mLifecycleRegistry;
    }
    
    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        // 通过 ReportFragment 注入生命周期上报逻辑（兼容方案）
        ReportFragment.injectIfNeededIn(this);
    }
}

// Fragment 中正确观察 LiveData 的方式
class MyFragment : Fragment() {
    
    private val viewModel: MyViewModel by viewModels()
    
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        
        // ✅ 使用 viewLifecycleOwner，View 销毁时自动取消订阅
        viewModel.data.observe(viewLifecycleOwner) { data ->
            // 更新 UI
            binding.textView.text = data
        }
        
        // ❌ 使用 this 可能导致内存泄漏或重复回调
        // viewModel.data.observe(this) { ... }
    }
}

// LifecycleOwner 接口定义（极简）
public interface LifecycleOwner {
    /**
     * 返回该组件的 Lifecycle 实例
     * 该方法必须在主线程调用
     */
    @NonNull
    Lifecycle getLifecycle();
}

// 自定义 LifecycleOwner 的 Service 实现
class MyLifecycleService : Service(), LifecycleOwner {
    
    // 创建 LifecycleRegistry，传入 this 作为 owner
    private val lifecycleRegistry = LifecycleRegistry(this)
    
    // 实现 LifecycleOwner 接口
    override val lifecycle: Lifecycle
        get() = lifecycleRegistry
    
    override fun onCreate() {
        super.onCreate()
        // 手动标记状态为 CREATED
        lifecycleRegistry.currentState = Lifecycle.State.CREATED
    }
    
    override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
        // 手动标记状态为 STARTED
        lifecycleRegistry.currentState = Lifecycle.State.STARTED
        return START_STICKY
    }
    
    override fun onDestroy() {
        // 手动标记状态为 DESTROYED
        lifecycleRegistry.currentState = Lifecycle.State.DESTROYED
        super.onDestroy()
    }
    
    override fun onBind(intent: Intent?): IBinder? = null
}

// Lifecycle.State 枚举定义
public enum class State {
    DESTROYED,  // 已销毁，终态
    INITIALIZED, // 已初始化，但尚未调用 onCreate
    CREATED,    // 已创建，介于 onCreate 之后与 onStart 之前
    STARTED,    // 已启动，介于 onStart 之后与 onResume 之前
    RESUMED;    // 已恢复，用户可见且可交互，最活跃状态
    
    // 判断当前状态是否至少处于指定状态
    public fun isAtLeast(state: State): Boolean {
        return compareTo(state) >= 0
    }
}

// LiveData 内部判断观察者是否活跃的简化逻辑
fun shouldBeActive(): Boolean {
    // 只有当宿主至少处于 STARTED 状态时，观察者才被视为活跃
    return owner.lifecycle.currentState.isAtLeast(Lifecycle.State.STARTED)
}

// LifecycleRegistry 添加观察者的核心逻辑（简化版）
override fun addObserver(observer: LifecycleObserver) {
    // 强制在主线程执行，确保线程安全
    enforceMainThreadIfNeeded("addObserver")
    
    // 新观察者的初始状态：如果当前状态是 DESTROYED 则为 DESTROYED，否则为 INITIALIZED
    val initialState = if (state == State.DESTROYED) State.DESTROYED else State.INITIALIZED
    
    // 将观察者包装为 ObserverWithState，该包装类持有观察者及其当前状态
    val statefulObserver = ObserverWithState(observer, initialState)
    
    // 使用 FastSafeIterableMap 存储，支持在遍历时修改
    val previous = observerMap.putIfAbsent(observer, statefulObserver)
    
    // 如果观察者已存在，直接返回，避免重复添加
    if (previous != null) return
    
    // 获取 LifecycleOwner（使用弱引用避免内存泄漏）
    val lifecycleOwner = lifecycleOwner.get() 
        ?: return  // 如果 Owner 已被回收，直接返回
    
    // 标记正在添加观察者，用于处理重入情况
    val isReentrance = addingObserverCounter != 0 || handlingEvent
    
    // 计算目标状态：取当前状态和新观察者状态的较小值
    var targetState = calculateTargetState(observer)
    
    addingObserverCounter++  // 增加计数器，标记添加操作进行中
    
    // 核心循环：逐步将观察者状态推进到目标状态
    while (statefulObserver.state < targetState && observerMap.contains(observer)) {
        pushParentState(statefulObserver.state)  // 压入父状态（用于处理嵌套调用）
        
        // 获取将观察者从当前状态推进到下一状态所需的事件
        val event = Event.upFrom(statefulObserver.state)
            ?: throw IllegalStateException("no event up from ${statefulObserver.state}")
        
        // 分发事件给观察者，同时更新观察者的状态
        statefulObserver.dispatchEvent(lifecycleOwner, event)
        
        popParentState()  // 弹出父状态
        
        // 重新计算目标状态（因为在分发事件过程中，状态可能被修改）
        targetState = calculateTargetState(observer)
    }
    
    // 如果不是重入调用，则同步所有观察者的状态
    if (!isReentrance) {
        sync()
    }
    
    addingObserverCounter--  // 减少计数器
}

// 处理生命周期事件的入口方法
fun handleLifecycleEvent(event: Event) {
    // 强制主线程执行
    enforceMainThreadIfNeeded("handleLifecycleEvent")
    // 将事件转换为目标状态，并移动到该状态
    moveToState(event.targetState)
}
 
// 移动到目标状态
private fun moveToState(next: State) {
    // 如果目标状态与当前状态相同，无需处理
    if (state == next) return
    
    // 更新当前状态
    state = next
    
    // 如果正在处理事件或正在添加观察者，标记需要同步并返回
    // 这是为了避免重入导致的状态混乱
    if (handlingEvent || addingObserverCounter != 0) {
        newEventOccurred = true
        return
    }
    
    // 标记正在处理事件
    handlingEvent = true
    
    // 核心同步方法
    sync()
    
    handlingEvent = false
}

// 同步所有观察者的状态
private fun sync() {
    val lifecycleOwner = lifecycleOwner.get()
        ?: throw IllegalStateException("LifecycleOwner was GC'd")
    
    // 循环直到所有观察者都同步完成
    while (!isSynced) {
        newEventOccurred = false  // 重置新事件标记
        
        // 情况1：需要向后回退（如 RESUMED -> STARTED）
        // 比较当前状态与最老观察者（eldest）的状态
        if (state < observerMap.eldest()!!.value.state) {
            backwardPass(lifecycleOwner)
        }
        
        // 情况2：需要向前推进（如 STARTED -> RESUMED）
        // 比较当前状态与最新观察者（newest）的状态
        val newest = observerMap.newest()
        if (!newEventOccurred && newest != null && state > newest.value.state) {
            forwardPass(lifecycleOwner)
        }
    }
    
    newEventOccurred = false
}
 
// 判断是否已同步完成：所有观察者状态一致且等于当前状态
private val isSynced: Boolean
    get() {
        if (observerMap.size() == 0) return true
        val eldestState = observerMap.eldest()!!.value.state
        val newestState = observerMap.newest()!!.value.state
        // 最老和最新观察者状态相同，且等于当前目标状态
        return eldestState == newestState && state == eldestState
    }

// Lifecycle.Event 枚举定义
enum class Event {
    ON_CREATE,   // 对应 CREATED 状态
    ON_START,    // 对应 STARTED 状态  
    ON_RESUME,   // 对应 RESUMED 状态
    ON_PAUSE,    // 从 RESUMED 回退到 STARTED
    ON_STOP,     // 从 STARTED 回退到 CREATED
    ON_DESTROY,  // 从 CREATED 回退到 DESTROYED
    ON_ANY;      // 通配符，匹配任意事件
    
    // 获取事件对应的目标状态
    val targetState: State
        get() = when (this) {
            ON_CREATE, ON_STOP -> State.CREATED
            ON_START, ON_PAUSE -> State.STARTED
            ON_RESUME -> State.RESUMED
            ON_DESTROY -> State.DESTROYED
            ON_ANY -> throw IllegalArgumentException("ON_ANY has no target state")
        }
    
    // 从某状态向上推进时应触发的事件
    companion object {
        @JvmStatic
        fun upFrom(state: State): Event? = when (state) {
            State.INITIALIZED -> ON_CREATE
            State.CREATED -> ON_START
            State.STARTED -> ON_RESUME
            else -> null
        }
        
        // 从某状态向下回退时应触发的事件
        @JvmStatic
        fun downFrom(state: State): Event? = when (state) {
            State.CREATED -> ON_DESTROY
            State.STARTED -> ON_STOP
            State.RESUMED -> ON_PAUSE
            else -> null
        }
    }
}

// ObserverWithState 内部类
class ObserverWithState(
    observer: LifecycleObserver,   // 原始观察者
    initialState: State            // 初始状态
) {
    var state: State = initialState  // 当前状态
    
    // 生命周期事件适配器，负责将事件路由到具体的回调方法
    private val lifecycleEventObserver: LifecycleEventObserver = 
        Lifecycling.lifecycleEventObserver(observer)
    
    // 分发事件
    fun dispatchEvent(owner: LifecycleOwner, event: Event) {
        // 根据事件计算新状态
        val newState = event.targetState
        
        // 取当前状态和新状态的较小值（防止状态超前）
        state = minOf(state, newState)
        
        // 调用适配器的 onStateChanged 方法，最终触发观察者的回调
        lifecycleEventObserver.onStateChanged(owner, event)
        
        // 更新为新状态
        state = newState
    }
}

// LifecycleRegistry 构造函数
class LifecycleRegistry private constructor(
    provider: LifecycleOwner,
    enforceMainThread: Boolean
) : Lifecycle() {
    
    // 使用 WeakReference 持有 LifecycleOwner
    private val lifecycleOwner: WeakReference<LifecycleOwner> = WeakReference(provider)
    
    // ...
}

// 内存引用关系示意
// ┌─────────────────────────────────────────────────────────┐
// │  GC Root                                                │
// │    │                                                    │
// │    ▼                                                    │
// │  Activity ◄──────── 强引用 ──────── LifecycleRegistry   │
// │    │         (如果是强引用，Activity 无法被回收)          │
// │    ▼                                                    │
// │  lifecycle (LifecycleRegistry)                          │
// │    │                                                    │
// │    ▼                                                    │
// │  observerMap ────► Observer                             │
// └─────────────────────────────────────────────────────────┘

Singleton → Observer → LifecycleRegistry → Activity（强引用）

Singleton → Observer → LifecycleRegistry ⇢ Activity（弱引用，可被 GC）

private fun sync() {
    // 获取 LifecycleOwner，如果已被回收则抛异常或提前返回
    val lifecycleOwner = lifecycleOwner.get()
        ?: throw IllegalStateException("LifecycleOwner was GC'd")
    // ...
}

// FastSafeIterableMap 存储 Observer，使用强引用
private val observerMap = FastSafeIterableMap<LifecycleObserver, ObserverWithState>()

class MyActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        lifecycle.addObserver(ObserverA())  // 第1个观察者
    }
    
    override fun onStart() {
        super.onStart()
        lifecycle.addObserver(ObserverB())  // 第2个观察者
    }
}

// 一个典型的 DefaultLifecycleObserver 实现
// 用于管理位置服务的生命周期
class LocationObserver(
    private val context: Context,  // 需要 Context 来获取系统服务
    private val callback: (Location) -> Unit  // 位置更新时的回调
) : DefaultLifecycleObserver {
 
    // LocationManager 实例，延迟初始化
    private var locationManager: LocationManager? = null
 
    // 当 LifecycleOwner 进入 STARTED 状态时触发
    // 此时 Activity/Fragment 对用户可见，适合开始位置监听
    override fun onStart(owner: LifecycleOwner) {
        // 获取系统位置服务
        locationManager = context.getSystemService(Context.LOCATION_SERVICE)
            as LocationManager
        // 开始请求位置更新（实际代码需处理权限）
        // locationManager?.requestLocationUpdates(...)
    }
 
    // 当 LifecycleOwner 即将离开 STARTED 状态时触发
    // 此时 Activity/Fragment 即将不可见，应停止耗电操作
    override fun onStop(owner: LifecycleOwner) {
        // 移除位置更新监听，避免后台耗电
        locationManager?.removeUpdates { }
        // 释放引用
        locationManager = null
    }
}

// ⚠️ 已废弃的写法，仅供历史参考
public class OldStyleObserver implements LifecycleObserver {
    
    @OnLifecycleEvent(Lifecycle.Event.ON_START)
    public void onStartEvent() {
        // 处理 onStart
    }
    
    @OnLifecycleEvent(Lifecycle.Event.ON_STOP)
    public void onStopEvent() {
        // 处理 onStop
    }
}

// ✅ 推荐的现代写法
class ModernObserver : DefaultLifecycleObserver {
    
    // 直接覆写接口方法，编译器保证类型安全
    override fun onStart(owner: LifecycleOwner) {
        // 处理 onStart
    }
    
    override fun onStop(owner: LifecycleOwner) {
        // 处理 onStop
    }
}

// 演示多 Observer 的执行顺序
class MainActivity : AppCompatActivity() {
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        
        // 按顺序注册三个 Observer
        lifecycle.addObserver(ObserverA())  // 第一个注册
        lifecycle.addObserver(ObserverB())  // 第二个注册
        lifecycle.addObserver(ObserverC())  // 第三个注册
        
        // 上升阶段（如 onStart）的执行顺序：A → B → C
        // 下降阶段（如 onStop）的执行顺序：C → B → A
    }
}

// LifecycleEventObserver 的定义
interface LifecycleEventObserver : LifecycleObserver {
    // 统一的事件回调入口
    // event 参数告诉你具体发生了哪个事件
    fun onStateChanged(source: LifecycleOwner, event: Lifecycle.Event)
}

// 使用 LifecycleEventObserver 实现生命周期日志
class LifecycleLogger(private val tag: String) : LifecycleEventObserver {
    
    // 所有生命周期事件都会调用这个方法
    override fun onStateChanged(source: LifecycleOwner, event: Lifecycle.Event) {
        // 统一打印日志，event.name 返回如 "ON_CREATE", "ON_START" 等
        Log.d(tag, "Lifecycle event: ${event.name}")
        
        // 也可以用 when 表达式分别处理
        when (event) {
            Lifecycle.Event.ON_CREATE -> { /* ... */ }
            Lifecycle.Event.ON_DESTROY -> { /* ... */ }
            else -> { /* ... */ }
        }
    }
}

// LifecycleRegistry 内部的简化逻辑（伪代码）
internal class LifecycleRegistry : Lifecycle {
    
    // 当前状态
    private var currentState: State = State.INITIALIZED
    
    // Observer 集合，使用 FastSafeIterableMap 支持迭代中修改
    private val observerMap = FastSafeIterableMap<LifecycleObserver, ObserverWithState>()
    
    // 状态变化时调用
    fun handleLifecycleEvent(event: Event) {
        // 根据 Event 计算目标 State
        val targetState = event.targetState
        // 将当前状态移动到目标状态
        moveToState(targetState)
    }
    
    private fun moveToState(targetState: State) {
        // 更新当前状态
        currentState = targetState
        // 同步所有 Observer 到新状态
        sync()
    }
    
    private fun sync() {
        // 遍历所有 Observer
        for ((observer, observerWithState) in observerMap) {
            // 将每个 Observer 的状态推进到当前状态
            // 期间会触发相应的 Event 回调
            observerWithState.dispatchEvent(this, currentState)
        }
    }
}

// ProcessLifecycleOwner 内部简化逻辑示意
class ProcessLifecycleOwner private constructor() : LifecycleOwner {
    
    // 全局单例，通过 companion object 暴露
    companion object {
        // 延迟时间常量：700 毫秒
        private const val TIMEOUT_MS = 700L
        
        // 单例实例，懒加载
        private val sInstance = ProcessLifecycleOwner()
        
        // 获取单例的静态方法
        @JvmStatic
        fun get(): ProcessLifecycleOwner = sInstance
    }
    
    // 记录处于 started 状态的 Activity 数量
    private var mStartedCounter = 0
    
    // 记录处于 resumed 状态的 Activity 数量
    private var mResumedCounter = 0
    
    // 标记延迟的 ON_PAUSE 是否已被消费
    private var mPauseSent = true
    
    // 标记延迟的 ON_STOP 是否已被消费
    private var mStopSent = true
    
    // 内部持有的 LifecycleRegistry，负责状态管理和事件分发
    private val mRegistry = LifecycleRegistry(this)
    
    // 主线程 Handler，用于延迟任务
    private val mHandler = Handler(Looper.getMainLooper())
    
    // 延迟分发 ON_PAUSE 和 ON_STOP 的 Runnable
    private val mDelayedPauseRunnable = Runnable {
        // 延迟时间到，分发 ON_PAUSE 事件
        dispatchPauseIfNeeded()
        // 紧接着分发 ON_STOP 事件
        dispatchStopIfNeeded()
    }
    
    // 当 Activity onStart() 时被调用
    fun activityStarted() {
        // 计数器加 1
        mStartedCounter++
        // 如果从 0 变为 1，说明应用进入前台
        if (mStartedCounter == 1 && mStopSent) {
            // 将状态推进到 STARTED，分发 ON_START 事件
            mRegistry.handleLifecycleEvent(Lifecycle.Event.ON_START)
            // 标记 ON_STOP 未发送（等待后续可能的后台切换）
            mStopSent = false
        }
    }
    
    // 当 Activity onStop() 时被调用
    fun activityStopped() {
        // 计数器减 1
        mStartedCounter--
        // 延迟分发 ON_STOP，防止 Activity 切换时的误判
        dispatchStopIfNeeded()
    }
    
    private fun dispatchStopIfNeeded() {
        // 只有当所有 Activity 都不在 started 状态时才可能进入后台
        if (mStartedCounter == 0 && !mStopSent) {
            // 发送延迟任务，700ms 后再决定是否真的进入后台
            mHandler.postDelayed(mDelayedPauseRunnable, TIMEOUT_MS)
        }
    }
    
    // 实现 LifecycleOwner 接口，返回内部的 LifecycleRegistry
    override val lifecycle: Lifecycle
        get() = mRegistry
}

// 自定义 Application 类
class MyApplication : Application() {
    
    override fun onCreate() {
        super.onCreate()
        
        // 在 Application 创建时注册进程生命周期观察者
        // ProcessLifecycleOwner.get() 获取全局单例
        // lifecycle 属性返回其内部的 LifecycleRegistry
        ProcessLifecycleOwner.get().lifecycle.addObserver(AppLifecycleObserver())
    }
}
 
// 实现 DefaultLifecycleObserver 接口的观察者
// DefaultLifecycleObserver 提供了所有生命周期回调的默认空实现
// 开发者只需覆写关心的方法
class AppLifecycleObserver : DefaultLifecycleObserver {
    
    // 应用进程首次创建时调用（仅一次）
    // 对应 Lifecycle.Event.ON_CREATE
    override fun onCreate(owner: LifecycleOwner) {
        // 适合做全局初始化，如日志系统、Analytics SDK 等
        Log.d("AppLifecycle", "Application process created")
    }
    
    // 应用进入前台时调用（至少一个 Activity 处于 started 状态）
    // 对应 Lifecycle.Event.ON_START
    override fun onStart(owner: LifecycleOwner) {
        // 应用从后台回到前台
        // 适合刷新数据、恢复网络连接、继续动画等
        Log.d("AppLifecycle", "App moved to foreground")
    }
    
    // 应用获得焦点时调用（至少一个 Activity 处于 resumed 状态）
    // 对应 Lifecycle.Event.ON_RESUME
    override fun onResume(owner: LifecycleOwner) {
        // 应用完全可交互
        // 适合开始传感器监听、定位更新等高功耗操作
        Log.d("AppLifecycle", "App is interactive")
    }
    
    // 应用失去焦点时调用（所有 Activity 都离开 resumed 状态）
    // 对应 Lifecycle.Event.ON_PAUSE
    override fun onPause(owner: LifecycleOwner) {
        // 应用即将失去焦点（可能是弹出系统对话框等）
        // 适合暂停传感器、减少资源消耗
        Log.d("AppLifecycle", "App lost focus")
    }
    
    // 应用进入后台时调用（所有 Activity 都离开 started 状态）
    // 对应 Lifecycle.Event.ON_STOP
    // 注意：此回调会延迟约 700ms 触发
    override fun onStop(owner: LifecycleOwner) {
        // 应用进入后台
        // 适合保存草稿、上传未同步数据、释放资源
        Log.d("AppLifecycle", "App moved to background")
    }
    
    // 注意：ON_DESTROY 永远不会被 ProcessLifecycleOwner 分发
    // 因为进程被杀死时没有机会执行回调
    override fun onDestroy(owner: LifecycleOwner) {
        // 这个方法永远不会被调用
        Log.d("AppLifecycle", "This will never be called")
    }
}

// 追踪用户会话的观察者
class SessionTracker : DefaultLifecycleObserver {
    
    // 会话开始时间戳
    private var sessionStartTime: Long = 0L
    
    override fun onStart(owner: LifecycleOwner) {
        // 记录会话开始时间
        sessionStartTime = System.currentTimeMillis()
        // 上报会话开始事件到 Analytics 平台
        Analytics.trackEvent("session_start")
    }
    
    override fun onStop(owner: LifecycleOwner) {
        // 计算会话时长（毫秒）
        val duration = System.currentTimeMillis() - sessionStartTime
        // 上报会话结束事件，附带时长参数
        Analytics.trackEvent("session_end", mapOf("duration_ms" to duration))
    }
}

// 根据应用前后台状态调整网络策略
class NetworkPolicyObserver(
    private val networkManager: NetworkManager
) : DefaultLifecycleObserver {
    
    override fun onStart(owner: LifecycleOwner) {
        // 应用在前台，启用激进的数据同步策略
        networkManager.setSyncPolicy(SyncPolicy.AGGRESSIVE)
        // 立即拉取最新数据
        networkManager.fetchLatestData()
    }
    
    override fun onStop(owner: LifecycleOwner) {
        // 应用在后台，切换到保守策略，减少网络请求
        networkManager.setSyncPolicy(SyncPolicy.CONSERVATIVE)
        // 取消非关键的网络请求
        networkManager.cancelNonEssentialRequests()
    }
}

// Lifecycle 库内部的 ContentProvider（简化版）
// 这个类定义在 lifecycle-process 模块中
class ProcessLifecycleOwnerInitializer : ContentProvider() {
    
    override fun onCreate(): Boolean {
        // 获取 Application Context
        val appContext = context?.applicationContext
            ?: throw IllegalStateException("Context cannot be null")
        
        // 初始化 ProcessLifecycleOwner
        // 内部会注册 ActivityLifecycleCallbacks
        LifecycleDispatcher.init(appContext)
        ProcessLifecycleOwner.init(appContext)
        
        // 返回 true 表示初始化成功
        return true
    }
    
    // ContentProvider 的其他方法返回空实现
    // 这个 Provider 不提供任何数据，仅用于初始化
    override fun query(...) = null
    override fun insert(...) = null
    override fun delete(...) = 0
    override fun update(...) = 0
    override fun getType(...) = null
}

<!-- lifecycle-process 库的 Manifest 片段 -->
<provider
    android:name="androidx.lifecycle.ProcessLifecycleOwnerInitializer"
    android:authorities="${applicationId}.lifecycle-process"
    android:exported="false"
    android:multiprocess="true" />

// 推荐：使用依赖注入或 Application Context
class GoodObserver(
    private val appContext: Context  // Application Context，安全
) : DefaultLifecycleObserver {
    // ...
}
 
// 避免：直接持有 Activity 引用
class BadObserver(
    private val activity: Activity  // 危险！会导致内存泄漏
) : DefaultLifecycleObserver {
    // ...
}

// LiveData 观察者注册的核心流程示意
class LiveData<T> {
    // 使用 SafeIterableMap 存储观察者，键是 Observer，值是包装后的 ObserverWrapper
    private val mObservers = SafeIterableMap<Observer<in T>, ObserverWrapper>()
    
    // 当前存储的数据值
    private var mData: T? = null
    
    // 数据版本号，每次 setValue 都会递增
    private var mVersion = START_VERSION  // START_VERSION = -1
    
    // 核心注册方法：将 Observer 与 LifecycleOwner 绑定
    fun observe(owner: LifecycleOwner, observer: Observer<in T>) {
        // 检查是否在主线程调用，LiveData 的观察必须在主线程进行
        assertMainThread("observe")
        
        // 如果 LifecycleOwner 已经处于 DESTROYED 状态，直接忽略注册
        if (owner.lifecycle.currentState == Lifecycle.State.DESTROYED) {
            return
        }
        
        // 创建生命周期绑定的观察者包装对象
        val wrapper = LifecycleBoundObserver(owner, observer)
        
        // 尝试将包装对象放入观察者 Map
        // putIfAbsent 返回已存在的值，如果返回 null 表示新增成功
        val existing = mObservers.putIfAbsent(observer, wrapper)
        
        // 如果同一个 Observer 已经绑定到不同的 LifecycleOwner，抛出异常
        if (existing != null && !existing.isAttachedTo(owner)) {
            throw IllegalArgumentException(
                "Cannot add the same observer with different lifecycles"
            )
        }
        
        // 如果已经存在相同的绑定关系，直接返回
        if (existing != null) {
            return
        }
        
        // 将包装对象注册到 Lifecycle，开始监听生命周期事件
        owner.lifecycle.addObserver(wrapper)
    }
}

// LifecycleBoundObserver 包装类的核心实现
class LifecycleBoundObserver(
    private val mOwner: LifecycleOwner,      // 持有 LifecycleOwner 的引用
    observer: Observer<in T>                  // 实际的观察者回调
) : ObserverWrapper(observer), LifecycleEventObserver {
    
    // 判断当前观察者是否处于活跃状态
    // 只有 STARTED 和 RESUMED 状态才被认为是活跃的
    override fun shouldBeActive(): Boolean {
        // isAtLeast 检查当前状态是否 >= STARTED
        return mOwner.lifecycle.currentState.isAtLeast(Lifecycle.State.STARTED)
    }
    
    // 生命周期事件回调，当 LifecycleOwner 状态变化时触发
    override fun onStateChanged(source: LifecycleOwner, event: Lifecycle.Event) {
        // 获取当前的生命周期状态
        val currentState = mOwner.lifecycle.currentState
        
        // 如果已经处于 DESTROYED 状态，自动移除观察者
        if (currentState == Lifecycle.State.DESTROYED) {
            // 调用 LiveData 的 removeObserver 方法清理自己
            removeObserver(mObserver)
            return
        }
        
        // 状态变化可能导致活跃状态改变，需要重新分发数据
        // 使用 while 循环是因为在 activeStateChanged 执行过程中
        // 状态可能再次发生变化
        var prevState: Lifecycle.State? = null
        while (prevState != currentState) {
            prevState = currentState
            // 通知 ObserverWrapper 活跃状态可能发生了变化
            activeStateChanged(shouldBeActive())
            currentState = mOwner.lifecycle.currentState
        }
    }
    
    // 检查此包装对象是否绑定到指定的 LifecycleOwner
    override fun isAttachedTo(owner: LifecycleOwner): Boolean {
        return mOwner === owner
    }
    
    // 从 Lifecycle 中移除自己
    override fun detachObserver() {
        mOwner.lifecycle.removeObserver(this)
    }
}

// setValue 的核心实现
@MainThread  // 强制标注必须在主线程调用
protected fun setValue(value: T) {
    // 断言当前在主线程，否则抛出 IllegalStateException
    assertMainThread("setValue")
    
    // 递增版本号，这是 LiveData 判断数据是否更新的关键
    mVersion++
    
    // 更新内部存储的数据值
    mData = value
    
    // 分发数据变化给所有观察者
    dispatchingValue(null)  // 传入 null 表示通知所有观察者
}

// postValue 的核心实现
protected fun postValue(value: T) {
    // mPendingData 用于暂存待发送的值
    // NOT_SET 是一个特殊的哨兵值，表示没有待处理的数据
    val postTask: Boolean
    
    synchronized(mDataLock) {
        // 检查是否已经有待处理的 post 任务
        postTask = mPendingData === NOT_SET
        
        // 更新待发送的值（注意：这会覆盖之前未处理的值！）
        mPendingData = value
    }
    
    // 如果已经有任务在排队，就不再重复 post
    // 这意味着快速连续调用 postValue 时，只有最后一个值会被分发
    if (!postTask) {
        return
    }
    
    // 通过 ArchTaskExecutor 将任务 post 到主线程
    ArchTaskExecutor.getInstance().postToMainThread(mPostValueRunnable)
}
 
// 在主线程执行的 Runnable
private val mPostValueRunnable = Runnable {
    val newValue: Any?
    synchronized(mDataLock) {
        // 取出待发送的值
        newValue = mPendingData
        // 重置为 NOT_SET，表示没有待处理的数据
        mPendingData = NOT_SET
    }
    // 调用 setValue 完成实际的数据更新（此时已在主线程）
    setValue(newValue as T)
}

// 决定是否通知单个观察者的核心逻辑
private fun considerNotify(observer: ObserverWrapper) {
    // 如果观察者不活跃，直接返回不通知
    if (!observer.mActive) {
        return
    }
    
    // 再次检查观察者的活跃状态（可能在分发过程中发生变化）
    if (!observer.shouldBeActive()) {
        observer.activeStateChanged(false)
        return
    }
    
    // 关键的版本检查：如果观察者已经收到过当前版本的数据，不再重复通知
    // 这就是粘性事件的根源：新观察者的 mLastVersion 是 -1
    // 而 LiveData 的 mVersion 在 setValue 后至少是 0
    // 因此条件 mLastVersion >= mVersion 不成立，会执行通知
    if (observer.mLastVersion >= mVersion) {
        return
    }
    
    // 更新观察者的版本号为当前 LiveData 版本
    observer.mLastVersion = mVersion
    
    // 调用实际的观察者回调
    observer.mObserver.onChanged(mData as T)
}

// SingleLiveEvent 的核心实现思路
class SingleLiveEvent<T> : MutableLiveData<T>() {
    
    // 原子布尔标志，标记事件是否已被处理
    // 使用 AtomicBoolean 保证线程安全
    private val mPending = AtomicBoolean(false)
    
    override fun observe(owner: LifecycleOwner, observer: Observer<in T>) {
        // 包装原始观察者，增加消费检查逻辑
        super.observe(owner, Observer { t ->
            // compareAndSet(true, false)：如果当前值是 true，则设置为 false 并返回 true
            // 这保证了事件只会被消费一次
            if (mPending.compareAndSet(true, false)) {
                observer.onChanged(t)
            }
            // 如果 mPending 已经是 false，说明事件已被消费，不再触发回调
        })
    }
    
    override fun setValue(value: T) {
        // 设置新值前，将标志位设为 true，表示有新事件待处理
        mPending.set(true)
        super.setValue(value)
    }
}

// Event 包装类，支持标记数据是否已被消费
open class Event<out T>(private val content: T) {
    
    // 标记事件是否已被处理，初始为 false
    var hasBeenHandled = false
        private set  // 只允许内部修改
    
    // 获取内容并标记为已处理（只能获取一次）
    // 返回值为 null 表示事件已被消费
    fun getContentIfNotHandled(): T? {
        return if (hasBeenHandled) {
            null  // 已处理过，返回 null
        } else {
            hasBeenHandled = true  // 标记为已处理
            content  // 返回实际内容
        }
    }
    
    // 无论是否已处理，都返回内容（用于需要重复读取的场景）
    fun peekContent(): T = content
}
 
// 在 ViewModel 中使用
class MyViewModel : ViewModel() {
    // 使用 Event 包装一次性事件数据
    private val _navigateToDetail = MutableLiveData<Event<String>>()
    val navigateToDetail: LiveData<Event<String>> = _navigateToDetail
    
    fun onItemClick(itemId: String) {
        // 每次点击创建新的 Event 实例
        _navigateToDetail.value = Event(itemId)
    }
}
 
// 在 Activity/Fragment 中观察
viewModel.navigateToDetail.observe(this) { event ->
    // getContentIfNotHandled() 确保事件只被消费一次
    event.getContentIfNotHandled()?.let { itemId ->
        // 执行导航操作
        navigateToDetailScreen(itemId)
    }
}

class MyViewModel : ViewModel() {
    // SharedFlow with replay = 0，不保留历史数据，避免粘性问题
    private val _events = MutableSharedFlow<UiEvent>()
    val events: SharedFlow<UiEvent> = _events.asSharedFlow()
    
    fun showToast(message: String) {
        viewModelScope.launch {
            // emit 是挂起函数，可以安全地从任何协程调用
            _events.emit(UiEvent.ShowToast(message))
        }
    }
}

// 版本控制在 LiveData 中的应用
abstract class LiveData<T> {
    
    companion object {
        // 起始版本号，表示"从未设置过值"
        const val START_VERSION = -1
    }
    
    // LiveData 当前的版本号
    private var mVersion = START_VERSION
    
    // 当前存储的数据
    private var mData: T = null as T
    
    // 分发逻辑：遍历所有观察者，决定是否通知
    private fun dispatchingValue(initiator: ObserverWrapper?) {
        // mDispatchingValue 防止递归分发
        if (mDispatchingValue) {
            // 如果正在分发过程中又触发了分发，标记需要重新分发
            mDispatchInvalidated = true
            return
        }
        
        mDispatchingValue = true
        do {
            mDispatchInvalidated = false
            
            if (initiator != null) {
                // 只通知指定的观察者（观察者状态变化时使用）
                considerNotify(initiator)
                initiator = null
            } else {
                // 通知所有观察者（setValue 时使用）
                for ((_, observer) in mObservers) {
                    considerNotify(observer)
                    // 如果在通知过程中状态被标记为无效，重新开始分发
                    if (mDispatchInvalidated) {
                        break
                    }
                }
            }
        } while (mDispatchInvalidated)
        
        mDispatchingValue = false
    }
    
    // 判断是否需要通知某个观察者
    private fun considerNotify(observer: ObserverWrapper) {
        // 检查 1：观察者必须处于活跃状态
        if (!observer.mActive) {
            return
        }
        
        // 检查 2：再次确认活跃状态（状态可能在分发过程中改变）
        if (!observer.shouldBeActive()) {
            observer.activeStateChanged(false)
            return
        }
        
        // 检查 3：版本比较——核心逻辑
        // 如果观察者已经处理过当前版本或更新的数据，跳过
        if (observer.mLastVersion >= mVersion) {
            return
        }
        
        // 更新观察者的版本号
        observer.mLastVersion = mVersion
        
        // 执行回调通知
        observer.mObserver.onChanged(mData)
    }
    
    // 获取当前版本号（用于子类或测试）
    fun getVersion(): Int {
        return mVersion
    }
}

时间线示意图（ASCII）：
 
时间 →  T1        T2        T3        T4        T5
        │         │         │         │         │
LiveData状态:
        setValue(V1)       setValue(V2)
        mVersion=0         mVersion=1
        │         │         │         │         │
Observer A:
        订阅       活跃      收到V1    活跃       收到V2
        v=-1      v=-1      v=0       v=0        v=1
        │         │         │         │         │
Observer B:
                           订阅       活跃       收到V2
                           v=-1      v=-1       v=1

class MyViewModel : ViewModel() {
    val toastMessage = MutableLiveData<String>()
    
    fun showWelcome() {
        toastMessage.value = "欢迎使用"
    }
}
 
class MyActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        viewModel.toastMessage.observe(this) { message ->
            Toast.makeText(this, message, Toast.LENGTH_SHORT).show()
        }
        if (savedInstanceState == null) {
            viewModel.showWelcome()  // 首次创建时显示欢迎
        }
    }
}

// 假设 userLiveData 是从 Repository 获取的用户数据
// 类型为 LiveData<User>
val userLiveData: LiveData<User> = userRepository.getUser()
 
// 使用 Transformations.map 将 User 对象转换为显示名称
// 返回类型为 LiveData<String>
val displayNameLiveData: LiveData<String> = Transformations.map(userLiveData) { user ->
    // 这个 lambda 在主线程同步执行
    // 每当 userLiveData 发出新值时，此函数被调用
    // 将 User 对象映射为格式化的显示名称
    "${user.firstName} ${user.lastName} (${user.age}岁)"
}
 
// 在 Activity/Fragment 中观察转换后的数据
// UI 层无需关心原始 User 对象的结构
displayNameLiveData.observe(viewLifecycleOwner) { displayName ->
    // displayName 已经是可以直接显示的字符串
    binding.tvUserName.text = displayName
}

// Transformations.map 的简化源码实现
// 位于 androidx.lifecycle.Transformations
@MainThread
fun <X, Y> map(
    source: LiveData<X>,           // 源 LiveData
    mapFunction: (X) -> Y          // 映射函数
): LiveData<Y> {
    // 创建一个 MediatorLiveData 作为结果容器
    val result = MediatorLiveData<Y>()
    
    // 将源 LiveData 作为数据源添加到 Mediator
    // 当源数据变化时，执行映射并更新 result
    result.addSource(source) { x ->
        // 调用映射函数，将结果设置到 result 中
        result.value = mapFunction(x)
    }
    
    // 返回的 LiveData 会自动跟随源的生命周期
    return result
}

// 用户 ID 的 LiveData，可能由 UI 输入或其他事件触发变化
val userIdLiveData: MutableLiveData<String> = MutableLiveData()
 
// 使用 switchMap 根据 userId 动态获取用户详情
// 每当 userId 变化，自动切换到新的数据源
val userDetailsLiveData: LiveData<UserDetails> = Transformations.switchMap(userIdLiveData) { userId ->
    // 这个 lambda 每当 userId 变化时调用
    // 返回一个新的 LiveData，代表该用户的详情数据
    // 这个 LiveData 可能来自 Room 数据库查询或网络请求
    userRepository.getUserDetails(userId)  // 返回 LiveData<UserDetails>
}
 
// 触发查询：设置新的用户 ID
// switchMap 会自动取消对旧用户数据的订阅
userIdLiveData.value = "user_12345"
 
// 稍后切换到另一个用户
// 之前用户的数据变化不会再影响 userDetailsLiveData
userIdLiveData.value = "user_67890"

// Transformations.switchMap 的简化源码实现
@MainThread
fun <X, Y> switchMap(
    source: LiveData<X>,                    // 源 LiveData
    switchMapFunction: (X) -> LiveData<Y>   // 返回 LiveData 的映射函数
): LiveData<Y> {
    val result = MediatorLiveData<Y>()
    
    // 用于跟踪当前订阅的数据源
    var currentSource: LiveData<Y>? = null
    
    // 监听源数据的变化
    result.addSource(source) { x ->
        // 根据新值获取新的数据源
        val newLiveData: LiveData<Y> = switchMapFunction(x)
        
        // 如果数据源没有变化，无需处理
        if (currentSource === newLiveData) {
            return@addSource
        }
        
        // 移除对旧数据源的订阅（关键步骤！）
        currentSource?.let { oldSource ->
            result.removeSource(oldSource)
        }
        
        // 更新当前数据源引用
        currentSource = newLiveData
        
        // 订阅新的数据源
        result.addSource(newLiveData) { y ->
            // 将新数据源的值传递给结果
            result.value = y
        }
    }
    
    return result
}

// 场景：用户个人资料页面需要同时展示用户信息和用户订单数量
// 这两个数据来自不同的数据源，需要合并后统一展示
 
// 数据源 1：用户基本信息
val userLiveData: LiveData<User> = userRepository.getUser()
 
// 数据源 2：用户订单数量
val orderCountLiveData: LiveData<Int> = orderRepository.getOrderCount()
 
// 合并后的 UI 状态
data class ProfileUiState(
    val user: User? = null,       // 用户信息
    val orderCount: Int = 0,      // 订单数量
    val isComplete: Boolean = false  // 数据是否完整
)
 
// 使用 MediatorLiveData 合并多个数据源
val profileStateLiveData: MediatorLiveData<ProfileUiState> = MediatorLiveData<ProfileUiState>().apply {
    // 初始状态
    value = ProfileUiState()
    
    // 添加用户数据源
    // 当用户数据变化时，更新合并状态中的 user 字段
    addSource(userLiveData) { user ->
        // 获取当前状态，如果为 null 则使用默认值
        val currentState = value ?: ProfileUiState()
        // 更新 user 字段，保留其他字段不变
        value = currentState.copy(
            user = user,
            // 当两个数据源都有值时，标记为完整
            isComplete = user != null && currentState.orderCount > 0
        )
    }
    
    // 添加订单数量数据源
    // 当订单数量变化时，更新合并状态中的 orderCount 字段
    addSource(orderCountLiveData) { count ->
        val currentState = value ?: ProfileUiState()
        value = currentState.copy(
            orderCount = count,
            isComplete = currentState.user != null && count > 0
        )
    }
}
 
// 在 UI 层只需观察一个 LiveData
// 无需关心数据来自哪里，如何合并
profileStateLiveData.observe(viewLifecycleOwner) { state ->
    if (state.isComplete) {
        binding.tvUserName.text = state.user?.name
        binding.tvOrderCount.text = "订单数：${state.orderCount}"
        binding.progressBar.visibility = View.GONE
    } else {
        binding.progressBar.visibility = View.VISIBLE
    }
}

// MediatorLiveData 内部结构示意（简化）
class MediatorLiveData<T> : MutableLiveData<T>() {
    
    // 存储所有数据源及其观察者的映射
    // 使用 SafeIterableMap 支持在遍历时修改
    private val sources: SafeIterableMap<LiveData<*>, Source<*>> = SafeIterableMap()
    
    // Source 内部类：封装数据源和对应的观察者
    private class Source<V>(
        val liveData: LiveData<V>,           // 被观察的数据源
        val observer: Observer<in V>         // 数据变化时的回调
    ) : Observer<V> {
        var version: Int = START_VERSION     // 用于防止重复通知
        var plugged: Boolean = false         // 是否已连接（正在观察）
        
        // 开始观察数据源
        fun plug() {
            // 使用 observeForever，因为生命周期由 MediatorLiveData 管理
            liveData.observeForever(this)
            plugged = true
        }
        
        // 停止观察数据源
        fun unplug() {
            liveData.removeObserver(this)
            plugged = false
        }
        
        // Observer 接口实现
        override fun onChanged(value: V) {
            // 检查版本，避免重复通知
            if (version != liveData.version) {
                version = liveData.version
                // 调用用户提供的回调
                observer.onChanged(value)
            }
        }
    }
    
    // 添加数据源
    @MainThread
    fun <S> addSource(source: LiveData<S>, onChanged: Observer<in S>) {
        val e = Source(source, onChanged)
        val existing = sources.putIfAbsent(source, e)
        
        // 检查是否重复添加同一个源
        require(existing == null || existing.observer === onChanged) {
            "已经添加了相同的数据源但使用了不同的观察者"
        }
        
        // 如果 Mediator 当前有活跃观察者，立即开始观察源
        if (hasActiveObservers()) {
            e.plug()
        }
    }
    
    // 移除数据源
    @MainThread
    fun <S> removeSource(source: LiveData<S>) {
        val e = sources.remove(source)
        e?.unplug()  // 停止观察
    }
    
    // 当 MediatorLiveData 变为活跃时（有活跃观察者）
    override fun onActive() {
        // 开始观察所有已添加的数据源
        for ((_, source) in sources) {
            source.plug()
        }
    }
    
    // 当 MediatorLiveData 变为不活跃时（无活跃观察者）
    override fun onInactive() {
        // 停止观察所有数据源，释放资源
        for ((_, source) in sources) {
            source.unplug()
        }
    }
}

// 构建数据转换链
// 源数据 -> 过滤 -> 映射 -> 格式化
val displayTextLiveData: LiveData<String> = Transformations.switchMap(categoryIdLiveData) { categoryId ->
    // 第一步：根据类别 ID 获取商品列表
    productRepository.getProductsByCategory(categoryId)
}.let { productsLiveData ->
    // 第二步：过滤出库存大于 0 的商品
    Transformations.map(productsLiveData) { products ->
        products.filter { it.stock > 0 }
    }
}.let { availableProductsLiveData ->
    // 第三步：映射为显示文本
    Transformations.map(availableProductsLiveData) { products ->
        if (products.isEmpty()) {
            "暂无可用商品"
        } else {
            "共 ${products.size} 件商品可购买"
        }
    }
}

// 传统方式：Activity 中注册位置监听
class LocationActivity : AppCompatActivity() {
    
    // 位置管理器实例，全局单例
    private val locationManager = LocationManager.getInstance()
    
    // 位置变化回调，持有 Activity 的隐式引用
    private val locationCallback = object : LocationCallback {
        override fun onLocationChanged(location: Location) {
            // 更新 UI，此处 this@LocationActivity 被隐式持有
            updateLocationUI(location)
        }
    }
    
    override fun onStart() {
        super.onStart()
        // 注册监听
        locationManager.addCallback(locationCallback)
    }
    
    override fun onStop() {
        super.onStop()
        // 必须手动取消注册，否则会内存泄漏！
        locationManager.removeCallback(locationCallback)
    }
}

// LiveData.observe() 源码简化版
public void observe(LifecycleOwner owner, Observer<? super T> observer) {
    // 断言：必须在主线程调用
    assertMainThread("observe");
    
    // 关键判断：如果 owner 已经处于 DESTROYED 状态，直接忽略，不添加观察者
    if (owner.getLifecycle().getCurrentState() == DESTROYED) {
        return;
    }
    
    // 创建生命周期绑定的观察者包装器
    LifecycleBoundObserver wrapper = new LifecycleBoundObserver(owner, observer);
    
    // 将 wrapper 存入观察者 Map
    ObserverWrapper existing = mObservers.putIfAbsent(observer, wrapper);
    
    // 防止同一个 observer 被绑定到不同的 owner
    if (existing != null && !existing.isAttachedTo(owner)) {
        throw new IllegalArgumentException("Cannot add the same observer with different lifecycles");
    }
    
    // 将 wrapper 注册为 owner 的生命周期观察者
    owner.getLifecycle().addObserver(wrapper);
}

// LifecycleBoundObserver 内部类源码简化
class LifecycleBoundObserver extends ObserverWrapper implements LifecycleEventObserver {
    
    // 持有宿主的引用
    final LifecycleOwner mOwner;
    
    LifecycleBoundObserver(LifecycleOwner owner, Observer<? super T> observer) {
        super(observer);
        mOwner = owner;
    }
    
    // 判断当前是否处于活跃状态（至少 STARTED）
    @Override
    boolean shouldBeActive() {
        return mOwner.getLifecycle().getCurrentState().isAtLeast(STARTED);
    }
    
    // 核心：监听生命周期事件
    @Override
    public void onStateChanged(LifecycleOwner source, Lifecycle.Event event) {
        // 获取当前生命周期状态
        Lifecycle.State currentState = mOwner.getLifecycle().getCurrentState();
        
        // 如果状态为 DESTROYED，自动移除观察者
        if (currentState == DESTROYED) {
            // 调用 LiveData 的 removeObserver 方法
            removeObserver(mObserver);
            return;
        }
        
        // 否则，根据活跃状态决定是否分发数据
        activeStateChanged(shouldBeActive());
    }
    
    // 判断是否绑定到指定 owner
    @Override
    boolean isAttachedTo(LifecycleOwner owner) {
        return mOwner == owner;
    }
    
    // 解除与 owner 的绑定
    @Override
    void detachObserver() {
        mOwner.getLifecycle().removeObserver(this);
    }
}

// Lifecycle.State 枚举定义
enum class State {
    DESTROYED,   // Activity 已销毁
    INITIALIZED, // Activity 已创建但未调用 onCreate
    CREATED,     // onCreate 已调用，但未调用 onStart
    STARTED,     // onStart 已调用，但未调用 onResume
    RESUMED;     // onResume 已调用，Activity 完全可见可交互
    
    // 判断当前状态是否至少达到某个级别
    fun isAtLeast(state: State): Boolean {
        return compareTo(state) >= 0
    }
}

// 判断逻辑：状态值 >= STARTED 即为活跃
override fun shouldBeActive(): Boolean {
    return mOwner.getLifecycle().getCurrentState().isAtLeast(STARTED)
}

// LiveData 内部数据分发逻辑
private void considerNotify(ObserverWrapper observer) {
    // 第一道门：如果观察者不活跃，直接返回
    if (!observer.mActive) {
        return;
    }
    
    // 第二道门：再次检查生命周期状态（可能在分发过程中状态变化）
    if (!observer.shouldBeActive()) {
        observer.activeStateChanged(false);
        return;
    }
    
    // 第三道门：版本检查，防止重复分发
    if (observer.mLastVersion >= mVersion) {
        return;
    }
    
    // 更新观察者的版本号
    observer.mLastVersion = mVersion;
    
    // 真正调用 Observer.onChanged()
    observer.mObserver.onChanged((T) mData);
}

// 活跃状态变化处理
void activeStateChanged(boolean newActive) {
    // 如果状态没变，不处理
    if (newActive == mActive) {
        return;
    }
    
    // 更新活跃标记
    mActive = newActive;
    
    // 更新 LiveData 的活跃观察者计数
    changeActiveCounter(mActive ? 1 : -1);
    
    // 如果变为活跃，立即尝试分发最新数据
    if (mActive) {
        dispatchingValue(this);
    }
}

class DataRepository {
    
    private val dataLiveData = MutableLiveData<Data>()
    
    // 使用 observeForever 的观察者
    private val foreverObserver = Observer<Data> { data ->
        // 处理数据...
    }
    
    fun startObserving() {
        // 注意：这种方式不会自动清理！
        dataLiveData.observeForever(foreverObserver)
    }
    
    fun stopObserving() {
        // 必须手动移除，否则会导致泄漏
        dataLiveData.removeObserver(foreverObserver)
    }
}

class MyViewModel : ViewModel() {
    
    private val repository = DataRepository()
    private val _uiState = MutableLiveData<UiState>()
    val uiState: LiveData<UiState> = _uiState
    
    private val dataObserver = Observer<Data> { data ->
        _uiState.value = UiState.Success(data)
    }
    
    init {
        // 在 ViewModel 中监听 Repository 的 LiveData
        repository.dataLiveData.observeForever(dataObserver)
    }
    
    override fun onCleared() {
        super.onCleared()
        // ViewModel 销毁时手动移除观察者
        repository.dataLiveData.removeObserver(dataObserver)
    }
}

class MyFragment : Fragment() {
    
    private val viewModel: MyViewModel by viewModels()
    
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        
        // 正确：使用 viewLifecycleOwner，Observer 与 View 生命周期绑定
        viewModel.uiState.observe(viewLifecycleOwner) { state ->
            updateUI(state)
        }
        
        // 错误：使用 this，Observer 与 Fragment 实例绑定
        // viewModel.uiState.observe(this) { state -> ... }
    }
}

// 内存引用关系 (无泄漏情况)
//
// ┌─────────────────────────────────────────────────────────┐
// │                    ViewModel (长生命周期)                 │
// │  ┌───────────────────────────────────────────────────┐  │
// │  │  MutableLiveData                                   │  │
// │  │  ├── mData: T                                     │  │
// │  │  ├── mVersion: Int                                │  │
// │  │  └── mObservers: SafeIterableMap                  │  │
// │  │       └── [Observer] → LifecycleBoundObserver ────┼──┼─── 弱引用 ──┐
// │  └───────────────────────────────────────────────────┘  │             │
// └─────────────────────────────────────────────────────────┘             │
//                                                                         │
// ┌─────────────────────────────────────────────────────────┐             │
// │                    Activity (短生命周期)                  │◄────────────┘
// │  ┌───────────────────────────────────────────────────┐  │
// │  │  LifecycleRegistry                                 │  │
// │  │  └── mObserverMap                                  │  │
// │  │       └── LifecycleBoundObserver ◄─── 弱引用 ──────┼──┼── (循环引用被打破)
// │  └───────────────────────────────────────────────────┘  │
// │  ┌───────────────────────────────────────────────────┐  │
// │  │  Observer Lambda (匿名类)                          │  │
// │  │  └── 隐式引用 this@Activity                        │  │
// │  └───────────────────────────────────────────────────┘  │
// └─────────────────────────────────────────────────────────┘
//
// 当 Activity 销毁时：
// 1. LifecycleRegistry 分发 ON_DESTROY 事件
// 2. LifecycleBoundObserver.onStateChanged() 被调用
// 3. LifecycleBoundObserver 从 LiveData.mObservers 中移除自己
// 4. Observer Lambda 引用断开，可被 GC 回收
// 5. Activity 实例无外部强引用，可被 GC 回收

// LifecycleRegistry 内部的观察者存储
private FastSafeIterableMap<LifecycleObserver, ObserverWithState> mObserverMap =
        new FastSafeIterableMap<>();
 
// 添加观察者（强引用）
public void addObserver(LifecycleObserver observer) {
    // ...
    ObserverWithState statefulObserver = new ObserverWithState(observer, initialState);
    // 强引用存储
    ObserverWithState previous = mObserverMap.putIfAbsent(observer, statefulObserver);
    // ...
}

// liveData 构建器的函数签名
// context: 协程上下文，默认为 EmptyCoroutineContext
// timeoutInMs: 超时时间（毫秒），当没有活跃观察者时，协程会延迟取消
// block: 挂起函数代码块，在其中执行异步操作并发射数据
public fun <T> liveData(
    context: CoroutineContext = EmptyCoroutineContext,  // 可指定调度器如 Dispatchers.IO
    timeoutInMs: Long = DEFAULT_TIMEOUT,                // 默认 5000ms
    @BuilderInference block: suspend LiveDataScope<T>.() -> Unit  // 核心逻辑代码块
): LiveData<T>

// 典型使用示例：在 ViewModel 中获取用户数据
class UserViewModel(
    private val repository: UserRepository  // 数据仓库
) : ViewModel() {
 
    // 使用 liveData 构建器创建响应式数据源
    val user: LiveData<User> = liveData(
        context = Dispatchers.IO,  // 指定在 IO 线程池执行
        timeoutInMs = 5000L        // 配置变更时保持 5 秒
    ) {
        // 这个代码块是一个挂起函数环境
        // 只有当存在活跃观察者时才会执行
        
        // 首先发射一个加载中的占位数据（可选）
        emit(User.loading())
        
        // 执行耗时的网络请求，这是一个挂起函数
        val userData = repository.fetchUser()
        
        // 将结果发射给所有观察者
        emit(userData)
    }
}