Swift Composable Architecture 弃用 API 迁移指南：Effect 弃用类型 TaskResult 及其替代方案

前端移动开发【免费下载链接】swift-composable-architectureA library for building applications in a consistent and understandable way, with composition, testing, and ergonomics in mind.项目地址https://gitcode.com/GitHub_Trending/sw/swift-composable-architecture点击查看免费下载本文依据 TCA 官方文档中的 Effect 弃用 API 清单EffectDeprecations.md撰写。该清单聚焦于与 Effect 相关的已弃用 API目前列出唯一一个弃用类型TaskResult。本文将以它为骨架结合官方 1.4 迁移指南MigratingTo1.4.md与源码实现Deprecations.swift完整讲解TaskResult的来龙去脉、弃用原因、源码细节以及如何迁移到标准库Result与基于 case key path 的新式测试断言语法。一、弃用 API 清单文档的结构与阅读方式在 TCA 官方文档中Deprecations系列页面是开发者快速了解哪些 API 不再受支持、应该用什么替代的入口。以本主题的 EffectDeprecations.md 为例文档本身采用 DocC 标准结构Overview明确建议避免在应用中使用已弃用 API选择一个方法查看你应该使用的替代品Topics → Deprecated types列出当前 Effect 相关的弃用类型即TaskResult。在 Xcode 的 DocC 渲染中点击TaskResult符号即可跳转到该类型的完整文档页其中会展示弃用消息以及指向迁移指南的链接。这一系列Deprecations文档与仓库目录 Sources/ComposableArchitecture/Documentation.docc/Extensions/Deprecations/ 下的其他页面如ReducerDeprecations.md、ScopeDeprecations.md、StoreDeprecations.md、SwiftUIDeprecations.md、TestStoreDeprecations.md共同构成 TCA 的弃用 API 总索引。需要注意的是这份清单页本身只承担导航作用真正的替代说明位于对应迁移指南中。对于TaskResult其替代说明集中在 MigratingTo1.4.md 的 Moving off of TaskResult 章节第 209–255 行下文将以此为权威依据展开。二、TaskResult 是什么为 Equatable 测试而生的 Result 变体2.1 源码定义TaskResult的完整实现在 Deprecations.swift 第 3438–3622 行。其核心定义是一个两分支枚举public enum TaskResultSuccess: Sendable: Sendable { case success(Success) case failure(any Error) }从源码结构看它提供了以下主要 APIinit(catching:)异步执行一段Sendable () async throws - Success闭包do/catch包裹后自动映射为.success或.failureinit(_ result: ResultSuccess, Failure)由标准库Result直接转换而来var value: Successget throws提取成功值失败时抛出底层错误map/flatMap对成功值做变换失败分支原样传递CasePathable实现提供success、failure两个 case path方便在 reducer 与测试中用 case path 语法解构Equatable/Hashable条件扩展在Success: Equatable/Hashable时可用。2.2 诞生的历史动机为什么 TCA 曾经需要这样一个重复造轮子的类型官方迁移指南给出了完整解释MigratingTo1.4.mdResultSuccess, Failure在Failure any Error时不满足Equatableany Error本身不可比较相等而 TCA 的 reducerAction类型希望是Equatable的原因是TestStore需要比较effect 发出的 action 是否与断言一致于是 TCA 设计了TaskResult把错误侧弱化为any Error通过特殊实现让Action可以相等比较从而支撑 effect 动作的测试断言。2.3 源码中的运行时警告设计TaskResult的Equatable实现值得注意Deprecations.swift 第 3550–3582 行当两个.failure的错误类型一致但错误本身不可比较时它会在 DEBUG 构建下通过reportIssue输出运行时警告提示该类型不满足 Equatable请显式声明extension X: Equatable {}。同样的机制也出现在Hashable实现中。从 TestStore.swift 第 1242 行可以看到TestStore在运行测试时还会通过TaskResultDebugging.$emitRuntimeWarnings.withValue(false)临时关闭这些警告避免测试输出被噪音干扰。三、为什么被弃用case key path 让 Equatable 断言不再必要官方在 TCA 1.4 版本中做出两个关键动作直接导致TaskResult失去存在意义引入Reducer宏自动为 feature 的Action枚举以及枚举形态的State应用CasePathable由CasePathable派生出的case key path语法让测试断言可以只描述收到了哪个 case而无需比较 action 携带的具体数据。官方对弃用的措辞非常明确MigratingTo1.4.md 第 209–212 行在 1.4 版本中TaskResult被软弃用soft-deprecated并最终会被完全弃用后移除第 253–255 行进一步说明有了更好的语法之后TaskResult存在的理由变少了我们计划最终移除它。对应的弃用消息Deprecations.swift 第 3438–3442 行直接指向迁移方案Use Result, instead. See the following migration guide for more information: .../documentation/composablearchitecture/migratingto1.4#Moving-off-of-TaskResult即用标准库Result替换TaskResult用 case key path 语法重写测试断言。四、迁移实战一用标准库 Result 替换 TaskResult迁移第一步是把 effect 返回类型从TaskResultT换成ResultT, any Error。由于TaskResult自身提供了init(_ result:)同时标准库Result也提供了从TaskResult转换的初始化方法Deprecations.swift 第 3529–3544 行两种类型可以低成本互转。典型的 effect 写法对比// 迁移前返回 TaskResult return .run { send in let result await TaskResult { try await self.client.fetch() } await send(.response(result)) } // 迁移后返回 ResultT, any Error return .run { send in do { let value try await self.client.fetch() await send(.response(.success(value))) } catch { await send(.response(.failure(error))) } }在此基础上Action的Equatable依赖可以解除如果唯一阻碍Action满足Equatable的是TaskResult中的any Error迁移后即可移除这些 conformance官方明确表示若你只用 case key path 风格接收 action甚至可以完全停止让Action遵循Equatable。五、迁移实战二用 case key path 重写测试断言TaskResult存在的根本目的是支撑effect 发出动作的测试断言。迁移的核心是把断言语法从构造完整具体 action改为描述 case 路径。5.1 从具体值到 key path迁移前TestStore的receive需要给出完整 action并要求Action可比较相等store.receive(.response(.success(Hello!))) { // 状态断言... }嵌套较深的集成测试会非常啰嗦store.receive(.child(.response(.success(Hello!)))) { // ... }迁移后用 case key path 语法直接描述 case 的嵌套路径store.receive(\.child.response.success) { // ... }官方特别说明这种语法不要求Action遵循Equatable因为此时只断言收到了该 caseaction 携带的数据通常已由receive尾随闭包中的状态断言覆盖。5.2 三点进阶用法官方在迁移指南中给出了三处值得注意的进阶场景PresentationAction 可省略presented路径组件对于PresentationActionstore.receive(\.child.presented.response.success)可简写为store.receive(\.child.response.success)IdentifiedAction 按下标接收store.receive(\.rows[id: 0].response.success)即通过IdentifiedAction的subscript(id:)定位集合中的指定元素StackAction 同样支持store.receive(\.path[id: 0].response.success)可用于NavigationStack路径上的元素断言。5.3 使用前提case key path 语法要求每一层嵌套的枚举都是CasePathable。经由Reducer宏生成的 featureAction通常自动满足其他自定义枚举需要显式标注CasePathable enum DelegateAction { case didFinish(success: Bool) }六、源码佐证Effect 相关的其他弃用形态虽然 EffectDeprecations.md 当前仅列出TaskResult一个弃用类型但从源码看Effect相关的旧式 API 弃用还体现在 Effect.swift 与 Deprecations.swift 中可作为迁移时的背景参考Effect.concatenate顺序串联多个 effect已标记弃用消息为 Sequence work directly in a .run insteadEffect.swift 第 288–315 行。替代方式是在单个.runeffect 内按顺序await执行Effect.map变换 effect 发出的 action已标记弃用消息为 Avoid transforming effects; construct them directly in a feature insteadEffect.swift 第 427–456 行。替代方式是直接在 feature 内构造出对应 action 的 effectEffect.send(_:animation:)、Effect.animation(_:)、Effect.transaction(_:)等旧式修饰器在 Deprecations.swift 中以available形式保留为弃用形态。这些弃用的共同趋势是把曾经通过组合器combinator表达的 effect 逻辑收敛到单一、直接的.runeffect 与Send机制中。当前文档中的Effect.run(priority:name:operation:catch:)与SendAction是这一演进的最终形态Effect.swift 第 92–136 行、第 180–216 行。七、总结与迁移检查清单围绕 EffectDeprecations.md 中的弃用类型TaskResult完整迁移路径可以收敛为三步替换类型TaskResultT→ResultT, any Error利用两个类型间的互转init平滑过渡Deprecations.swift 第 3456–3464 行、第 3529–3544 行重写断言store.receive(.child(.response(...)))→store.receive(\.child.response.success)嵌套场景利用PresentationAction省略、IdentifiedAction/StackAction的id下标MigratingTo1.4.md 第 190–207 行清理 conformance在完全切换到 key path 断言后Action的Equatableconformance 可以按需移除。最终效果是effect 类型更贴近标准库、测试断言更短且类型更安全同时消除了因any Error不可比较而引入的运行时警告。如果你有TaskResult的独特使用场景认为它值得保留在库中官方也邀请到仓库 Discussions 中发起讨论MigratingTo1.4.md 第 253–255 行。赞分享前端移动开发【免费下载链接】swift-composable-architectureA library for building applications in a consistent and understandable way, with composition, testing, and ergonomics in mind.项目地址https://gitcode.com/GitHub_Trending/sw/swift-composable-architecture点击查看免费下载相关推荐TestStore 弃用 API 迁移指南swift-composable-architecture 中已废弃测试接口的识别与替换TestStore 弃用 API 迁移指南swift composable architecture 中已废弃测试接口的识别与替换 在 swift compo前端移动开发swift-composable-architecture SwiftUI 弃用 API 迁移指南从 ViewStore 走向 ObservableStateswift composable architecture SwiftUI 弃用 API 迁移指南从 ViewStore 走向 ObservableStat前端移动开发如何用 OpenArk 三步定位并清除 Windows 全局热键冲突新手教程如何用 OpenArk 三步定位并清除 Windows 全局热键冲突新手教程 复制粘贴快捷键突然失灵或者你辛苦配好的自定义快捷键被刚装的某个软件悄悄抢前端移动开发上一篇OpenMed ICD-11 离线接地从 WHO ICD-API 构建发布固定快照到本地精确匹配与 FHIR 导出下一篇Civitai 审核模块 Prisma→Kysely 移植偏差实录从 EXPLAIN 校验网到翻译决策清单创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考