# 架构技巧：Android应用架构该技能定义了在该项目中构建 Android 应用程序的架构规则和模式。它使用 Views 和 Jetpack Compose 建立状态管理、层分离、依赖注入、模块化和 UI 模式的约定。 ** ** ## 1\. TEA（Elm 架构）- 修改 ### 概述该架构使用带有 **State** 、 **Command** 和 **SideEffect** 的修改 TEA 模式。该系统必须是完全可取消的。 Store 通过 ViewModel 具有生命周期感知能力。 **Store.send() 只能从主线程调用。** ### 组件 #### 状态表示功能的当前状态。必须是不可变的。数据类 AuthState( val isLoading: 布尔值 = false, 值错误：字符串？ = 空，有效用户：用户？ = 空，） ####命令表示可以修改状态的用户操作或系统事件。密封接口 AuthCommand { 数据类 LoginTapped(val email: String, val 密码: String) : AuthCommand 数据对象 LogoutTapped ：AuthCommand 数据类 UserLoaded(val user: User) : AuthCommand 数据类 ErrorOccurred(val message: String) : AuthCommand } #### 副作用代表需要执行的副作用。 SideEffects 有两个目的： 1. **业务逻辑** \-由EffectHandlers处理（网络调用、持久化等） 2. **UI 操作** \- 由 Fragment/Composable 处理（导航、Toast 等）密封接口 AuthSideEffect { // 业务逻辑副作用数据类登录（val电子邮件：字符串，val密码：字符串）：AuthSideEffect 数据对象注销：AuthSideEffect 数据对象 LoadUser : AuthSideEffect // 用户界面副作用数据对象 NavigateToHome ：AuthSideEffect 数据类 ShowError(val message: String) : AuthSideEffect } ### 减速器接口减速器接受状态和命令，返回新状态和副作用列表。 Reducer 是一个**纯函数** \- 不允许有副作用。 // 接口 - 在 core/tea/base 模块中，公共接口Reducer<状态，命令，SideEffect> { 有趣的减少（状态：状态，命令：命令）：ReduceResult<状态，SideEffect> } 数据类ReduceResult( val状态：状态， val sideEffects: List = emptyList(), ） // 语法更简洁的辅助函数 fun State.withSideEffects( 可变参数副作用：副作用， ):ReduceResult<状态, SideEffect> =ReduceResult(this, sideEffects.toList()) fun State.noSideEffects():ReduceResult = 减少结果（这个，空列表（）） // 实现 - 功能名称前缀，内部可见性（减速器没有 Impl 后缀）内部类 AuthReducer :Reducer { 覆盖乐趣减少（状态：验证状态，命令：AuthCommand， ):ReduceResult = 当（命令）{ 是 AuthCommand.LoginTapped -> { state.copy(isLoading = true, error = null) .withSideEffects(AuthSideEffect.Login(命令.电子邮件, 命令.密码)) } 是 AuthCommand.LogoutTapped -> { state.withSideEffects(AuthSideEffect.Logout) } 是 AuthCommand.UserLoaded -> { state.copy(isLoading = false, user = command.user) .withSideEffects(AuthSideEffect.NavigateToHome) } 是 AuthCommand.ErrorOccurred -> { state.copy(isLoading = false, error = command.message) .withSideEffects(AuthSideEffect.ShowError(command.message)) } } } ### EffectHandler 接口效果处理程序处理副作用并通过“onCommand”挂起函数发送反馈。 `onCommand` **必须挂起**并在内部使用 `withContext(Dispatchers.Main.immediate)` 确保线程安全，因为必须从主线程调用 `Store.send()`。可以指定多个效果处理程序，每个效果处理程序都有自己的角色。 EffectHandler 扩展了 `Closeable`。默认的“close()”是无操作，但可以覆盖它以释放资源（例如，取消内部作业）。 `Store.cancel()` 在所有效果处理程序上调用 `close()`。 // 接口 - 在 core/tea/base 模块中，公共接口 EffectHandler: 可关闭 { 挂起有趣的句柄（效果：SideEffect，onCommand：挂起（命令）->单位）覆盖 fun close() = 单位 } // 网络相关效果处理程序 - 功能名称前缀，内部（无 Impl 后缀）内部类 AuthNetworkEffectHandler @Inject 构造函数（ private val loginUseCase: LoginUseCase, private val logoutUseCase: LogoutUseCase, ) : EffectHandler { 覆盖挂起乐趣句柄（效果：AuthSideEffect， onCommand：暂停（AuthCommand）->单位，）{ 当（效果）{ 是 AuthSideEffect.Login -> { loginUseCase(效果.电子邮件, 效果.密码) .onSuccess { 用户 -> onCommand(AuthCommand.UserLoaded(user)) } .onFailure { 错误 -> onCommand(AuthCommand.ErrorOccurred(error.message ?: "未知错误")) } } 是 AuthSideEffect.Logout -> { 注销用例() } // 由不同的效果处理程序或 UI 处理其他 -> 单位 } } } // 与持久性相关的效果处理程序内部类 AuthPersistenceEffectHandler @Inject 构造函数（私有val loadUserUseCase：LoadUserUseCase， ) : EffectHandler { 覆盖挂起乐趣句柄（效果：AuthSideEffect， onCommand：暂停（AuthCommand）->单位，）{ 当（效果）{ 是 AuthSideEffect.LoadUser -> { loadUserUseCase()?.let { 用户 -> onCommand(AuthCommand.UserLoaded(用户)) } } // 由不同的效果处理程序或 UI 处理其他 -> 单位 } } } ### 商店存储编排状态、减速器和效果处理程序。必须支持通过协程作业管理取消。 **`send()` 只能从主线程调用。** // 在 core/tea/base 模块中，public 类 Store<状态、命令、副作用>( 初始状态：状态，私有 val 减速器：Reducer<状态，命令，SideEffect>， private val EffectHandlers: List>, 私有 val 范围：CoroutineScope，）{ 私有 val _state = MutableStateFlow(initialState) val 状态：StateFlow = _state.asStateFlow() 私有 val _sideEffects = MutableSharedFlow() val sideEffects: SharedFlow = _sideEffects.asSharedFlow() 私有 val jobs = mutableMapOf() /** * 向商店发送命令。必须从主线程调用。 */ 有趣的发送（命令：命令）{ val 结果 = reducer.reduce(_state.value, 命令) _state.value = 结果.state result.sideEffects.forEach { sideEffect -> // 发出 UI 观察的副作用范围.启动{ _sideEffects.emit(sideEffect) } // 使用处理程序处理副作用 effectHandlers.forEach { 处理程序 -> val jobId = UUID.randomUUID().toString() val job = 范围.launch { handler.handle(sideEffect) { cmd -> // 在调用send之前切换到主线程 withContext(Dispatchers.Main) { 发送(cmd) } } 职位.删除（职位ID） } 职位[职位ID] = 职位 } } } 有趣的取消() { jobs.values.forEach { it.cancel() } 工作.clear() effectHandlers.forEach { it.close() } } } ### ViewStateMapper 接口 ViewStateMapper 是一个**强制**接口，它将内部域状态转换为可呈现的 ViewState。每个功能都必须有一个 ViewState 和一个 ViewStateMapper - 没有选择退出。 // 在 core/tea/base 模块中，public 接口 ViewStateMapper<状态，ViewState> { 有趣的地图（状态：状态）：ViewState } 即使对于 State 1:1 映射到 ViewState 的简单功能，映射器也必须存在。映射器保持边界干净，并且使以后添加派生字段变得微不足道。 ### BaseStoreViewModel 将 Store 与 Android 生命周期集成的基础 ViewModel。 ViewModel 通过 ViewStateMapper 将内部状态映射到 ViewState 并公开映射的“StateFlow”。 // 在 core/tea/android 模块中，public 抽象类 BaseStoreViewModel( 初始状态：状态，减速器：减速器<状态，命令，副作用>， effectHandlers: List>, viewStateMapper: ViewStateMapper<状态, ViewState>, 初始SideEffects：List = emptyList（）， viewStateMappingDispatcher：CoroutineDispatcher = Dispatchers.Main.immediate， ) : ViewModel() { 私人 val 商店 = 商店( 初始状态 = 初始状态, 减速机=减速机，效果处理程序 = 效果处理程序, 范围 = viewModelScope, ） val 状态：StateFlow = store.state .map { viewStateMapper.map(it) } .flowOn(viewStateMappingDispatcher) .stateIn( 范围 = viewModelScope, 开始=SharingStarted.Eagerly，初始值 = viewStateMapper.map(initialState), ） val sideEffects: SharedFlow = store.sideEffects 初始化{ initialSideEffects.forEach { 效果 -> effectHandlers.forEach { 处理程序 -> viewModelScope.launch { handler.handle(effect) { cmd -> withContext(Dispatchers.Main.immediate) { 发送(cmd) } } } } } } 有趣的发送（命令：命令）{ 存储.发送（命令） } 重写 fun onCleared() { super.onCleared() 商店.取消() } } **要点：** * `ViewState` 是第一个类型参数 * `state` 暴露 `StateFlow`，而不是 `StateFlow` - 映射发生在 ViewModel 内部 * `viewStateMappingDispatcher` 默认为 `Dispatchers.Main.immediate` 但可以被覆盖（例如，`Dispatchers.Default`）以进行昂贵的映射操作 * 片段/可组合项直接渲染 `ViewState` - 它们不注入映射器 ### 特征视图模型扩展 BaseStoreViewModel 的特定功能 ViewModel。第一个类型参数始终是 ViewState。 // 特征 ViewModel - 内部可见性 @HiltViewModel 内部类 AuthViewModel @Inject 构造函数( 减速器：AuthReducer， networkEffectHandler：AuthNetworkEffectHandler， persistenceEffectHandler：AuthPersistenceEffectHandler， viewStateMapper：AuthViewStateMapper， ) : BaseStoreViewModel( 初始状态 = AuthState(), 减速机=减速机， effectHandlers = listOf(networkEffectHandler, persistenceEffectHandler), 视图状态映射器 = 视图状态映射器, 初始SideEffects = listOf( AuthSideEffect.LoadUser， AuthSideEffect.ObservePreferences， ), ） ### ViewState 模式（强制）每个功能都必须具有 **State** （由Reducer 管理的内部域状态）和 **ViewState** （UI 使用的演示就绪状态）。 **ViewStateMapper** 将 State 转换为 ViewModel 内的 ViewState — Fragment/Composable 只能看到 ViewState。＃＃＃＃成分 **State** 保存由Reducer 管理的以域为中心的数据：内部数据类 ItemsState( val items: List? = 空， val selectedIds: Set = emptySet(), val ExpandedOverrides: Map = emptyMap(), val defaultExpanded: 布尔值 = false, val 文本大小：Int = 14， val itemsChanged: 布尔值 = true, // ...其他域字段） **ViewState** 保存片段的演示就绪数据：内部数据类 ItemsViewState( val items: List? = 空， val itemsChanged: 布尔值 = true, val 选择：Boolean = false， val selectedCount: Int = 0, // ...其他 UI 字段） **ViewStateMapper** 从 `core/tea`、`@Inject` 构造、`internal` 可见性实现了 `ViewStateMapper` 接口：内部类 ItemsViewStateMapper @Inject constructor() : ViewStateMapper { 覆盖有趣的地图（状态：ItemsState）：ItemsViewState = ItemsViewState（ items = state.items?.map { 格式化 -> 格式化.toPresentationModel( Expanded = state.expandedOverrides.getOrElse(formatted.id) { state.defaultExpanded }, selected = state.selectedIds中的formatted.id， textSize = state.textSize.toFloat(), ） }, itemsChanged = state.itemsChanged, 选择 = state.selectedIds.isNotEmpty(), selectedCount = state.selectedIds.size, ） } 对于 State 与 ViewState 几乎 1:1 映射的简单功能，映射器仍然是必需的，但很简单：内部类 SearchLogsViewStateMapper @Inject constructor() : ViewStateMapper { 覆盖有趣的地图（状态：SearchLogsState）：SearchLogsViewState = SearchLogsViewState（查询 = state.query.orEmpty(), 大小写敏感=状态.大小写敏感，） } #### 整合 **ViewModel** 将“ViewState”作为其第一个类型参数，并在构造函数中接受“viewStateMapper”。 ViewModel 在内部映射 State -> ViewState 并公开 `StateFlow`： @HiltViewModel 内部类 ItemsViewModel @Inject 构造函数（减速器：ItemsReducer， effectHandler：ItemsEffectHandler， viewStateMapper：ItemsViewStateMapper， ) : BaseStoreViewModel( 初始状态 = ItemsState(), 减速机=减速机， effectHandlers = listOf(effectHandler), 视图状态映射器 = 视图状态映射器, 初始SideEffects = listOf(ItemsSideEffect.LoadItems), ） **Fragment** 直接渲染“ViewState”——它不注入映射器： @AndroidEntryPoint 内部类 ItemsFragment : BaseStoreFragment< FragmentItemsBinding，项目视图状态，项目状态，项目命令，项目副作用，项目视图模型， >() { 通过 viewModels() 覆盖 val viewModel 覆盖乐趣渲染（状态：ItemsViewState）{ 绑定.processList(状态.items, state.itemsChanged) 绑定.processSelection(状态.selecting, 状态.selectedCount) } } #### 关键规则 * **状态** 不得包含表示模型 - 使用域模型或中间格式化模型 * **ViewState** 不能是 TEA State 类型 — 它是派生的，不由 Store 管理 * **ViewStateMapper** 从 `core/tea` 实现 `ViewStateMapper` 接口 * **ViewStateMapper** 必须是纯函数（无副作用，无可变状态）——映射在“viewStateMappingDispatcher”上运行（默认为“Dispatchers.Main.immediate”） * 对于昂贵的映射操作，请在 ViewModel 构造函数中重写“viewStateMappingDispatcher”（例如，传递“Dispatchers.Default”） * 昂贵的工作（过滤、格式化、IO）保留在后台调度程序的 **EffectHandler** 中 *廉价的工作（将选择/扩展/文本大小应用于预先格式化的项目）发生在**映射器**中 * 选择、扩展和类似的 UI 本地状态**直接存在于 State** 中，由 **Reducer** 作为纯函数进行管理 — 没有表示层存储库或用例 * 当Reducer修改需要外部同步的选择状态时，它会发出一个携带数据的SideEffect（例如`SyncSelectedLines(selectedIds)`）而不是依赖于内部存储库 ### 为方便起见，输入别名类型别名 AuthStore = Store 类型别名 AuthStoreViewModel = BaseStoreViewModel ** ** ## 2\.干净的架构 ### 层结构每个功能/模块包含三层： * **演示** ：UI 组件（视图/可组合项）和 ViewModel * **领域**：用例和存储库接口 * **数据**：数据源和存储库实现 ### 依赖规则介绍──────► 域（api 模块） ▲ 数据──────────┘ （实现模块） **关键规则：** * 表示层不能知道或访问除其域层（api 模块）之外的任何内容 * 表示层不得直接访问数据层（impl 模块） * 数据层依赖于领域层（实现存储库接口） * 演示文稿仅通过 ViewModel 触发操作 ### 命名约定类型 |名称 |能见度 ---|---|--- 接口 |普通名称（例如“LoginUseCase”）| `public` （在 api 模块中）实施 | `Impl` 后缀（例如，`LoginUseCaseImpl`）| `internal`（在 impl 模块中）数据源接口|普通名称（例如“AuthRemoteDataSource”）| `内部` 数据源实施 | `Impl` 后缀（例如，`AuthRemoteDataSourceImpl`）| `内部` 视图模型 |功能名称+“ViewModel”（例如“AuthViewModel”）| `内部` 存储库接口|普通名称（例如“AuthRepository”）| `public` （在 api 模块中）存储库实施 | `Impl` 后缀（例如，`AuthRepositoryImpl`）| `internal`（在 impl 模块中）减速机|功能名称+“Reducer”（例如“AuthReducer”）| `内部` 效果处理程序 |功能名称+角色+`EffectHandler`（例如`AuthNetworkEffectHandler`）| `内部` 状态|功能名称+“状态”（例如“AuthState”）| `内部` 视图状态 |功能名称+“ViewState”（例如“AuthViewState”）| `内部` 视图状态映射器 |功能名称+“ViewStateMapper”（例如“AuthViewStateMapper”）| `内部` **Reducers 和 Effect Handlers 的例外：**Reducers 和 Effect Handlers 不使用 `Impl` 后缀，因为它们已经在标题中包含了功能名称（例如，`AuthReducer`、`AuthNetworkEffectHandler`）。这使得命名更加简洁，同时仍然清晰。 ### 域层 #### 用例 **关键规则：** * 用例必须使用 `invoke` 运算符函数（允许 `useCase()` 语法） * 用例方法不得抛出 - 对于失败的操作返回 `Result` 类型 * 用例捕获存储库异常并将其转换为“结果” // 接口 - 在 api 模块中，公共接口LoginUseCase { 挂起操作员乐趣调用（电子邮件：字符串，密码：字符串）：结果<用户> } // 实现 - 在 impl 模块中，内部内部类LoginUseCaseImpl @Inject构造函数（ private val authRepository: AuthRepository, ) : 登录用例 { 覆盖挂起乐趣调用（电子邮件：字符串，密码：字符串）：结果<用户> { 返回runCatching { authRepository.login（电子邮件、密码） } } } // 不可失败的用例示例接口 MarkOnboardingCompletedUseCase { 暂停运算符 fun invoke() } 内部类 MarkOnboardingCompletedUseCaseImpl @Inject 构造函数（ private val onboardingRepository: OnboardingRepository, ) : MarkOnboardingCompletedUseCase { 覆盖挂起乐趣调用（）{ onboardingRepository.markOnboardingCompleted() } } #### 存储库接口 **关键规则：** * 存储库方法必须使用 `throws` （挂起可以抛出异常的函数）来执行失败的操作，而不是 `Result<*>` * 使用 `Flow` 作为响应式属性 // 在api模块中接口 AuthRepository { 暂停有趣的登录（电子邮件：字符串，密码：字符串）：用户暂停有趣的注销() val isAuthenticated: Flow<布尔值> } #### 领域模型 // 在api模块中数据类用户（有效 ID：字符串， val 电子邮件：字符串，值名称：字符串，） ### 数据层 #### 数据源数据源在数据模型 (DTO) 上运行。数据源接口在数据层中定义，并且是“内部”的。 **关键规则：** * 数据源接口必须在 **impl 模块** 中定义，而不是在 api 中 * 数据源接口必须是“内部”可见性 * 数据源只能在 impl 模块内访问 * 数据源不得从域或表示层访问 // DTO - 内部，在 impl 模块中内部数据类 UserDTO( 有效 ID：字符串， val 电子邮件：字符串，值名称：字符串，）内部数据类LoginRequestDTO( val 电子邮件：字符串， val 密码：字符串，） // 远程数据源接口 - INTERNAL，在 impl 模块中定义内部接口 AuthRemoteDataSource { 暂停有趣的登录（请求：LoginRequestDTO）：UserDTO 暂停有趣的注销() } // 实现 - 内部内部类 AuthRemoteDataSourceImpl @Inject 构造函数（私有val api：AuthApi， ) : AuthRemoteDataSource { 覆盖挂起有趣的登录（请求：LoginRequestDTO）：UserDTO { 返回 api.login(请求) } 覆盖挂起乐趣注销（）{ api.注销() } } // 本地数据源接口 - 内部内部接口 AuthLocalDataSource { 暂停有趣的 saveUser(用户: UserDTO) 暂停乐趣 getUser()：UserDTO？暂停clearUser()的乐趣 val isAuthenticated: Flow<布尔值> } // 实现 - 内部内部类 AuthLocalDataSourceImpl @Inject 构造函数（ private val dataStore: DataStore<首选项>, ) : AuthLocalDataSource { // 实现... } #### 存储库实施存储库组合数据源并将 DTO 映射到域模型。 // 实现 - 在 impl 模块中，内部内部类 AuthRepositoryImpl @Inject 构造函数（私有val远程数据源：AuthRemoteDataSource，私有val localDataSource：AuthLocalDataSource， ) : AuthRepository { 覆盖挂起有趣的登录（电子邮件：字符串，密码：字符串）：用户{ val dto = RemoteDataSource.login( LoginRequestDTO（电子邮件=电子邮件，密码=密码）） localDataSource.saveUser(dto) 返回 dto.toDomain() } 覆盖挂起乐趣注销（）{ runCatching { remoteDataSource.logout() } localDataSource.clearUser() } 覆盖 val isAuthenticated: Flow get() = localDataSource.isAuthenticated } // 映射扩展 - 在 impl 模块中内部乐趣 UserDTO.toDomain(): User = User( id = id, 电子邮件=电子邮件，姓名=姓名，） ** ** ## 3\.被动/容器视图模式 ### 规则 1. **没有视图可以处理业务逻辑状态** \-它们只显示提供给它们的数据 2.视图接受lambda来触发事件 3.视图必须是**幂等**（相同的输入=相同的输出） 4. 只有 **Container** 屏幕（Activity/Fragment/Composable with ViewModel）可以： * 持有并观察 ViewModel * 处理导航 * 注册生命周期回调 5. **容器是独立的** \-它们不能互相了解 6. ViewModel生命周期与Container生命周期绑定 7. **容器不得手动构建 ViewModel** \-它们使用 Hilt 注入 8. **容器之间没有回调** \- 使用反应式数据观察代替 ### 容器通信 // 错误：在容器之间使用回调类 ParentFragment : BaseFragment<...>() { 有趣的 showChild() { ChildFragment(onItemSelected = { 项目 -> viewModel.send(AuthCommand.ItemSelected(item)) // 错误：回调 }) } } // 正确：子级更新共享数据，父级观察更改类 ParentFragment : BaseFragment<...>() { // 父级效果处理程序通过用例观察共享数据更改 // 子进程通过用例更新共享数据 // 父级通过其观察自动接收更新 } ### 基础片段类基类抽象了 Flow 集合样板。功能片段只需要实现“render()”和“handleSideEffect()”。 `core/tea/android` 中有三个基本片段变体： * **BaseStoreFragment** — 用于具有 ViewBinding 的常规片段 * **BaseStoreBottomSheetFragment** — 用于具有 ViewBinding 的底部工作表对话框片段 * **BaseStorePreferenceFragment** — 用于首选项片段（无 ViewBinding）所有这三个都遵循相同的类型参数模式和 API。 // 在 core/tea/android 模块中 - TEA 架构的基础片段抽象类 BaseStoreFragment< VB：视图绑定，视图状态，国家，命令，副作用， VM : BaseStoreViewModel, > : 片段() { 私有变量_绑定：VB？ = 空受保护的 val 绑定：VB get() = _binding!! 受保护的抽象值视图模型：VM /** * 为此片段创建ViewBinding。 */ 抽象乐趣inflateBinding（膨胀器：LayoutInflater，容器：ViewGroup？）：VB /** * 将状态渲染到 UI。呼吁每一个州的改变。 * 必须是幂等的 - 相同的状态 = 相同的 UI。 * 接收 ViewState（已由 ViewModel 从域状态映射）。 */ 抽象乐趣渲染（状态：ViewState） /** * 处理副作用（导航、信息栏等） * 要求所有副作用 - 忽略那些与 UI 无关的副作用。 */ 抽象乐趣handleSideEffect（sideEffect：SideEffect） /** * 在视图创建之后、状态收集开始之前调用。 * 覆盖设置视图、点击监听器等。 * 接收者是 ViewBinding - 无需添加前缀“binding.”。 */ protected open fun VB.onViewCreated(view: View, savingInstanceState: Bundle?) = Unit 重写 fun onCreateView( 充气器：LayoutInflater，容器：ViewGroup？，已保存实例状态：捆绑？， ): 查看 { _binding = inflateBinding（充气机，容器）返回绑定.root } 覆盖 fun onViewCreated(view: View, savingInstanceState: Bundle?) { super.onViewCreated（视图，savedInstanceState）绑定.onViewCreated（视图，savedInstanceState） viewLifecycleOwner.lifecycleScope.launch { viewLifecycleOwner.repeatOnLifecycle(Lifecycle.State.STARTED) { 启动 { viewModel.state.collect { 状态 -> 渲染（状态） } } 启动 { viewModel.sideEffects.collect { 效果 -> handleSideEffect(effect) } } } } } 重写 fun onDestroyView() { super.onDestroyView() _绑定=空 } /** * 向 ViewModel 发送命令的便捷方法 */ 受保护的乐趣发送（命令：命令）{ viewModel.send(命令) } } #### BaseStoreBottomSheetFragment 与 BaseStoreFragment 相同的 API，但扩展了 `BottomSheetDialogFragment`： // 在 core/tea/android 模块中抽象类 BaseStoreBottomSheetFragment< VB：视图绑定，视图状态，国家，命令，副作用， VM : BaseStoreViewModel, > : BottomSheetDialogFragment() { // 相同的 API：inflateBinding、render、handleSideEffect、VB.onViewCreated、send } #### BaseStorePreferenceFragment 对于首选项屏幕。无 ViewBinding — 使用 PreferenceFragmentCompat 的内置首选项 XML 膨胀。 // 在 core/tea/android 模块中抽象类 BaseStorePreferenceFragment< 视图状态，国家，命令，副作用， VM : BaseStoreViewModel, > : PreferenceFragmentCompat() { 受保护的抽象值视图模型：VM 抽象乐趣渲染（状态：ViewState）抽象乐趣handleSideEffect（sideEffect：SideEffect） // send() 可用的便捷方法 } **与旧 API 的主要区别：** * **6 个类型参数**（添加 `ViewState` 作为第二个）：`` * `render()` 接收 **ViewState** ，而不是 State — 映射是在 ViewModel 中完成的 * `inflateBinding()` 替换 `createBinding()` * `VB.onViewCreated()` 是绑定上的扩展函数 - 覆盖它而不是直接覆盖 `onViewCreated()`。绑定是接收者，因此您可以直接访问视图而无需“绑定”前缀。 ### 特征片段示例 // Container Fragment - 使用 6 个类型参数扩展 BaseStoreFragment @AndroidEntryPoint 内部类 AuthFragment ：基础存储片段< FragmentAuthBinding，验证视图状态，验证状态，验证命令， AuthSideEffect，验证视图模型， >() { 通过 viewModels() 覆盖 val viewModel 覆盖乐趣 inflateBinding( 充气器：LayoutInflater，容器：ViewGroup？， ) = FragmentAuthBinding.inflate(inflater, 容器, false) // 在 VB.onViewCreated 中设置事件监听器 - 绑定是接收者重写 fun FragmentAuthBinding.onViewCreated(view: View, savingInstanceState: Bundle?) { loginView.onEmailChanged = { 发送(AuthCommand.EmailChanged(it)) } loginView.onPasswordChanged = { 发送(AuthCommand.PasswordChanged(it)) } loginView.onLoginClick = { 发送(AuthCommand.LoginTapped) } } 覆盖乐趣渲染（状态：AuthViewState）{ // 纯渲染 - 相同的 ViewState = 相同的 UI 绑定.loginView.bind(状态) } 覆盖乐趣handleSideEffect（sideEffect：AuthSideEffect）{ // 处理UI相关的副作用，忽略业务逻辑的副作用当（副作用）{ 是 AuthSideEffect.NavigateToHome -> { findNavController().navigate(AuthFragmentDirections.actionAuthToHome()) } 是 AuthSideEffect.ShowError -> { Snackbar.make（绑定.root，sideEffect.message，Snackbar.LENGTH_SHORT）.show（） } // 业务逻辑副作用 - 由 EffectHandlers 处理，此处忽略其他 -> 单位 } } } ### 功能 BottomSheet 片段示例 @AndroidEntryPoint 内部类 SearchLogsBottomSheetFragment ： BaseStoreBottomSheetFragment< 工作表搜索绑定，搜索日志视图状态，搜索日志状态，搜索日志命令，搜索日志副作用，搜索日志视图模型， >() { 通过 viewModels() 覆盖 val viewModel 重写 fun inflateBinding(inflater: LayoutInflater, 容器: ViewGroup?) = SheetSearchBinding.inflate（膨胀器，容器，假）重写 fun SheetSearchBinding.onViewCreated(view: View, savingInstanceState: Bundle?) { // 使用绑定接收器设置点击监听器 searchButton.setOnClickListener { 发送(SearchLogsCommand.UpdateQuery(queryText.text?.toString())) } } 覆盖有趣的渲染（状态：SearchLogsViewState）{ 绑定.queryText.setText(状态.query) 绑定.caseSensitiveCheckbox.isChecked = 状态.caseSensitive } 覆盖乐趣handleSideEffect（sideEffect：SearchLogsSideEffect）{ 当（副作用）{ 是 SearchLogsSideEffect.Dismiss -> 解雇() 其他 -> 单位 } } } ### 视图：带有 ViewBinding 的被动视图 // 被动视图 - 仅通过绑定方法显示数据，通过 lambda 触发事件类 LoginView @JvmOverloads 构造函数（上下文：上下文， attrs：属性集？ = 空， ) : FrameLayout(上下文, attrs) { 私有 val 绑定 = ViewLoginBinding.inflate(LayoutInflater.from(context), this) var onEmailChanged: ((String) -> 单位)? = 空 var onPasswordChanged: ((String) -> 单位)? = 空 var onLoginClick: (() -> 单位)? = 空初始化{ binding.emailEditText.doAfterTextChanged { onEmailChanged?.invoke(it.toString()) } binding.passwordEditText.doAfterTextChanged { onPasswordChanged?.invoke(it.toString()) } binding.loginButton.setOnClickListener { onLoginClick?.invoke() } } 有趣的绑定（状态：AuthState）{ 绑定.emailEditText.setTextIfDifferent(state.email) binding.passwordEditText.setTextIfDifferent(state.password) 绑定.loginButton.isEnabled = !state.isLoading 绑定.progressBar.isVisible = state.isLoading 绑定.errorText.text = 状态.error binding.errorText.isVisible = state.error != null } } // 防止光标跳跃的辅助扩展私人乐趣 EditText.setTextIfDifferent(text: String) { if (this.text.toString() != 文本) { this.setText(文本) } } ### Compose：被动可组合示例 // 正确：被动可组合 - 仅显示数据，通过 lambda 触发事件 @可组合有趣的登录内容（电子邮件：字符串，密码：字符串，正在加载：布尔值，错误：字符串？， onEmailChanged：（字符串）->单位， onPasswordChanged：（字符串）->单位， onLoginClick: () -> 单位, 修饰符：修饰符=修饰符，）{ 列（修饰符 = 修饰符.padding(16.dp), 垂直排列 = 排列.spacedBy(16.dp), ）{ 文本字段（值=电子邮件， onValueChange = onEmailChanged, 标签 = { 文本("电子邮件") }, ）文本字段（值=密码， onValueChange = onPasswordChanged, 标签 = { 文本("密码") }, 视觉变换 = 密码视觉变换(), ）错误？.let { 文本（文本=它，颜色=MaterialTheme.colorScheme.error，） } 按钮（ onClick = onLoginClick, 启用=！正在加载，）{ 如果（正在加载）{ CircularProgressIndicator(修改器 = Modifier.size(24.dp)) } 否则{ 文本（“登录”） } } } } // 错误：可组合处理其自身状态 @可组合有趣的登录内容错误（）{ var email by Remember { mutableStateOf("") } // 错误：可组合处理状态 var password by Remember { mutableStateOf("") } // 错误：可组合处理状态 var isLoading by Remember { mutableStateOf(false) } // 错误：可组合处理状态 // ... } ### 撰写：容器屏幕示例 // 容器 - 唯一可以保存 ViewModel 并处理生命周期的可组合项 // 状态已经是 ViewState （由 ViewModel 映射） @可组合有趣的验证屏幕（ viewModel: AuthViewModel = hiltViewModel(), onNavigateToHome: () -> 单位，）{ 通过 viewModel.state.collectAsStateWithLifecycle() 获取 val 状态启动效果（viewModel）{ viewModel.sideEffects.collect { sideEffect -> // 处理UI相关的副作用，忽略业务逻辑的副作用当（副作用）{ 是 AuthSideEffect.NavigateToHome -> onNavigateToHome() is AuthSideEffect.ShowError -> { /* 显示小吃栏 */ } // 业务逻辑副作用 - 由 EffectHandlers 处理，此处忽略其他 -> 单位 } } } 登录内容( 电子邮件=状态.电子邮件，密码 = 状态.密码, isLoading = 状态.isLoading, 错误=状态.错误， onEmailChanged = { viewModel.send(AuthCommand.EmailChanged(it)) }, onPasswordChanged = { viewModel.send(AuthCommand.PasswordChanged(it)) }, onLoginClick = { viewModel.send(AuthCommand.LoginTapped) }, ） } ### 嵌套被动视图 // 父被动视图 @可组合有趣的个人资料内容（用户：用户，设置：设置， onEditTapped: () -> 单位, onSettingChanged：（设置）-> 单位，修饰符：修饰符=修饰符，）{ 列（修饰符=修饰符）{ // 子被动视图 - 接收数据，传递 lambda 配置文件标题内容( 名称=用户名，电子邮件=用户.电子邮件， onEditTapped = onEditTapped, ） // 另一个子被动视图设置列表内容( 设置=设置， onSettingChanged = onSettingChanged, ） } } // 子被动视图 @可组合有趣的个人资料标题内容（名称：字符串，电子邮件：字符串， onEditTapped: () -> 单位, 修饰符：修饰符=修饰符，）{ 行（修饰符=修饰符）{ 列（修饰符= Modifier.weight（1f））{ 文本（文本=名称，样式=MaterialTheme.typography.headlineSmall）文本（文本=电子邮件，样式=MaterialTheme.typography.bodyMedium） } 图标按钮（onClick = onEditTapped）{ 图标（Icons.Default.Edit，contentDescription =“编辑”） } } } ** ** ## 4\.反应性数据流 ### 概述数据以反应方式驱动应用程序。使用 kotlinx.coroutines 中的 `StateFlow` 和 `SharedFlow` 来公开反应状态。 ### 存储库反应流 // 存储库与 Flow 接口 - 在 api 模块中接口 AuthRepository { val isAuthenticated: Flow<布尔值> 暂停有趣的登录（电子邮件：字符串，密码：字符串）：用户暂停有趣的注销() } 接口 OnboardingRepository { val wasOnboardingCompleted：Flow 暂停乐趣 markOnboardingCompleted() } 接口设置存储库{ val selectedServer：流<服务器？> 暂停乐趣 selectServer(服务器: 服务器) } ### 数据层中的 StateFlow 实现 **关键规则：** * 在数据源中私有地使用`MutableStateFlow` * 公开为“Flow”（只读） * 对于需要初始值的状态使用`StateFlow` // 实现 - 在 impl 模块中，内部内部类 AuthLocalDataSourceImpl @Inject 构造函数（ private val dataStore: DataStore<首选项>, ) : AuthLocalDataSource { 私有 val _isAuthenticated = MutableStateFlow(false) 覆盖 val isAuthenticated: Flow = _isAuthenticated.asStateFlow() 初始化{ // 初始化 val hasToken = getAccessToken() != null _isAuthenticated.value = hasToken } 覆盖挂起乐趣 saveTokens（令牌：AuthTokens）{ // ...保存令牌... _isAuthenticated.value = true } 覆盖挂起乐趣clearTokens（）{ // ... 清除标记 ... _isAuthenticated.value = false } } ### 合并流程使用 kotlinx.coroutines 中的“combine”来组合多个流。 // 组合多个流程的用例接口 ObserveAppStateUseCase { 运算符 fun invoke(): Flow } 内部类 ObserveAppStateUseCaseImpl @Inject 构造函数（ private val authRepository: AuthRepository, private val onboardingRepository: OnboardingRepository, ) : 观察AppStateUseCase { 覆盖 fun invoke(): Flow =合并( onboardingRepository.wasOnboardingCompleted， authRepository.isAuthenticated， ) { isOnboardingCompleted, isAuthenticated -> 当{ !isOnboardingCompleted -> AppScreen.Onboarding !isAuthenticated -> AppScreen.Auth 其他 -> AppScreen.Main } } } // 在 ViewModel 中的用法 @HiltViewModel 类 ContentViewModel @Inject 构造函数（ private valobserveAppStateUseCase：ObserveAppStateUseCase， ) : ViewModel() { val appScreen: StateFlow =observeAppStateUseCase() .stateIn( 范围 = viewModelScope, 开始=SharingStarted.WhileSubscribed(5000), 初始值 = AppScreen.Loading, ） } ** ** ## 5\.模块化 ### 概述该项目遵循模块化架构，具有两种类型的模块：**核心**和**功能**。 ### 模块类型 #### 核心模块 * **目的**：跨任何应用程序的可重用组件 * **示例**：基类、网络、持久性、通用 UI 组件 * **特点**： * 通用的，不是特定于应用程序的 * 可以提取为库 * 示例：`BaseFragment`、`BaseViewModel`、网络实用程序 #### 功能模块 * **目的**：应用程序特定功能 * **示例**：身份验证、配置文件、设置、特定域模型 * **特点**： * 包含特定于此应用程序的业务逻辑 * 特定领域的模型和用例 ### 模块结构每个模块最多可以包含 3 个 Gradle 模块：功能/授权/ ├── api/ # 强制 - 接口和领域模型 │ └── build.gradle.kts # 使用：logfox.kotlin.jvm（最好）或 logfox.android.library ├── impl/ # 强制 - 实现和 DI │ └── build.gradle.kts # 使用：logfox.kotlin.jvm（最好）或 logfox.android.feature + 取决于 api └──presentation/ # 可选 - UI 层（仅适用于具有 UI 的功能） └── build.gradle.kts # 使用：logfox.android.feature.compose + 仅依赖于 api #### API 模块（强制） * 包含接口和领域模型 * 尽可能使用纯 Kotlin (`logfox.kotlin.jvm`) * 仅当需要 Android 特定类型时才使用 `logfox.android.library` * **没有实现，没有 DI 注释** // feature/auth/api/src/main/kotlin/com/f0x1d/logfox/feature/auth/api/AuthRepository.kt 接口 AuthRepository { 暂停有趣的登录（电子邮件：字符串，密码：字符串）：用户 val isAuthenticated: Flow<布尔值> } // feature/auth/api/src/main/kotlin/com/f0x1d/logfox/feature/auth/api/LoginUseCase.kt 接口LoginUseCase { 挂起操作员乐趣调用（电子邮件：字符串，密码：字符串）：结果<用户> } // feature/auth/api/src/main/kotlin/com/f0x1d/logfox/feature/auth/api/User.kt 数据类用户（有效 ID：字符串， val 电子邮件：字符串，值名称：字符串，） #### impl 模块（强制） * 包含api接口的实现 * 包含数据源、DTO、映射器 * 包含 Hilt DI 模块 * 取决于api模块 * 尽可能使用纯 Kotlin，需要时使用 Android // feature/auth/impl/src/main/kotlin/com/f0x1d/logfox/feature/auth/impl/AuthRepositoryImpl.kt 内部类 AuthRepositoryImpl @Inject 构造函数（私有val远程数据源：AuthRemoteDataSource，私有val localDataSource：AuthLocalDataSource， ) : AuthRepository { // 实现... } // feature/auth/impl/src/main/kotlin/com/f0x1d/logfox/feature/auth/impl/di/AuthModule.kt @模块 @InstallIn(SingletonComponent::class) 内部接口 AuthModule { @绑定有趣的bindAuthRepository（impl：AuthRepositoryImpl）：AuthRepository @绑定有趣的bindLoginUseCase(impl: LoginUseCaseImpl): LoginUseCase } #### 演示模块（可选） * 包含 UI 组件（Views/Composables）和 ViewModels * 包含TEA组件：State、ViewState、ViewStateMapper、Command、SideEffect、Reducer、EffectHandler * **仅依赖于 api 模块** \- 决不依赖于 impl * Android库模块（UI组件所需） * 对 Compose UI 使用 `logfox.android.feature.compose` // feature/auth/presentation/src/main/kotlin/com/f0x1d/logfox/feature/auth/presentation/AuthViewModel.kt @HiltViewModel 内部类 AuthViewModel @Inject 构造函数( 减速器：AuthReducer，效果处理程序：AuthEffectHandler， viewStateMapper：AuthViewStateMapper， ) : BaseStoreViewModel( 初始状态 = AuthState(), 减速机=减速机， effectHandlers = listOf(effectHandler), 视图状态映射器 = 视图状态映射器, ） // feature/auth/presentation/src/main/kotlin/com/f0x1d/logfox/feature/auth/presentation/AuthScreen.kt @可组合有趣的验证屏幕（ viewModel: AuthViewModel = hiltViewModel(), ）{ val state by viewModel.state.collectAsStateWithLifecycle() // 已经是 ViewState // 实现... } ### 简化模块有时模块不需要完整的 3 模块结构： #### 核心实用模块（没有要公开的接口）核心/茶/ ├── 基地/ │ └── build.gradle.kts # 纯 Kotlin JVM - Store、Reducer、ReduceResult、EffectHandler、ViewStateMapper └── 安卓/ └── build.gradle.kts # Android - BaseStoreViewModel、BaseStoreFragment、BaseStoreBottomSheetFragment、BaseStorePreferenceFragment 核心/用户界面/ └── build.gradle.kts # 包含BaseActivity、主题核心/通用/ └── build.gradle.kts # 包含常用扩展、实用程序 #### 到处使用的通用数据模型功能/通用/ └── build.gradle.kts # 包含公共数据类，无需 api/impl 拆分 ### 模块之间的依赖规则：应用程序（取决于所有演示和实现模块） │ ┌────────────────┼────────────────┐ ▼ ▼ ▼ :功能: :功能: :核心: 身份验证：配置文件：网络：演示文稿演示文稿 impl │ │ │ ▼ ▼ ▼ :功能: :功能: :核心: 身份验证：api 配置文件：api 网络：api **关键规则：** * `presentation` 模块仅依赖于 `api` 模块 * `impl` 模块依赖于它们的 `api` 模块 * `impl` 模块可以依赖于其他模块的 `api` 模块 * `:app` 模块依赖于所有 `presentation` 和 `impl` 模块 * 永远不要依赖于另一个模块的 `impl` 模块（`:app` 除外） ### build.gradle.kts 示例 // 功能/auth/api/build.gradle.kts 插件{ 别名（libs.plugins.logfox.kotlin.jvm） } 依赖项{ api(libs.kotlinx.coroutines.core) // 对于流程 } // 功能/auth/impl/build.gradle.kts 插件{ 别名（libs.plugins.logfox.android.feature） } 依赖项{ api（项目.feature.auth.api）实施（projects.core.network.api）实施（projects.core.persistence.api） } // 功能/auth/presentation/build.gradle.kts 插件{ 别名（libs.plugins.logfox.android.feature.compose） } 依赖项{ 实现(projects.feature.auth.api) // 只有 api，从不 impl 实施（projects.core.ui.api） } ** ** ## 6\.依赖注入（Hilt） ### 概述使用 Hilt 进行依赖注入。每个功能的 impl 模块都包含其 DI 模块。 **关键规则：** * Hilt 模块返回类型必须是接口，而不是实现 * 实现 (`*Impl`) 绝不能直接在 impl 模块之外使用 * 使用`@Binds`将接口绑定到实现 * 使用`@Provides`提供需要配置的实例 ### 模块结构 // 在 feature/auth/impl 模块中 @模块 @InstallIn(SingletonComponent::class) 内部接口 AuthBindsModule { @绑定有趣的bindAuthRepository（impl：AuthRepositoryImpl）：AuthRepository @绑定有趣的bindLoginUseCase(impl: LoginUseCaseImpl): LoginUseCase @绑定有趣的bindLogoutUseCase（impl：LogoutUseCaseImpl）：LogoutUseCase } @模块 @InstallIn(SingletonComponent::class) 内部对象 AuthProvidesModule { @提供 @辛格尔顿有趣的provideAuthApi（改造：改造）：AuthApi { 返回retrofit.create(AuthApi::class.java) } } ### 数据源绑定 @模块 @InstallIn(SingletonComponent::class) 内部接口 AuthDataSourceModule { @绑定有趣的bindAuthRemoteDataSource（impl：AuthRemoteDataSourceImpl）：AuthRemoteDataSource @绑定 @Singleton // 关键：共享状态需要单例有趣的bindAuthLocalDataSource（impl：AuthLocalDataSourceImpl）：AuthLocalDataSource } ### TEA 组件绑定注意：Reducers、EffectHandlers 和 ViewStateMappers 是“@Inject”构造的，并直接在 ViewModel 构造函数中使用 - 在大多数情况下它们不需要 DI 模块绑定。 Hilt 可以直接构建它们。仅在以下情况下才需要 DI 模块绑定： * 您需要为多个效果处理程序提供`List>` * 您想要绑定到通用接口类型（例如，`Reducer`） // 对于多个效果处理程序，以列表形式提供 @模块 @InstallIn(ViewModelComponent::class) 内部对象 AuthEffectHandlersModule { @提供有趣的提供效果处理程序（网络处理程序：AuthNetworkEffectHandler， persistenceHandler：AuthPersistenceEffectHandler， ): List> = listOf( 网络处理程序，持久化处理程序，） } 实际上，大多数 ViewModel 直接注入具体的Reducer、EffectHandler 和ViewStateMapper 类型： @HiltViewModel 内部类 AuthViewModel @Inject 构造函数( reducer: AuthReducer, // 具体类型，无需绑定 effectHandler: AuthEffectHandler, // 具体类型，无需绑定 viewStateMapper: AuthViewStateMapper, // 具体类型，无需绑定 ) : BaseStoreViewModel(...) ### 范围和生命周期 @模块 @InstallIn(SingletonComponent::class) 内部接口 AuthModule { // 单例 - 应用程序生命周期内存在（共享状态） @绑定 @辛格尔顿有趣的bindTokenStore（impl：TokenStoreImpl）：TokenStore // 无作用域 - 每次都是新实例（无状态） @绑定有趣的bindLoginUseCase(impl: LoginUseCaseImpl): LoginUseCase } ### 单例数据源 **关键规则：** 维护共享状态的数据源（例如，“StateFlow”、内存中缓存）并由多个存储库使用**必须是单例**。 @模块 @InstallIn(SingletonComponent::class) 内部接口 AuthDataSourceModule { // SINGLETON：具有共享 StateFlow 的本地数据源 @绑定 @辛格尔顿有趣的bindAuthLocalDataSource（impl：AuthLocalDataSourceImpl）：AuthLocalDataSource } // 示例：具有共享状态的数据源内部类 AuthLocalDataSourceImpl @Inject 构造函数（ private val dataStore: DataStore<首选项>, ) : AuthLocalDataSource { 私有 val _isAuthenticated = MutableStateFlow(false) 覆盖 val isAuthenticated: Flow = _isAuthenticated.asStateFlow() 覆盖挂起乐趣 saveToken(token: String) { // 所有观察者都会收到此更新 _isAuthenticated.value = true } } ** ** ## 7\.导航 ### 概述使用 Jetpack Navigation 进行导航。支持基于 Fragment 的导航（旧版）和 Compose 导航。 ### 使用片段导航 // 使用 Safe Args 进行类型安全导航 // 导航图定义目的地 // 在片段中类 AuthFragment : BaseFragment() { private val viewModel: AuthViewModel by viewModels() 覆盖 fun onViewCreated(view: View, savingInstanceState: Bundle?) { super.onViewCreated（视图，savedInstanceState） viewLifecycleOwner.lifecycleScope.launch { viewModel.effects.collect { 效果 -> 当（效果）{ 是 AuthEffect.NavigateToHome -> { findNavController().navigate(AuthFragmentDirections.actionAuthToHome()) } 是 AuthEffect.NavigateToRegister -> { findNavController().navigate(AuthFragmentDirections.actionAuthToRegister()) } } } } } } ### 基于 SideEffect 的导航导航应该由Reducer 中的SideEffects 触发，而不是直接由UI 事件触发。 // SideEffect 包括导航变体密封接口 AuthSideEffect { // 业务逻辑数据类登录（val电子邮件：字符串，val密码：字符串）：AuthSideEffect 数据对象注销：AuthSideEffect // 用户界面/导航数据对象 NavigateToHome ：AuthSideEffect 数据对象 NavigateToRegister ：AuthSideEffect 数据类 NavigateToForgotPassword(val email: String?) : AuthSideEffect 数据类 ShowError(val message: String) : AuthSideEffect } // 容器处理导航（Compose） @可组合有趣的验证屏幕（ viewModel: AuthViewModel = hiltViewModel(), onNavigateToHome: () -> 单位， onNavigateToRegister: () -> 单位, ）{ 启动效果（viewModel）{ viewModel.sideEffects.collect { sideEffect -> 当（副作用）{ AuthSideEffect.NavigateToHome -> onNavigateToHome() AuthSideEffect.NavigateToRegister -> onNavigateToRegister() 是 AuthSideEffect.NavigateToForgotPassword -> { /* 导航 */ } is AuthSideEffect.ShowError -> { /* 显示小吃栏 */ } else -> Unit // 由 EffectHandlers 处理的业务逻辑 } } } // ... } // 容器处理导航（带有 BaseStoreFragment 的 Fragment）覆盖乐趣handleSideEffect（sideEffect：AuthSideEffect）{ 当（副作用）{ AuthSideEffect.NavigateToHome -> { findNavController().navigate(AuthFragmentDirections.actionAuthToHome()) } AuthSideEffect.NavigateToRegister -> { findNavController().navigate(AuthFragmentDirections.actionAuthToRegister()) } 是 AuthSideEffect.NavigateToForgotPassword -> { findNavController().navigate( AuthFragmentDirections.actionAuthToForgotPassword(sideEffect.email) ） } 是 AuthSideEffect.ShowError -> { Snackbar.make（绑定.root，sideEffect.message，Snackbar.LENGTH_SHORT）.show（） } else -> Unit // 由 EffectHandlers 处理的业务逻辑 } } ** ** ## 8\.约定插件 ### 可用插件插件 ID |描述 |使用案例 ---|---|--- `logfox.kotlin.jvm` |纯 Kotlin JVM 模块 |没有 Android 依赖的 api 模块 `logfox.android.library` | Android 库模块 | Android 特定的 api 或独立模块 `logfox.android.feature` |带 Hilt 的功能模块 |实现模块 `logfox.android.feature.compose` |功能+撰写+测试|带有 Compose UI 的演示模块 `logfox.android.hilt` |添加 Hilt DI |由功能插件自动添加 `logfox.android.compose` |添加撰写 |由撰写功能插件自动添加 `logfox.android.room` |添加房间数据库 |使用 Room 的模块 `logfox.android.parcelize` |添加地块 |具有可打包类的模块 ### 插件层次结构 logfox.android.feature.compose └── logfox.android.feature └── logfox.android.library └── logfox.android.hilt └── logfox.android.compose ### 用法示例 // 纯 Kotlin api 模块 // 功能/auth/api/build.gradle.kts 插件{ 别名（libs.plugins.logfox.kotlin.jvm） } // Android api 模块（当需要 Android 类型时） // core/context/api/build.gradle.kts 插件{ 别名（libs.plugins.logfox.android.library） } // 实现模块 // 功能/auth/impl/build.gradle.kts 插件{ 别名（libs.plugins.logfox.android.feature） } // 带有 Compose 的演示模块 // 功能/auth/presentation/build.gradle.kts 插件{ 别名（libs.plugins.logfox.android.feature.compose） } // 数据库模块 // core/database/impl/build.gradle.kts 插件{ 别名（libs.plugins.logfox.android.feature）别名（libs.plugins.logfox.android.room） } ** ** ## 9\.项目结构 ### 每个文件一种类型规则 **关键规则：** 每个文件必须包含一种类型（类、接口、对象、枚举或类型别名），无论可见性如何。 **规则：** * 一个文件=一种类型（类/接口/对象/枚举/数据类/类型别名） * 文件名必须与类型名称匹配（例如，“LoginUseCase.kt”代表“接口 LoginUseCase”） * 同一文件中允许有相同类型的扩展名 *同一文件中允许使用其他类型的私有辅助扩展 * 同一文件中没有私有/内部帮助程序类型 - 将它们提取到单独的文件中 * 将相关文件分组到适当的包中 **示例：** // 正确：每个文件一种类型域/用例/ ├── LoginUseCase.kt // LoginUseCase 接口 ├── LoginUseCaseImpl.kt // 类 LoginUseCaseImpl ├── LogoutUseCase.kt // LogoutUseCase 接口 ├── LogoutUseCaseImpl.kt // 类 LogoutUseCaseImpl // 错误：一个文件中有多种类型域/用例/ ├── AuthUseCases.kt // 包含LoginUseCase、LogoutUseCase等 ### 文件夹组织应用程序/ ├── src/main/kotlin/com/f0x1d/logfox/ │ ├── App.kt # 应用程序类 │ ├── MainActivity.kt # 主活动 │ └── 导航/ │ └── AppNavigation.kt # 根导航核心/ ├── 茶/ │ ├── 基地/ │ │ └── src/main/kotlin/com/f0x1d/logfox/core/tea/ │ │ ├── Store.kt # TEA Store 实现 │ │ ├──Reducer.kt #Reducer接口 │ │ ├──ReduceResult.kt #ReduceResult数据类 │ │ ├── EffectHandler.kt # EffectHandler接口（扩展Closeable） │ │ └── ViewStateMapper.kt # ViewStateMapper接口 │ └── 安卓/ │ └── src/main/kotlin/com/f0x1d/logfox/core/tea/ │ ├── BaseStoreViewModel.kt # TEA 的基础 ViewModel │ ├── BaseStoreFragment.kt # TEA 的基础片段 │ ├── BaseStoreBottomSheetFragment.kt # TEA 的基础 BottomSheet │ └── BaseStorePreferenceFragment.kt # TEA 的基础 PreferenceFragment ├── 用户界面/ │ └── src/main/kotlin/com/f0x1d/logfox/core/ui/ │ ├── BaseFragment.kt # 简单的基础Fragment │ └── 主题/ │ ├── 主题.kt │ └── 颜色.kt ├── 网络/ │ ├── API/ │ │ └── src/main/kotlin/com/f0x1d/logfox/core/network/api/ │ │ ├── HttpClient.kt # 接口 │ │ └── NetworkError.kt # 密封类 │ └── 实现/ │ └── src/main/kotlin/com/f0x1d/logfox/core/network/impl/ │ ├── HttpClientImpl.kt # 实现 │ └── 迪/ │ └── NetworkModule.kt # Hilt 模块 ├── 坚持/ │ ├── API/ │ │ └── src/main/kotlin/com/f0x1d/logfox/core/persistence/api/ │ │ └── DataStoreClient.kt # 接口 │ └── 实现/ │ └── src/main/kotlin/com/f0x1d/logfox/core/persistence/impl/ │ ├── DataStoreClientImpl.kt │ └── 迪/ │ └── PersistenceModule.kt └── 常见/ └── src/main/kotlin/com/f0x1d/logfox/core/common/ └── 扩展/ ├── FlowExtensions.kt └── ContextExtensions.kt 特点/ ├── 授权/ │ ├── API/ │ │ └── src/main/kotlin/com/f0x1d/logfox/feature/auth/api/ │ │ ├── AuthRepository.kt │ │ ├── LoginUseCase.kt │ │ ├── LogoutUseCase.kt │ │ └── 用户.kt │ ├── 实现/ │ │ └── src/main/kotlin/com/f0x1d/logfox/feature/auth/impl/ │ │ ├── AuthRepositoryImpl.kt │ │ ├── LoginUseCaseImpl.kt │ │ ├── LogoutUseCaseImpl.kt │ │ ├── 数据源/ │ │ │ ├── AuthRemoteDataSource.kt │ │ │ ├── AuthRemoteDataSourceImpl.kt │ │ │ ├── AuthLocalDataSource.kt │ │ │ └── AuthLocalDataSourceImpl.kt │ │ ├── dto/ │ │ │ ├── UserDTO.kt │ │ │ └── LoginRequestDTO.kt │ │ ├── 映射器/ │ │ │ └── UserMapper.kt │ │ └── di/ │ │ └── AuthModule.kt │ └── 演示/ │ └── src/main/kotlin/com/f0x1d/logfox/feature/auth/presentation/ │ ├── AuthViewModel.kt # 特征ViewModel │ ├── AuthState.kt # 内部域状态 │ ├── AuthViewState.kt # 演示就绪的 ViewState │ ├── AuthViewStateMapper.kt # State -> ViewState 映射器（实现 ViewStateMapper） │ ├── AuthCommand.kt # 用户操作/反馈命令 │ ├── AuthSideEffect.kt # 副作用（业务+UI） │ ├── AuthReducer.kt # 纯reducer函数 │ ├── AuthNetworkEffectHandler.kt # 网络副作用处理程序 │ ├── AuthPersistenceEffectHandler.kt # 持久化副作用处理程序 │ ├── AuthScreen.kt # 容器可组合项 │ ├── AuthFragment.kt # 容器片段（如果使用视图） │ └── 组件/ │ ├── LoginContent.kt # 被动可组合 │ └── 注册内容.kt ├── 简介/ │ ├── API/ │ ├── 实现/ │ └── 演示/ └── 设置/ ├── API/ ├── 实现/ └── 演示/ ### 包命名 **关键规则：** 每个 api、impl 和演示 Gradle 模块都必须包含其模块类型作为包段。封装模式为： com.f0x1d.logfox.<模块类型>.<模块名称>.[.subpackage] 其中： * `` 是 `feature` 或 `core` * `` 是功能/核心名称（例如，`auth`、`logging`、`preferences`） * ``对应Gradle子模块 **示例：** Gradle 模块 |包根目录 ---|--- `：应用程序` | `com.f0x1d.logfox` `:功能:auth:api` | `com.f0x1d.logfox.feature.auth.api` `:feature:auth:impl` | `com.f0x1d.logfox.feature.auth.impl` `：功能：身份验证：演示` | `com.f0x1d.logfox.feature.auth.presentation` `：核心：首选项：api` | `com.f0x1d.logfox.core.preferences.api` `：核心：首选项：impl` | `com.f0x1d.logfox.core.preferences.impl` `:core:ui:base` | `com.f0x1d.logfox.core.ui`（独立，无 api/impl 拆分）每个模块内的子包自然如下： com.f0x1d.logfox.feature.auth.api.data # 存储库接口 com.f0x1d.logfox.feature.auth.api.domain # 用例接口 com.f0x1d.logfox.feature.auth.api.model # 域模型 com.f0x1d.logfox.feature.auth.impl.data # 存储库实现、数据源 com.f0x1d.logfox.feature.auth.impl.di # Hilt 模块 com.f0x1d.logfox.feature.auth.impl.domain # 用例实现 com.f0x1d.logfox.feature.auth.presentation.ui # 片段、屏幕 **为什么这很重要：** * 防止 api 和 impl 模块之间的包冲突（例如，两者都有一个“data”子包） * 从导入中可以立即看出类属于哪个模块 * `build.gradle.kts` 中的 `android.namespace` 必须与包根目录匹配（例如，`com.f0x1d.logfox.feature.auth.api`） ** ** ## 关键规则总结 1. **TEA模式**：状态是不可变的，命令通过Reducer触发状态更改，SideEffects由EffectHandlers（业务）和UI（导航/toast）处理 2. **Reducer** ：纯函数，接受 State + Command，返回新的 State + SideEffects。减速器不允许产生任何副作用 3. **EffectHandler** ：异步处理 SideEffects，`onCommand` 是 **suspend** 并使用 `withContext(Dispatchers.Main.immediate)` 调用 `Store.send()`。扩展“Closeable”以进行资源清理 4. **Store.send()** ：必须仅从主线程调用 5. **SideEffects** ：服务双重目的 - 业务逻辑（由 EffectHandler 处理）和 UI 操作（由 Fragment/Composable 处理） 6. **ViewState 是强制的** ：每个功能都有 State（域，由Reducer 管理）和 ViewState（表示，由 ViewStateMapper 派生）。 ViewStateMapper 实现了 `core/tea` 中的 `ViewStateMapper` 接口 7. **BaseStoreViewModel** ：4个类型参数 ``，在内部映射 State -> ViewState，公开 `StateFlow` 8. **BaseStoreFragment** ：6个类型参数``，渲染ViewState，使用`inflateBinding()`和`VB.onViewCreated()` 9. **基础片段变体**：`BaseStoreFragment`、`BaseStoreBottomSheetFragment`、`BaseStorePreferenceFragment` \- 全部位于 `core/tea/android` 中 10. **core/tea 模块拆分** ： `core/tea/base/` （纯 Kotlin JVM - Store、Reducer、ReduceResult、EffectHandler、ViewStateMapper）和 `core/tea/android/` （Android - BaseStoreViewModel、BaseStoreFragment 等） 11. **用例**：必须使用 `invoke` 运算符，对于失败的操作返回 `Result` 12. **存储库**：方法可以抛出、公开“Flow”以获取反应数据 13. **数据源**：impl模块内部，从不暴露于外部 14. **Views** ：被动，仅通过 lambdas 显示数据和触发事件 15. **模块化**：api/impl/presentation结构，presentation仅依赖于api 16. **DI** ：对接口使用 Hilt `@Binds`，对共享状态使用单例。 TEA 组件（Reducer、EffectHandler、ViewStateMapper）是通过“@Inject”构建并直接使用的 - 除非提供列表，否则不需要 DI 绑定 17. **Navigation** ：基于 SideEffect，在容器组件中处理 18. **文件结构**：每个文件一种类型，文件名与类型名称匹配 19. **约定插件**：为每个模块类型使用适当的插件 20. **包命名**：每个 api/impl/presentation 模块必须包含其模块类型作为包段：`com.f0x1d.logfox...`。 `build.gradle.kts` 中的 `android.namespace` 必须与此包根匹配

安卓架构

包含技能