UI 状态容器

// ========== ViewModel：持有数据 + 处理业务逻辑 ==========
class NewsViewModel(
    private val repository: NewsRepository  // 通过构造函数注入数据源依赖
) : ViewModel() {
 
    // 内部可变状态，类型为 MutableStateFlow，仅 ViewModel 自身可以修改
    private val _uiState = MutableStateFlow(NewsUiState())
 
    // 对外暴露不可变的 StateFlow，UI 层只能观察，不能直接修改
    // 这就是"单一信息源"（Single Source of Truth）思想的体现
    val uiState: StateFlow<NewsUiState> = _uiState.asStateFlow()
 
    // init 块在 ViewModel 构造时执行，自动触发首次数据加载
    init {
        loadNews()
    }
 
    // 封装加载逻辑：发起协程请求，处理 成功/失败 两种情况
    fun loadNews() {
        // viewModelScope 是 ViewModel 专属的协程作用域
        // 当 ViewModel 被清理时（onCleared），该作用域会自动取消所有协程
        viewModelScope.launch {
            // 先将 UI 状态更新为"加载中"，UI 层观察到后会显示 Loading 指示器
            _uiState.value = _uiState.value.copy(isLoading = true)
            try {
                // 调用 Repository 获取新闻数据（可能来自网络或本地缓存）
                val articles = repository.getLatestNews()
                // 请求成功：更新状态为"有数据"，关闭加载指示
                _uiState.value = NewsUiState(articles = articles, isLoading = false)
            } catch (e: Exception) {
                // 请求失败：更新状态为"有错误"，携带错误信息供 UI 展示
                _uiState.value = _uiState.value.copy(
                    isLoading = false,
                    errorMessage = e.message
                )
            }
        }
    }
}
 
// UI 状态的数据类，将"屏幕上需要展示什么"完整描述出来
data class NewsUiState(
    val articles: List<Article> = emptyList(),  // 新闻列表数据
    val isLoading: Boolean = false,              // 是否正在加载
    val errorMessage: String? = null             // 错误信息（null 表示无错误）
)

// ========== Activity：纯粹的 UI 控制器 ==========
class NewsActivity : AppCompatActivity() {
 
    // 使用 by viewModels() 委托获取 ViewModel 实例
    // 内部通过 ViewModelProvider 确保同一 Activity 生命周期内返回同一实例
    private val viewModel: NewsViewModel by viewModels()
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_news)
 
        // 使用 repeatOnLifecycle 在 STARTED 状态下收集 StateFlow
        // 当 Activity 进入 STOPPED 状态时自动暂停收集，避免后台刷新 UI
        lifecycleScope.launch {
            repeatOnLifecycle(Lifecycle.State.STARTED) {
                // collect 是挂起函数，每当 uiState 变化时，lambda 被调用
                viewModel.uiState.collect { state ->
                    // 根据状态渲染 UI：这就是 Activity 的全部职责
                    updateUI(state)
                }
            }
        }
    }
 
    // UI 渲染逻辑：根据 UiState 决定显示什么
    private fun updateUI(state: NewsUiState) {
        // 如果正在加载，显示进度条
        progressBar.isVisible = state.isLoading
        // 将新闻列表数据提交给 RecyclerView 的 Adapter
        newsAdapter.submitList(state.articles)
        // 如果有错误信息，用 Snackbar 提示用户
        state.errorMessage?.let { showSnackbar(it) }
    }
}

// ===== ComponentActivity 源码（简化版） =====
 
// ComponentActivity 内部定义的静态数据类，用于封装需要跨配置变更保留的对象
static final class NonConfigurationInstances {
    // 核心字段：ViewModelStore 引用
    Object custom;           // 留给子类自定义使用（已废弃的 onRetainCustomNonConfigurationInstance）
    ViewModelStore viewModelStore;  // ← 这就是 ViewModel 存活的关键！
}
 
// ---- 保存阶段（Activity 即将因配置变更被销毁时，由系统调用）----
@Override
@Nullable
public final Object onRetainNonConfigurationInstance() {
    // 取出当前 Activity 持有的 ViewModelStore
    ViewModelStore viewModelStore = mViewModelStore;
 
    // 如果当前 Activity 自身没有创建过 ViewModelStore，
    // 尝试从上一轮的 NonConfigurationInstances 中继承（链式保留）
    if (viewModelStore == null) {
        NonConfigurationInstances nc = (NonConfigurationInstances) getLastNonConfigurationInstance();
        if (nc != null) {
            viewModelStore = nc.viewModelStore;
        }
    }
 
    // 如果确实没有任何 ViewModel 被创建过，返回 null，无需保留
    if (viewModelStore == null) {
        return null;
    }
 
    // 将 ViewModelStore 打包到 NonConfigurationInstances 中返回给系统
    NonConfigurationInstances nci = new NonConfigurationInstances();
    nci.viewModelStore = viewModelStore;
    return nci;  // 系统会将此对象暂存到 ActivityClientRecord 中
}
 
// ---- 恢复阶段（新 Activity 创建时，在 onCreate 中尝试恢复）----
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
 
    // 尝试从系统暂存中取回上一轮的 NonConfigurationInstances
    NonConfigurationInstances nc = (NonConfigurationInstances) getLastNonConfigurationInstance();
    if (nc != null && nc.viewModelStore != null) {
        // 如果存在，直接将旧的 ViewModelStore 赋给新 Activity 实例
        // 这意味着所有旧 ViewModel 实例都原封不动地 "移交" 过来了
        mViewModelStore = nc.viewModelStore;
    }
    // ... 其他初始化逻辑
}

// ===== 共享 ViewModel =====
// 持有两个 Fragment 需要共享的数据
class SharedViewModel : ViewModel() {
 
    // 选中的文章条目，初始值为 null，表示尚未选中
    private val _selectedArticle = MutableStateFlow<Article?>(null)
 
    // 对外暴露不可变 StateFlow，两个 Fragment 都可以 collect
    val selectedArticle: StateFlow<Article?> = _selectedArticle.asStateFlow()
 
    // 提供一个方法供 ListFragment 调用，设置选中项
    fun selectArticle(article: Article) {
        _selectedArticle.value = article
    }
}
 
// ===== ListFragment：生产数据（设置选中项）=====
class ListFragment : Fragment() {
 
    // 关键点：activityViewModels() 使用 Activity 级别的 ViewModelStore
    // 这确保了获取到的 SharedViewModel 实例与 Activity 作用域绑定
    private val sharedViewModel: SharedViewModel by activityViewModels()
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        // 用户点击列表项时，通过 ViewModel 设置选中的文章
        // DetailFragment 会自动收到通知（因为它观察的是同一个 StateFlow）
        recyclerView.setOnItemClickListener { article ->
            sharedViewModel.selectArticle(article)
        }
    }
}
 
// ===== DetailFragment：消费数据（观察选中项）=====
class DetailFragment : Fragment() {
 
    // 同样使用 activityViewModels()，获取的是同一个 SharedViewModel 实例
    private val sharedViewModel: SharedViewModel by activityViewModels()
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        // 收集 selectedArticle 的变化，一旦 ListFragment 设置了选中项，
        // 这里就会收到最新值并刷新详情 UI
        viewLifecycleOwner.lifecycleScope.launch {
            viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
                sharedViewModel.selectedArticle.collect { article ->
                    // article 不为 null 时，显示详情内容
                    article?.let { displayDetail(it) }
                }
            }
        }
    }
}

// ===== 在 Navigation Graph 作用域内共享 =====
class CheckoutFragment : Fragment() {
 
    // navGraphViewModels 使用指定 Navigation Graph 的 ViewModelStore
    // 该图内的所有 Fragment 获取到的是同一个 CheckoutViewModel 实例
    // 当用户导航离开这个 Graph 时，ViewModel 被自动清理
    private val checkoutVM: CheckoutViewModel by navGraphViewModels(R.id.checkout_graph)
 
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        // 所有 checkout 流程中的 Fragment（选地址、选支付方式、确认下单）
        // 都可以通过同一个 checkoutVM 共享订单数据
        viewLifecycleOwner.lifecycleScope.launch {
            viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) {
                checkoutVM.orderState.collect { renderOrder(it) }
            }
        }
    }
}

// ===== Framework 层 (android.app.Activity) =====
// 这是系统 Activity 内部定义的 NonConfigurationInstances
// ActivityThread 在配置变更时直接操作的就是这个对象
static final class NonConfigurationInstances {
    // 存放子类（ComponentActivity）自定义的保留对象
    // 类型为 Object，Framework 不关心具体内容
    Object activity;
    // 存放子 Activity（已废弃的 ActivityGroup 机制）的保留数据
    HashMap<String, Object> children;
    // 存放 Fragment 的保留数据（旧版 Fragment 机制）
    FragmentManagerNonConfig fragments;
    // 存放 Loader 的保留数据
    ArrayMap<String, LoaderManager> loaders;
    // 存放 VoiceInteractor（语音交互）的保留数据
    VoiceInteractor voiceInteractor;
}
 
// ===== AndroidX 层 (androidx.activity.ComponentActivity) =====
// 这是 Jetpack ComponentActivity 定义的 NonConfigurationInstances
// 它作为 Object 被塞进上面 Framework 层的 activity 字段中
static final class NonConfigurationInstances {
    // 这里就是 ViewModelStore 真正的栖身之所
    Object custom;           // 开发者自定义的保留对象（通过 onRetainCustomNonConfigurationInstance）
    ViewModelStore viewModelStore;  // ★ 核心：ViewModel 容器
}

// ActivityThread.java 中的核心保留逻辑（简化版）
// 在 Activity 即将被销毁前调用
ActivityClientRecord performDestroyActivity(IBinder token, boolean finishing, ...) {
    // 通过 token 找到当前 Activity 对应的 ClientRecord
    ActivityClientRecord r = mActivities.get(token);
 
    // ★ 关键步骤：如果不是用户主动 finish，而是配置变更导致的销毁
    // 则调用 retainNonConfigurationInstances() 保留数据
    if (!finishing) {
        // 这个方法会沿调用链收集所有需要保留的对象
        // 返回 Activity.NonConfigurationInstances（第一层）
        r.lastNonConfigurationInstances = r.activity.retainNonConfigurationInstances();
    }
 
    // 之后才真正执行 onDestroy()
    // 此时 ViewModelStore 已经安全转移到 r 中
    performDestroyActivity(r, ...);
 
    // r (ActivityClientRecord) 不会被移除，它还在 mActivities 这个 Map 中
    // 等待新 Activity 创建时复用
    return r;
}

// ComponentActivity.java（AndroidX 层）
// 这个方法由 Activity.retainNonConfigurationInstances() 回调
@Override
public final Object onRetainNonConfigurationInstance() {
    // 获取开发者自定义的保留对象（如果有的话）
    Object custom = onRetainCustomNonConfigurationInstance();
 
    // 拿到当前持有的 ViewModelStore
    ViewModelStore viewModelStore = mViewModelStore;
 
    // 如果当前实例还没创建过 ViewModelStore
    // 则尝试从上一次配置变更中继承（避免丢失）
    if (viewModelStore == null) {
        NonConfigurationInstances nc = (NonConfigurationInstances) getLastNonConfigurationInstance();
        if (nc != null) {
            viewModelStore = nc.viewModelStore;
        }
    }
 
    // 如果既没有自定义保留对象，也没有 ViewModelStore
    // 就返回 null，表示没有需要保留的东西
    if (custom == null && viewModelStore == null) {
        return null;
    }
 
    // 把 ViewModelStore 包装进 AndroidX 层的 NonConfigurationInstances
    NonConfigurationInstances nci = new NonConfigurationInstances();
    nci.custom = custom;
    nci.viewModelStore = viewModelStore;  // ★ ViewModelStore 在此被保留
    return nci;
}

// ComponentActivity.onCreate() 中的恢复逻辑（简化版）
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
 
    // 尝试从上一次配置变更中恢复 NonConfigurationInstances
    NonConfigurationInstances nc = (NonConfigurationInstances) getLastNonConfigurationInstance();
    if (nc != null && nc.viewModelStore != null) {
        // ★ 如果有保留的 ViewModelStore，直接复用
        // 这里的 ViewModelStore 和旧 Activity 中的是同一个对象引用
        mViewModelStore = nc.viewModelStore;
    }
}

// ViewModelStore.java —— ViewModel 的容器
// 整个类非常精简，本质上就是一个带有清理能力的 HashMap 包装器
public class ViewModelStore {
 
    // ★ 核心存储结构：以 String 为 key，以 ViewModel 为 value
    // key 的格式通常为 "androidx.lifecycle.ViewModelProvider.DefaultKey:全限定类名"
    private final HashMap<String, ViewModel> mMap = new HashMap<>();
 
    // 存入一个 ViewModel（包级可见，不对外暴露）
    final void put(String key, ViewModel viewModel) {
        // 如果同一个 key 已经有旧的 ViewModel，先把旧的关闭
        // 这确保了不会出现"孤儿" ViewModel 占用资源的情况
        ViewModel oldViewModel = mMap.put(key, viewModel);
        if (oldViewModel != null) {
            // 调用旧 ViewModel 的 onCleared()，释放资源
            oldViewModel.onCleared();
        }
    }
 
    // 根据 key 获取 ViewModel（包级可见）
    final ViewModel get(String key) {
        return mMap.get(key);
    }
 
    // 获取所有 key 的集合
    Set<String> keys() {
        return new HashSet<>(mMap.keySet());
    }
 
    // ★ 清空所有 ViewModel，并依次调用每个 ViewModel 的 onCleared()
    // 当 Activity 真正结束（不是配置变更）时调用
    public final void clear() {
        for (ViewModel vm : mMap.values()) {
            // 通知每个 ViewModel 进行资源清理
            vm.clear();  // 内部会调用 onCleared() 和取消 CoroutineScope
        }
        // 清空整个 Map
        mMap.clear();
    }
}

// ComponentActivity 构造函数中注册的生命周期观察者（简化版）
getLifecycle().addObserver(new LifecycleEventObserver() {
    @Override
    public void onStateChanged(LifecycleOwner source, Lifecycle.Event event) {
        // 只在 ON_DESTROY 事件时处理
        if (event == Lifecycle.Event.ON_DESTROY) {
            // ★ 关键判断：是否正在配置变更
            // isChangingConfigurations() 为 true → 配置变更 → 不清理
            // isChangingConfigurations() 为 false → 真正销毁 → 清理
            if (!isChangingConfigurations()) {
                getViewModelStore().clear();
            }
        }
    }
});

// 使用自定义 key 创建同类型 ViewModel 的多个实例
// 每个 key 对应 ViewModelStore HashMap 中的一个独立条目
val viewModelTab1: ItemViewModel = ViewModelProvider(this).get(
    "tab_1",                    // 自定义 key，唯一标识这个实例
    ItemViewModel::class.java   // ViewModel 类型
)
 
val viewModelTab2: ItemViewModel = ViewModelProvider(this).get(
    "tab_2",                    // 不同的 key → 不同的 ViewModel 实例
    ItemViewModel::class.java   // 同一个类型
)
 
// 此时 ViewModelStore 的 HashMap 中有两个条目：
// "tab_1" → ItemViewModel@A
// "tab_2" → ItemViewModel@B
// 它们是完全独立的实例，互不影响

// ViewModelStoreOwner.java —— 表示"我拥有一个 ViewModelStore"的契约接口
public interface ViewModelStoreOwner {
    // 返回该 Owner 持有的 ViewModelStore
    // 实现类必须保证在配置变更期间返回同一个实例
    @NonNull
    ViewModelStore getViewModelStore();
}

// Fragment 中获取 Activity 级别的共享 ViewModel
// ★ 关键：owner 是 requireActivity()，因此访问的是 Activity 的 ViewModelStore
val sharedVM: SharedViewModel by activityViewModels()
// 等价于: ViewModelProvider(requireActivity()).get(SharedViewModel::class.java)
 
// Fragment 自己的私有 ViewModel
// ★ owner 是 this（Fragment 自身），访问的是 Fragment 的 ViewModelStore
val privateVM: DetailViewModel by viewModels()
// 等价于: ViewModelProvider(this).get(DetailViewModel::class.java)

// ViewModelProvider.Factory 接口定义（简化版）
// 位于 androidx.lifecycle 包中
public interface Factory {
    // 核心方法：根据传入的 Class 类型，创建并返回对应的 ViewModel 实例
    // modelClass —— 需要创建的 ViewModel 的 Class 对象
    fun <T : ViewModel> create(modelClass: Class<T>): T
}

// ViewModelProvider 核心逻辑（基于 lifecycle-viewmodel 2.5+ 简化）
class ViewModelProvider(
    private val store: ViewModelStore,   // 缓存容器，持有 HashMap<String, ViewModel>
    private val factory: Factory         // 工厂，负责实例化 ViewModel
) {
    // 默认 key 前缀，避免不同类的 className 冲突
    companion object {
        private const val DEFAULT_KEY = "androidx.lifecycle.ViewModelProvider.DefaultKey"
    }
 
    // 外部调用的入口方法
    fun <T : ViewModel> get(modelClass: Class<T>): T {
        // 用「固定前缀 + 类的全限定名」作为唯一 key
        val key = DEFAULT_KEY + ":" + modelClass.canonicalName
        return get(key, modelClass)
    }
 
    fun <T : ViewModel> get(key: String, modelClass: Class<T>): T {
        // 第一步：尝试从 ViewModelStore 缓存中获取
        var viewModel = store.get(key)
 
        // 第二步：如果缓存命中，且类型匹配，直接返回（强转）
        if (modelClass.isInstance(viewModel)) {
            @Suppress("UNCHECKED_CAST")
            return viewModel as T
        }
 
        // 第三步：缓存未命中，委托 Factory 创建新实例
        viewModel = factory.create(modelClass)
 
        // 第四步：将新实例存入 ViewModelStore，下次直接复用
        store.put(key, viewModel)
 
        @Suppress("UNCHECKED_CAST")
        return viewModel as T
    }
}

// 一个需要 Repository 依赖的 ViewModel
class UserProfileViewModel(
    private val userRepository: UserRepository  // 构造函数参数：用户数据仓库
) : ViewModel() {
 
    // 通过 repository 获取用户信息，返回 StateFlow 供 UI 层观察
    val userProfile: StateFlow<UserProfile?> = userRepository
        .getUserProfile()                        // 从仓库获取数据流
        .stateIn(                                // 转换为 StateFlow
            scope = viewModelScope,              // 绑定到 ViewModel 协程作用域
            started = SharingStarted.WhileSubscribed(5000), // 下游无订阅者 5s 后停止
            initialValue = null                  // 初始值为 null
        )
}

// 自定义 Factory：为 UserProfileViewModel 注入 UserRepository
class UserProfileViewModelFactory(
    private val userRepository: UserRepository  // 工厂自身持有需要注入的依赖
) : ViewModelProvider.Factory {
 
    @Suppress("UNCHECKED_CAST")
    override fun <T : ViewModel> create(modelClass: Class<T>): T {
        // 类型检查：确保请求的是 UserProfileViewModel
        if (modelClass.isAssignableFrom(UserProfileViewModel::class.java)) {
            // 通过构造函数注入 Repository，创建 ViewModel 实例
            return UserProfileViewModel(userRepository) as T
        }
        // 如果类型不匹配，抛出异常（防御性编程）
        throw IllegalArgumentException("Unknown ViewModel class: ${modelClass.name}")
    }
}

class UserProfileActivity : AppCompatActivity() {
 
    // 使用自定义 Factory 创建 ViewModel
    private val viewModel: UserProfileViewModel by viewModels {
        // 构造 Factory 时传入具体的 Repository 实例
        UserProfileViewModelFactory(
            userRepository = (application as MyApp).userRepository
        )
    }
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // viewModel 已就绪，可以直接使用
        lifecycleScope.launch {
            viewModel.userProfile.collect { profile ->
                // 更新 UI ...
            }
        }
    }
}

// NewInstanceFactory 源码（简化自 androidx.lifecycle）
open class NewInstanceFactory : Factory {
 
    companion object {
        // 单例实例，避免反复创建工厂对象（线程安全的懒加载）
        private var sInstance: NewInstanceFactory? = null
 
        // 获取全局共享的单例实例
        fun getInstance(): NewInstanceFactory {
            if (sInstance == null) {
                sInstance = NewInstanceFactory()
            }
            return sInstance!!
        }
    }
 
    override fun <T : ViewModel> create(modelClass: Class<T>): T {
        return try {
            // 核心：通过 Java 反射调用 Class 的无参构造函数
            // newInstance() 等价于 new MyViewModel()
            modelClass.newInstance()
        } catch (e: InstantiationException) {
            // 如果类是抽象类或接口，无法实例化
            throw RuntimeException("Cannot create an instance of $modelClass", e)
        } catch (e: IllegalAccessException) {
            // 如果构造函数是 private/protected，无法访问
            throw RuntimeException("Cannot create an instance of $modelClass", e)
        }
    }
}

// 一个可以被 NewInstanceFactory 创建的简单 ViewModel
class CounterViewModel : ViewModel() {
 
    // 使用 MutableStateFlow 管理计数状态
    private val _count = MutableStateFlow(0)
 
    // 对外暴露不可变的 StateFlow
    val count: StateFlow<Int> = _count.asStateFlow()
 
    // 递增方法
    fun increment() {
        _count.value++   // 原子操作，更新计数值
    }
}
 
// 在 Activity 中使用——无需指定 Factory
// viewModels() 委托会自动使用 NewInstanceFactory
class CounterActivity : AppCompatActivity() {
    private val viewModel: CounterViewModel by viewModels()  // 默认工厂即可
}

// AndroidViewModel 源码（完整版，非常简单）
open class AndroidViewModel(
    private val application: Application  // 持有 Application 引用（全局单例，不会泄漏）
) : ViewModel() {
 
    // 提供 getter 方法，子类可通过 getApplication() 获取 Application
    @Suppress("UNCHECKED_CAST")
    fun <T : Application> getApplication(): T {
        return application as T
    }
}

// AndroidViewModelFactory 源码（简化自 androidx.lifecycle）
open class AndroidViewModelFactory
private constructor(
    private val application: Application?  // 可选的 Application 引用
) : NewInstanceFactory() {
 
    // 公开构造函数：传入 Application 实例
    constructor(application: Application) : this(application as Application?)
 
    companion object {
        // 全局单例工厂（懒加载）
        private var sInstance: AndroidViewModelFactory? = null
 
        // 获取绑定到指定 Application 的全局单例工厂
        fun getInstance(application: Application): AndroidViewModelFactory {
            if (sInstance == null) {
                sInstance = AndroidViewModelFactory(application)
            }
            return sInstance!!
        }
    }
 
    override fun <T : ViewModel> create(modelClass: Class<T>): T {
        // 分支一：如果请求的 ViewModel 是 AndroidViewModel 的子类
        if (AndroidViewModel::class.java.isAssignableFrom(modelClass)) {
            // 确保 application 不为 null（防御性检查）
            val app = application
                ?: throw IllegalStateException(
                    "Cannot create AndroidViewModel without Application"
                )
            return try {
                // 通过反射找到接受 Application 参数的构造函数
                // getDeclaredConstructor(Application::class.java) 精确匹配单参构造
                modelClass
                    .getDeclaredConstructor(Application::class.java)
                    .newInstance(app)  // 传入 Application 实例进行创建
            } catch (e: NoSuchMethodException) {
                throw RuntimeException("Cannot create instance of $modelClass", e)
            } catch (e: Exception) {
                throw RuntimeException("Cannot create instance of $modelClass", e)
            }
        }
 
        // 分支二：如果不是 AndroidViewModel 子类，回退到父类逻辑
        // 即 NewInstanceFactory 的无参反射创建
        return super.create(modelClass)
    }
}

by viewModels()
  → 调用 defaultViewModelProviderFactory
    → 返回 SavedStateViewModelFactory
      → 内部判断：
         ├── 如果是 AndroidViewModel 子类 → 注入 Application + SavedStateHandle
         ├── 如果构造函数含 SavedStateHandle → 仅注入 SavedStateHandle
         └── 否则 → 退化为 NewInstanceFactory 的无参反射

// 一个典型的 AndroidViewModel 子类
class AppSettingsViewModel(
    application: Application               // 接收 Application 对象
) : AndroidViewModel(application) {
 
    // 利用 Application Context 获取 SharedPreferences
    private val prefs = application
        .getSharedPreferences("app_settings", Context.MODE_PRIVATE)
 
    // 读取暗黑模式设置，暴露为 StateFlow
    private val _isDarkMode = MutableStateFlow(
        prefs.getBoolean("dark_mode", false)  // 从 SP 中读取默认值
    )
    val isDarkMode: StateFlow<Boolean> = _isDarkMode.asStateFlow()
 
    // 切换暗黑模式
    fun toggleDarkMode() {
        val newValue = !_isDarkMode.value          // 取反当前值
        _isDarkMode.value = newValue               // 更新 StateFlow
        prefs.edit()                               // 获取 SP 编辑器
            .putBoolean("dark_mode", newValue)     // 写入新值
            .apply()                               // 异步提交
    }
}

class SettingsActivity : AppCompatActivity() {
 
    // 方式一：使用 by viewModels() 委托（推荐）
    // 默认 Factory（SavedStateViewModelFactory）会自动检测 AndroidViewModel
    // 并注入 Application，无需手动指定工厂
    private val viewModel: AppSettingsViewModel by viewModels()
 
    // 方式二：显式指定 AndroidViewModelFactory（了解原理时使用）
    // private val viewModel: AppSettingsViewModel by viewModels {
    //     AndroidViewModelFactory.getInstance(application)
    // }
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_settings)
 
        lifecycleScope.launch {
            // 在生命周期感知的协程中收集暗黑模式状态
            repeatOnLifecycle(Lifecycle.State.STARTED) {
                viewModel.isDarkMode.collect { isDark ->
                    // 根据状态更新 UI 主题...
                    applyTheme(isDark)
                }
            }
        }
    }
}

// 新版 Factory 接口（Lifecycle 2.5+ 新增的带 extras 的 create 重载）
public interface Factory {
    // 旧版方法（仍然保留，向后兼容）
    fun <T : ViewModel> create(modelClass: Class<T>): T
 
    // 新版方法：额外接收 CreationExtras 参数
    fun <T : ViewModel> create(modelClass: Class<T>, extras: CreationExtras): T {
        // 默认实现：忽略 extras，回退到旧版 create
        return create(modelClass)
    }
}

// CreationExtras 中预定义的几个核心 Key
object ViewModelProvider {
    // Key：获取 Application 实例
    val APPLICATION_KEY: CreationExtras.Key<Application>
 
    // Key：获取 SavedStateRegistryOwner
    val SAVED_STATE_REGISTRY_OWNER_KEY: CreationExtras.Key<SavedStateRegistryOwner>
 
    // Key：获取 ViewModelStoreOwner
    val VIEW_MODEL_STORE_OWNER_KEY: CreationExtras.Key<ViewModelStoreOwner>
}

// 使用 CreationExtras 的现代 Factory 风格
val factory = object : ViewModelProvider.Factory {
    override fun <T : ViewModel> create(
        modelClass: Class<T>,
        extras: CreationExtras    // 新版参数：包含 Application、SavedState 等信息
    ): T {
        // 从 extras 中安全取出 Application（类型安全，无需强转）
        val application = extras[ViewModelProvider.AndroidViewModelFactory.APPLICATION_KEY]
            ?: throw IllegalStateException("Application not found in CreationExtras")
 
        // 从 extras 中取出 SavedStateHandle（若需要）
        val savedStateHandle = extras.createSavedStateHandle()
 
        @Suppress("UNCHECKED_CAST")
        return UserProfileViewModel(
            application = application,        // 注入 Application
            savedStateHandle = savedStateHandle // 注入 SavedStateHandle
        ) as T
    }
}

// Kotlin DSL 风格的 Factory 构建（Lifecycle 2.5+）
val myFactory = viewModelFactory {
    // 为每种 ViewModel 类型注册 initializer
    initializer {
        // this 就是 CreationExtras
        val app = this[APPLICATION_KEY]!!          // 从 extras 取 Application
        val handle = createSavedStateHandle()      // 创建 SavedStateHandle
        UserProfileViewModel(app, handle)          // 构造 ViewModel
    }
    initializer {
        CounterViewModel()                         // 无参 ViewModel 直接创建
    }
}

class MyViewModel(val repo: UserRepository) : ViewModel()
val vm = ViewModelProvider(this).get(MyViewModel::class.java)

// ViewModel 中使用 SavedStateHandle 的基本模式
class SearchViewModel(
    // 框架自动注入，进程恢复时会携带之前保存的数据
    private val savedStateHandle: SavedStateHandle
) : ViewModel() {
 
    // 从 SavedStateHandle 中读取之前保存的搜索关键词
    // 如果是首次启动（没有保存过），则使用默认值空字符串
    val searchQuery: StateFlow<String> =
        savedStateHandle.getStateFlow("search_query", "")
 
    // 当用户在搜索框输入文字时调用此方法
    fun onQueryChanged(query: String) {
        // 将最新的搜索词写入 SavedStateHandle
        // 框架会在适当时机将其序列化到 Bundle 中
        savedStateHandle["search_query"] = query
    }
}

// 传统方式：在 Activity 中手动保存和恢复状态
class SearchActivity : AppCompatActivity() {
 
    // UI 状态变量
    private var searchQuery: String = ""
    private var selectedTabIndex: Int = 0
 
    override fun onSaveInstanceState(outState: Bundle) {
        // 手动将每个需要保存的状态写入 Bundle
        super.onSaveInstanceState(outState)
        outState.putString("key_search_query", searchQuery)
        outState.putInt("key_selected_tab", selectedTabIndex)
    }
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // 手动从 Bundle 中恢复每个状态
        if (savedInstanceState != null) {
            searchQuery = savedInstanceState.getString("key_search_query", "")
            selectedTabIndex = savedInstanceState.getInt("key_selected_tab", 0)
        }
    }
}

class DetailViewModel(
    private val savedStateHandle: SavedStateHandle
) : ViewModel() {
 
    // ---- 1. 直接读写 ----
    // get<T>(key): 读取值，返回 T?（可能为 null）
    val userId: String? = savedStateHandle.get<String>("user_id")
 
    // set(key, value) 或 operator[](key) = value: 写入值
    fun updateUserId(id: String) {
        savedStateHandle["user_id"] = id  // 等价于 savedStateHandle.set("user_id", id)
    }
 
    // ---- 2. 响应式读取（推荐方式）----
    // getStateFlow(key, initialValue): 返回一个 StateFlow
    // 当 set() 被调用时，StateFlow 自动更新
    // initialValue 仅在 key 不存在时使用
    val filterType: StateFlow<String> =
        savedStateHandle.getStateFlow("filter_type", "ALL")
 
    // getLiveData(key, initialValue): 返回一个 LiveData
    // 原理与 getStateFlow 类似，但用于传统 View 体系
    val sortOrder: LiveData<String> =
        savedStateHandle.getLiveData("sort_order", "ASC")
 
    // ---- 3. 删除与查询 ----
    fun clearFilter() {
        // remove(key): 删除某个 key
        savedStateHandle.remove<String>("filter_type")
    }
 
    fun hasUserId(): Boolean {
        // contains(key): 判断是否存在某个 key
        return savedStateHandle.contains("user_id")
    }
 
    // ---- 4. 获取所有 key ----
    fun allKeys(): Set<String> {
        // keys(): 返回所有已存储的 key
        return savedStateHandle.keys()
    }
}

// 假设导航定义了参数 "article_id"
// 在 Navigation Graph 中: <argument name="article_id" app:argType="string" />
class ArticleViewModel(
    savedStateHandle: SavedStateHandle
) : ViewModel() {
 
    // Navigation 参数自动注入到 SavedStateHandle 中
    // 直接通过 key 读取即可，无需手动解析 Intent 或 Bundle
    val articleId: String = savedStateHandle.get<String>("article_id")
        ?: throw IllegalArgumentException("article_id is required")
 
    // 也可以用于 Compose Navigation 的路由参数
    // 例如路由 "article/{articleId}" 中的 articleId
    init {
        // 使用 articleId 发起网络请求等初始化操作
        loadArticle(articleId)
    }
 
    private fun loadArticle(id: String) {
        viewModelScope.launch {
            // ... 加载文章详情
        }
    }
}

// ❌ 错误示范：存入不支持的类型
data class UiState(      // 既没有 @Parcelize，也没有实现 Serializable
    val isLoading: Boolean,
    val errorMessage: String?
)
 
class BadViewModel(
    private val savedStateHandle: SavedStateHandle
) : ViewModel() {
    fun saveState() {
        // 运行时崩溃！UiState 不是 Bundle 支持的类型
        savedStateHandle["ui_state"] = UiState(true, null)
    }
}
 
// ✅ 正确方式 1：使用 @Parcelize（推荐，性能最优）
@Parcelize  // 需要 kotlin-parcelize 插件
data class UiState(
    val isLoading: Boolean,
    val errorMessage: String?
) : Parcelable  // 实现 Parcelable 接口
 
// ✅ 正确方式 2：拆分为基本类型分别存储
class GoodViewModel(
    private val savedStateHandle: SavedStateHandle
) : ViewModel() {
    // 将复杂状态拆解为多个基本类型 key
    val isLoading: StateFlow<Boolean> =
        savedStateHandle.getStateFlow("is_loading", false)
 
    val errorMessage: StateFlow<String?> =
        savedStateHandle.getStateFlow("error_msg", null)
}

// ❌ 反模式：在 SavedStateHandle 中存储大量数据
class SearchResultViewModel(
    private val savedStateHandle: SavedStateHandle
) : ViewModel() {
 
    fun cacheResults(results: List<SearchResult>) {
        // 危险！如果 results 列表很大（比如包含图片 URL、长文本等），
        // 序列化后可能超过 Bundle 大小限制
        savedStateHandle["results"] = ArrayList(results) // ArrayList<Parcelable>
    }
}
 
// ✅ 正确做法：只保存恢复搜索所必要的最小信息
class SearchResultViewModel(
    private val savedStateHandle: SavedStateHandle
) : ViewModel() {
 
    // 只保存搜索关键词和当前页码
    // 恢复后重新发起搜索请求获取数据
    val query: StateFlow<String> =
        savedStateHandle.getStateFlow("query", "")
 
    val currentPage: StateFlow<Int> =
        savedStateHandle.getStateFlow("page", 1)
 
    // 搜索结果列表存在普通的 StateFlow 中（不持久化）
    // 进程恢复后重新加载即可
    private val _results = MutableStateFlow<List<SearchResult>>(emptyList())
    val results: StateFlow<List<SearchResult>> = _results.asStateFlow()
 
    init {
        // 如果 query 非空，说明是从进程恢复回来的
        // 自动重新发起搜索
        viewModelScope.launch {
            query.collect { q ->
                if (q.isNotEmpty()) {
                    _results.value = repository.search(q, currentPage.value)
                }
            }
        }
    }
}

// 🏆 最佳实践：使用 @Parcelize 自动生成 Parcelable 实现
// 需要在 build.gradle 中应用 kotlin-parcelize 插件
// plugins { id("kotlin-parcelize") }
@Parcelize
data class FilterConfig(
    val category: String,       // 类别筛选
    val minPrice: Double,       // 最低价格
    val maxPrice: Double,       // 最高价格
    val sortBy: SortType        // 排序方式（枚举也需要是 Parcelable 或基本类型）
) : Parcelable
 
// 枚举天然支持 Serializable，可以直接存入 Bundle
// 但若作为 Parcelable 的字段，推荐也标注 @Parcelize 或使用基本类型
enum class SortType {
    PRICE_ASC, PRICE_DESC, RATING, NEWEST
}
 
class ProductListViewModel(
    private val savedStateHandle: SavedStateHandle
) : ViewModel() {
 
    // Parcelable 对象可以直接存入 SavedStateHandle
    val filterConfig: StateFlow<FilterConfig> =
        savedStateHandle.getStateFlow(
            "filter_config",
            FilterConfig("ALL", 0.0, 9999.0, SortType.NEWEST) // 默认值
        )
 
    // 更新筛选配置
    fun updateFilter(config: FilterConfig) {
        savedStateHandle["filter_config"] = config
    }
}

// 一个典型的 ViewModel，演示 viewModelScope 的基本用法
class UserProfileViewModel(
    private val userRepository: UserRepository // 通过构造函数注入数据仓库
) : ViewModel() {
 
    // 使用 MutableStateFlow 持有 UI 状态，初始值为 Loading
    private val _uiState = MutableStateFlow<UiState>(UiState.Loading)
    // 对外暴露不可变的 StateFlow，防止 UI 层直接修改状态
    val uiState: StateFlow<UiState> = _uiState.asStateFlow()
 
    // 加载用户资料的函数
    fun loadUserProfile(userId: String) {
        // 在 viewModelScope 中启动协程
        // 当 ViewModel 被 clear 时，这个协程会自动取消
        viewModelScope.launch {
            _uiState.value = UiState.Loading          // 先置为加载中状态
            try {
                // 调用挂起函数获取用户数据（内部可能是网络请求）
                val user = userRepository.getUser(userId)
                _uiState.value = UiState.Success(user) // 成功则更新状态
            } catch (e: CancellationException) {
                throw e // 协程取消异常必须重新抛出，不能吞掉
            } catch (e: Exception) {
                _uiState.value = UiState.Error(e.message ?: "Unknown error")
            }
        }
    }
}

// ViewModel 内部简化源码（伪代码，帮助理解机制）
open class ViewModel {
    // 内部维护的 tag 存储，用于附加需要随 ViewModel 清理的资源
    private val bagOfTags = HashMap<String, Any>()
    // 标记 ViewModel 是否已被 clear
    @Volatile private var isCleared = false
 
    // 存储 tag 的方法：如果 key 不存在则放入，如果已存在则返回旧值
    // 这保证了同一个 key 只会创建一次对象（类似 ConcurrentHashMap.putIfAbsent）
    fun <T> setTagIfAbsent(key: String, newValue: T): T {
        synchronized(bagOfTags) {
            // 尝试获取已有的值
            val previous = bagOfTags[key] as? T
            if (previous != null) {
                return previous // 已存在，直接返回，不替换
            }
            bagOfTags[key] = newValue as Any // 不存在，存入新值
        }
        // 如果在存入的瞬间 ViewModel 已经被 clear 了，立即关闭
        if (isCleared) {
            (newValue as? Closeable)?.close()
        }
        return newValue
    }
 
    // ViewModel 被清除时由 ViewModelStore 调用
    @MainThread
    fun clear() {
        isCleared = true
        // 遍历所有 tag，关闭所有 Closeable 资源
        synchronized(bagOfTags) {
            for (value in bagOfTags.values) {
                closeWithRuntimeException(value) // 如果是 Closeable 就调 close()
            }
        }
        onCleared() // 回调子类的清理逻辑
    }
}

// viewModelScope 早期实现（lifecycle-viewmodel-ktx 2.1~2.4）
// 定义一个常量 key，用于在 ViewModel 的 tag map 中存取 scope
private const val JOB_KEY = "androidx.lifecycle.ViewModelCoroutineScope.JOB_KEY"
 
// ViewModel 的扩展属性
val ViewModel.viewModelScope: CoroutineScope
    get() {
        // 先尝试从 tag map 中获取已有的 scope
        val scope: CoroutineScope? = this.getTag(JOB_KEY)
        if (scope != null) {
            return scope // 已创建过，直接返回
        }
        // 首次访问，创建新的 CloseableCoroutineScope
        // SupervisorJob() 保证子协程异常不会取消兄弟协程
        // Dispatchers.Main.immediate 保证默认在主线程调度
        return setTagIfAbsent(
            JOB_KEY,
            CloseableCoroutineScope(
                SupervisorJob() + Dispatchers.Main.immediate
            )
        )
    }
 
// 实现了 Closeable 的 CoroutineScope 包装类
// 当 ViewModel.clear() 遍历 tag 调用 close() 时，会取消协程上下文
internal class CloseableCoroutineScope(
    override val coroutineContext: CoroutineContext
) : Closeable, CoroutineScope {
    override fun close() {
        // 取消 coroutineContext 中的 Job，从而取消所有子协程
        coroutineContext.cancel()
    }
}

viewModelScope.launch(Dispatchers.Default) { // 切到计算线程
    // 假设这是一个需要长时间计算的循环
    for (i in 0 until 1_000_000) {
        // 关键：手动检查协程是否仍然活跃
        // 如果 ViewModel 已经 clear，isActive 会变为 false
        if (!isActive) break // 或者调用 ensureActive() 自动抛 CancellationException
        // 执行计算逻辑...
        heavyComputation(i)
    }
}

普通 Job 的异常传播（双向取消）：
 
         ┌─────────┐
         │ Root Job│   ← 3. 父 Job 收到异常，取消自己和所有子 Job
         └────┬────┘
         ┌────┴─────────────┐
    ┌────┴────┐       ┌────┴────┐
    │ Child A │       │ Child B │  ← 4. 无辜的 Child B 也被取消了！
    │ (崩溃💥)│       │ (正常中)│
    └─────────┘       └─────────┘
    ↑ 1. 抛出异常      ↑ 2. 异常向上传播

SupervisorJob 的异常传播（单向取消）：
 
         ┌──────────────┐
         │SupervisorJob │   ← 3. 父 Job 不受影响，继续存活
         └──────┬───────┘
         ┌──────┴─────────────┐
    ┌────┴────┐         ┌────┴────┐
    │ Child A │         │ Child B │  ← 4. Child B 完全不受影响
    │ (崩溃💥)│         │ (正常✅) │
    └─────────┘         └─────────┘
    ↑ 1. 抛出异常
    ↑ 2. 异常不向上传播，Child A 自己消亡

// Kotlin 协程库中的简化源码
// SupervisorJob 工厂函数
public fun SupervisorJob(parent: Job? = null): CompletableJob =
    SupervisorJobImpl(parent)
 
// SupervisorJobImpl 的核心区别
private class SupervisorJobImpl(parent: Job?) : JobImpl(parent) {
    // 当子协程因异常失败并通知父 Job 时，这个方法会被调用
    // 普通 JobImpl 中此方法会返回 true 并取消自己（连带所有子协程）
    // SupervisorJobImpl 直接返回 false，表示"我不处理子协程的失败"
    override fun childCancelled(cause: Throwable): Boolean = false
}

class OrderViewModel(
    private val orderRepo: OrderRepository
) : ViewModel() {
 
    fun placeOrder(order: Order) {
        viewModelScope.launch {
            // ✅ 正确：在 launch 内部捕获异常
            try {
                val result = orderRepo.submitOrder(order)
                _uiState.value = UiState.OrderPlaced(result)
            } catch (e: CancellationException) {
                throw e // CancellationException 必须重新抛出，否则取消机制会失效
            } catch (e: HttpException) {
                // 业务异常，更新 UI 状态即可
                _uiState.value = UiState.Error("下单失败: ${e.code()}")
            } catch (e: IOException) {
                // 网络异常
                _uiState.value = UiState.Error("网络连接异常，请重试")
            }
        }
    }
 
    fun loadOrderHistory() {
        viewModelScope.launch {
            // 这个协程与 placeOrder 完全独立
            // 即使 placeOrder 的协程崩溃，也不影响这里
            try {
                val history = orderRepo.getHistory()
                _historyState.value = history
            } catch (e: CancellationException) {
                throw e
            } catch (e: Exception) {
                _historyState.value = emptyList()
            }
        }
    }
}

viewModelScope.launch {
    // 在一个协程内部，并发加载多个独立数据源
    // 使用 supervisorScope 确保它们之间互不影响
    supervisorScope {
        // 这两个 async 是并发执行的
        val profileDeferred = async { userRepo.getProfile() }  // 子任务 1
        val settingsDeferred = async { userRepo.getSettings() } // 子任务 2
 
        // 即使 settings 请求失败，profile 的结果仍然可用
        val profile = try {
            profileDeferred.await()
        } catch (e: Exception) {
            null // profile 请求失败，降级为 null
        }
 
        val settings = try {
            settingsDeferred.await()
        } catch (e: Exception) {
            Settings.default() // settings 请求失败，使用默认值
        }
 
        _uiState.value = UiState.Success(profile, settings)
    }
}

// ComponentActivity 中注册的 Lifecycle 观察者（简化）
getLifecycle().addObserver(object : LifecycleEventObserver {
    override fun onStateChanged(source: LifecycleOwner, event: Lifecycle.Event) {
        // 只在 ON_DESTROY 事件时处理
        if (event == Lifecycle.Event.ON_DESTROY) {
            // 关键判断：是否是配置变更导致的 destroy
            // 如果不是配置变更（即是真正的销毁），才清理 ViewModelStore
            if (!isChangingConfigurations) {
                viewModelStore.clear() // 这会触发所有 ViewModel 的 onCleared()
            }
        }
    }
})

// ViewModel.clear() 源码简化
@MainThread
final fun clear() {
    isCleared = true
    // 1️⃣ 先清理 bagOfTags 中所有 Closeable 资源（包括 viewModelScope）
    synchronized(bagOfTags) {
        for (value in bagOfTags.values) {
            closeWithRuntimeException(value)
        }
    }
    // 2️⃣ 再回调子类的 onCleared()
    onCleared()
}

class AnalyticsViewModel(
    private val analyticsRepo: AnalyticsRepository,
    private val appScope: CoroutineScope // 注入应用级 scope，生命周期与进程一致
) : ViewModel() {
 
    // 记录用户在本页面的行为数据
    private val pageEvents = mutableListOf<AnalyticsEvent>()
 
    override fun onCleared() {
        super.onCleared()
        // ⚠️ 此时 viewModelScope 已取消！不能用它启动协程
        // ✅ 使用应用级 scope，确保日志上传能完成
        appScope.launch {
            analyticsRepo.uploadEvents(pageEvents.toList())
        }
    }
}

class MediaPlayerViewModel : ViewModel() {
 
    // ViewModel 持有的 MediaPlayer 资源
    private var mediaPlayer: MediaPlayer? = null
 
    // 注册的广播接收器或事件监听
    private val eventBus = EventBus.getDefault()
 
    init {
        // 注册事件总线（如果使用）
        eventBus.register(this)
    }
 
    fun initPlayer(context: Context) {
        // 注意：这里的 context 应该是 Application context，不是 Activity context
        mediaPlayer = MediaPlayer.create(context, R.raw.background_music)
    }
 
    override fun onCleared() {
        super.onCleared()
 
        // 1. 释放 MediaPlayer 资源
        mediaPlayer?.release()
        mediaPlayer = null
 
        // 2. 注销事件总线
        eventBus.unregister(this)
 
        // 3. 关闭数据库连接、取消注册 ContentObserver 等
        // ...所有需要手动清理的资源都在这里处理
    }
}

class DatabaseViewModel : ViewModel() {
 
    // 通过 addCloseable 注册的资源会在 ViewModel clear 时自动关闭
    private val dbConnection = DatabaseConnection().also {
        addCloseable(it) // 注册为 Closeable，自动管理生命周期
    }
 
    // 无需重写 onCleared()，dbConnection 会自动被 close()
}

// 单元测试中替换 Main dispatcher
@OptIn(ExperimentalCoroutinesApi::class)
class UserViewModelTest {
 
    // 创建测试用的 dispatcher
    private val testDispatcher = UnconfinedTestDispatcher()
 
    @Before
    fun setup() {
        // 将 Dispatchers.Main 替换为测试 dispatcher
        // 这样 viewModelScope 中的协程会在测试线程上同步执行
        Dispatchers.setMain(testDispatcher)
    }
 
    @After
    fun tearDown() {
        // 测试结束后恢复原始的 Main dispatcher
        Dispatchers.resetMain()
    }
 
    @Test
    fun `loadUser should update state to Success`() = runTest {
        // Arrange: 准备 mock 数据
        val fakeRepo = FakeUserRepository(User("Alice"))
        val viewModel = UserProfileViewModel(fakeRepo)
 
        // Act: 触发加载
        viewModel.loadUserProfile("123")
 
        // 因为使用了 UnconfinedTestDispatcher，协程会立即执行完成
        // Assert: 验证状态
        val state = viewModel.uiState.value
        assertTrue(state is UiState.Success)
        assertEquals("Alice", (state as UiState.Success).user.name)
    }
}

// 1. 定义 ViewModel，构造函数声明所有依赖
class ArticleViewModel(
    private val repository: ArticleRepository,  // 数据仓库
    private val savedStateHandle: SavedStateHandle // 进程恢复状态
) : ViewModel() {
    // ... 业务逻辑
}
 
// 2. 手写 Factory，在 create() 中手动组装依赖
class ArticleViewModelFactory(
    private val repository: ArticleRepository,      // 外部传入的依赖
    owner: SavedStateRegistryOwner,                  // 用于获取 SavedStateHandle
    defaultArgs: Bundle? = null                      // 默认参数
) : AbstractSavedStateViewModelFactory(owner, defaultArgs) {
 
    // 重写 create 方法，手动调用 ViewModel 构造函数
    override fun <T : ViewModel> create(
        key: String,
        modelClass: Class<T>,
        handle: SavedStateHandle
    ): T {
        @Suppress("UNCHECKED_CAST")
        return ArticleViewModel(repository, handle) as T  // 手动注入
    }
}
 
// 3. 在 Activity/Fragment 中使用 Factory 创建 ViewModel
class ArticleActivity : AppCompatActivity() {
    private val viewModel: ArticleViewModel by viewModels {
        // 必须手动提供 Factory 实例，传入所有外部依赖
        ArticleViewModelFactory(
            repository = (application as MyApp).articleRepository,
            owner = this
        )
    }
}

// 1. 用 @HiltViewModel 标记 ViewModel
// 2. 用 @Inject 标记构造函数，声明所有依赖
@HiltViewModel
class ArticleViewModel @Inject constructor(
    private val repository: ArticleRepository,      // Hilt 自动从 DI 图中解析
    private val savedStateHandle: SavedStateHandle  // Hilt 自动提供
) : ViewModel() {
    // ... 业务逻辑完全不变
}
 
// 3. 在 Activity/Fragment 中直接使用，无需任何 Factory
@AndroidEntryPoint  // 必须标记，Hilt 才能注入当前组件
class ArticleActivity : AppCompatActivity() {
    // 直接 by viewModels()，不传 Factory 参数
    private val viewModel: ArticleViewModel by viewModels()
}

@HiltViewModel
class SearchViewModel @Inject constructor(
    private val searchRepository: SearchRepository,   // 普通依赖，从 DI 图解析
    private val savedStateHandle: SavedStateHandle    // 内置依赖，Hilt 自动提供
) : ViewModel() {
 
    // 从 savedStateHandle 中恢复搜索关键字
    // getStateFlow 会自动与 SavedStateRegistry 同步
    val query: StateFlow<String> = savedStateHandle.getStateFlow(
        key = "search_query",   // 存储 Key
        initialValue = ""       // 默认值：空字符串
    )
 
    // 更新搜索关键字，同时自动持久化到 SavedStateHandle
    fun updateQuery(newQuery: String) {
        savedStateHandle["search_query"] = newQuery  // 操作符重载写入
    }
}

// ViewModel: 使用 @AssistedInject 替代 @Inject
// 注意：不使用 @HiltViewModel，因为 Assisted 模式有独立的注册方式
class ArticleDetailViewModel @AssistedInject constructor(
    private val repository: ArticleRepository,   // 由 Hilt 自动提供（provided）
    private val analytics: AnalyticsTracker,     // 由 Hilt 自动提供（provided）
    @Assisted private val articleId: Long        // 由调用方运行时传入（assisted）
) : ViewModel() {
 
    // 使用注入的 articleId 加载文章详情
    val article: StateFlow<Article?> = flow {
        emit(repository.getArticle(articleId))   // 直接使用 assisted 参数
    }.stateIn(
        scope = viewModelScope,                  // ViewModel 协程作用域
        started = SharingStarted.WhileSubscribed(5000), // 5秒缓存
        initialValue = null                      // 初始值
    )
 
    // 编译期生成的工厂接口
    @AssistedFactory
    interface Factory {
        // 方法参数对应所有 @Assisted 标记的参数
        fun create(articleId: Long): ArticleDetailViewModel
    }
}

// 在 Activity/Fragment 中桥接 AssistedFactory 与 ViewModelProvider
@AndroidEntryPoint
class ArticleDetailFragment : Fragment() {
 
    // 1. 通过 Hilt 注入 AssistedFactory（它本身是 DI 图中的普通绑定）
    @Inject
    lateinit var viewModelFactory: ArticleDetailViewModel.Factory
 
    // 2. 使用 by viewModels{} 传入自定义 Factory
    private val viewModel: ArticleDetailViewModel by viewModels {
        // 3. 创建匿名 ViewModelProvider.Factory 桥接
        object : ViewModelProvider.Factory {
            @Suppress("UNCHECKED_CAST")
            override fun <T : ViewModel> create(modelClass: Class<T>): T {
                // 4. 从导航参数中取出 articleId
                val articleId = requireArguments().getLong("article_id")
                // 5. 调用 AssistedFactory 创建实例，并转型返回
                return viewModelFactory.create(articleId) as T
            }
        }
    }
}

class ComparisonViewModel @AssistedInject constructor(
    private val repository: ArticleRepository,              // provided
    @Assisted("left") private val leftArticleId: Long,      // assisted: 标记为 "left"
    @Assisted("right") private val rightArticleId: Long     // assisted: 标记为 "right"
) : ViewModel() {
 
    @AssistedFactory
    interface Factory {
        // 工厂方法的参数也必须带上相同的 @Assisted 标识
        fun create(
            @Assisted("left") leftId: Long,     // 与构造函数的 "left" 对应
            @Assisted("right") rightId: Long    // 与构造函数的 "right" 对应
        ): ComparisonViewModel
    }
}

@HiltViewModel
class ProfileViewModel @Inject constructor(
    private val userRepository: UserRepository,     // DI 提供
    private val savedStateHandle: SavedStateHandle  // Hilt 内置提供
) : ViewModel() {
 
    // Navigation 参数 "user_id" 自动存在于 SavedStateHandle 中
    // 通过非空断言获取（如果导航图中已声明该参数为必选）
    private val userId: String = savedStateHandle.get<String>("user_id")
        ?: throw IllegalArgumentException("user_id is required")  // 防御性校验
 
    // 使用 userId 加载用户数据
    val userProfile: StateFlow<UserProfile?> = userRepository
        .observeUser(userId)         // 返回 Flow<UserProfile>
        .stateIn(
            scope = viewModelScope,  // 绑定 ViewModel 生命周期
            started = SharingStarted.WhileSubscribed(5000),
            initialValue = null
        )
}