RxJS 7 到 RxJS Next 迁移评估与生命周期契约指南Assessment、Baseline 与 Target Contract 实战【免费下载链接】rxjsA reactive programming library for JavaScript项目地址: https://gitcode.com/gh_mirrors/rx/rxjs本文聚焦于 RxJS 仓库packages/migrate迁移工具链中assessment-and-contract.md这份核心参考文档系统讲解如何对存量 RxJS 7 应用进行仓库评估repository assessment、覆盖度处置coverage disposition、行为表征测试characterization与目标生命周期契约target lifecycle contract的订立。读者将掌握如何用可验证证据替代直觉判断、何时必须暂停等待开发者决策、以及如何把每个生命周期敏感单元记录进结构化的迁移契约清单从而为rxjs/migrate引擎的机械改写与后续验证提供可靠基线。文档定位贯穿迁移流程 Stage 2 至 Stage 4 的评估与契约基线在packages/migrate的八阶段迁移工作流见 SKILL.md中assessment-and-contract.md明确说明自己服务于Stage 2评估使用、生命周期风险与覆盖度至 Stage 4分类并批准目标契约三个阶段。它的核心纪律是先收集证据再向开发者提出目标契约选择只询问仓库本身无法证明的**意图intent**问题凡能通过代码、测试或配置证明的事实一律自行取证拒绝“从语法、文件名、操作符名称或当前通过测试”推断平台共享或每次订阅独立生产者的行为。这意味着该文档不是一份“迁移清单”而是一套证据纪律迁移是否完成不取决于 diff 是否干净而取决于每个生命周期敏感点是否拥有明确的覆盖处置与开发者批准的目标生命周期。仓库评估十大主题的系统取证文档要求评估者记录确切的文件位置以及驱动每个发现finding的命令或测试检索范围覆盖应用源码、共享库、测试、配置、fixtures、构建工具与框架胶水代码。下表是文档给出的完整取证主题框架主题检索内容行为性问题Construction构造new Observable、defer、自定义生产者、包装器生产者工作何时创建与重启Repeated subscription重复订阅retry、refresh、fan-out、缓存失效、多消费者消费者必须各自运行独立工作还是共享一个活动运行Subjects当前/重放值、迟到订阅者、终止状态观察之前存在什么迟到观察者必须看到什么Ownership所有权捕获的订阅、unsubscribe、组件销毁谁取消、因何取消、上游何时停止Teardown多个 teardown 回调、finalizer、资源释放Observable 顺序是否重要Timing时序scheduler、timer、动画、队列排序、虚拟时间哪个宿主时序边界能保留该声明Errorsselector 错误、观察者回调错误、迟到错误错误必须在何处投递或上报Inputsiterables、async iterables、promises、自定义 subscribables该值是否被平台转换边界接受Composition组合pipeable 操作符、别名、高阶管道是否存在针对该精确形式的 fixture 验证过的 Symbol 映射TestingTestScheduler 助手、框架断言、native/polyfill 设置哪些声明是真实行为哪些是 harness 机制文档特别强调两点必须追踪导入与辅助包装器避免把传递性transitive使用误判为“不存在”采样sampling仅在明确说明其局限并被接受时才是允许的。从packages/migrate的工程实践看这条规则直接对应着引擎“有界语法子集bounded syntax subset”的定位——引擎见 engine-and-batches.md只对被 fixture 证明的精确源码形态负责评估阶段的“追踪导入”正是为了把依赖传递造成的隐性 RxJS 使用纳入 scope。覆盖处置每个生命周期敏感发现的唯一归档评估产出不是一份“风险列表”而是给每个生命周期敏感发现一个唯一处置disposition。文档定义了四种处置Covered已覆盖存在一个命名的既有测试证明了相关行为Characterize需表征迁移前需新增一个聚焦的 RxJS 7 测试Unsupported不支持没有任何已接受的 Next 表面surface能保留所需声明必须保留证据并记录为产品缺口product gapAccepted uncovered risk已接受未覆盖风险开发者明确接受在缺失证据的情况下继续必须记录批准人、时间、理由与影响。文档明确建议对以下行为优先推荐Characterize重复订阅、副作用、共享sharing、迟到订阅者、取消、teardown、时序、错误以及公共 API 行为——当现有测试不能证明其结果时。这条处置逻辑与迁移工具链的“证据分类evidence classification”一一对应。在 types.ts 中兼容性分类被枚举为portable、harness-rewrite、compatibility-only、intentional-divergence、unsupported-or-obsolete五类在 schemas.ts 的 manifest schema 中每个迁移单元unit都必须携带一个evidenceClassification并接受 schema 级校验。也就是说评估阶段的“处置”在契约阶段会被固化为可机器校验的分类字段。表征协议用最窄的测试证明对外有意义的声明Characterize 不是“随便补个测试”而是遵循严格的协议添加最窄的测试证明一个**对外有意义externally meaningful**的声明优先断言值本身、完成/错误、生产者启动次数、并发与迟到观察、取消所有权、abort 原因、teardown 顺序、虚拟或宿主时序、可见副作用避免锁定无关的 RxJS 7 内部实现internals新测试必须在未变更的 RxJS 7 依赖上运行记录精确命令与结果关键限定在依赖迁移之后才添加的表征测试不能算作 RxJS 7 基线——除非它在固定的源环境下单独演示过。这最后一条直接对应 SKILL.md 中“在任何依赖或源码变更前建立 RxJS 7 基线”的不可协商规则non-negotiable rules也解释了迁移报告模板中 migration-report.md 的“RxJS 7 baseline”表格为何要求记录 Check ID、Command、Environment、Exit、Result 与“接受的既有失败”。在测试形态上表征协议与 test-migration.md 中的语义保持一致cold()代表 producer-per-subscription 证据、hot()代表 subject 式绝对时间线、observable()代表共享且 ref-counted 的平台生产者、flush()是异步的必须await。这些助手选择本身就是一种“表征声明”应当在评估阶段被识别并在契约中体现。生命周期决策记录六个合法值与其行为语义文档禁止对平台 Observable 使用笼统的“热hot/冷cold”标签并给出了一个精确的行为图景第一个观察者启动活动生产者并发观察者加入其中最后一个观察者离开时拆解它后续观察者可以启动新一轮运行。基于此文档要求只使用已安装契约清单 schema 接受的生命周期值共六种active platform producer shared and ref-counted while observers exist观察者存在期间平台生产者被共享并按引用计数管理producer work created per direct subscription through an explicit Next API通过显式 Next API每次直接订阅创建生产者工作intentional hot Subject behavior有意的热 Subject 行为no producer lifecycle applies不适用生产者生命周期required behavior is unsupported所需行为不受支持intent remains unresolved意图仍未解决。这与源码中的targetLifecycles枚举完全对应。在 types.ts 中合法值是platform-shared、producer-per-direct-subscription、subject-hot、not-applicable、unsupported、unresolved在 schemas.ts 中还有一条重要的交叉校验unresolved或unsupported单元不允许使用not-required审批状态——它们必须具有显式的审批记录。对每个单元文档要求记录 7 项内容稳定的 ID 与精确源码范围source spans当前 RxJS 7 声明claim与证据选定的目标生命周期被已安装 schema 接受的兼容性/证据分类一条或多条目标声明target claims审批状态、批准人、时间戳与理由如需相关的诊断、分歧divergences与阻塞项blockers。这套 7 项记录正是 schemas.ts 中migrationContractUnitSchema的字段映射id、sourceLocationsspan 数组、lifecycle、evidenceClassification、claims、approval外加 manifest 级收集的diagnostics、intentionalDivergences与blockers。其中sourceSpanSchemaschemas.ts要求仓库相对路径且禁止..父级穿越确保契约中的源码位置在仓库根内可解析。强制开发者暂停引擎识别风险人批准意图文档最独特的设计是Mandatory developer pauses——当出现以下任一情况时暂停而非推断独立与共享生产者行为都说得通both plausible重复订阅可能实现 retry、refresh、cache 或 fan-outSubject 重放、终止或迟到观察者行为未经证明取消所有权、abort 原因或 teardown 顺序可能改变移除 scheduler 可能改变排序自定义 subscribable 超出已接受的转换边界公共声明变化或期望需要变化覆盖缺失或基线不绿not green某个单元在就绪评估中仍未解决、未获接受地不支持、或处于待审批状态。文档的关键结论是引擎的诊断可以识别暂停条件但只有开发者才能批准生命周期意图或有意分歧intentional divergence。这与引擎的实现分工一致——cli.ts 中runCli在 dry-run 时返回结构化 JSON 报告与退出码success0、refused1、invalidArguments2、operationalFailure3任何refused结果都会让整个批次保持“拒绝”状态而不写盘而意图选择始终发生在引擎之外、由人完成。契约与就绪评估从“形状正确”到“可以关闭”契约写完后还必须经过两道分离的检查见 verification-and-closeout.md结构有效性schema validity只回答“形状是否正确”由migrationContractManifestSchema校验就绪评估readiness assessment独立运行assessMigrationContractReadiness实现在 schemas.ts用于检测引擎版本、能力注册表版本、Skill digest 与已安装包不一致engine-version-mismatch、capability-registry-version-mismatch、skill-digest-mismatch基线未绿或未运行baseline-not-green、缺少迁移后验证或验证未绿verification-missing、verification-not-green未解决生命周期单元unit-unresolved、不支持单元unit-unsupported、待审批approval-pending未解决诊断diagnostic-unresolved、未批准分歧divergence-unapproved、未接受阻塞项blocker-unaccepted。评估最终给出三种状态之一ready、ready-with-accepted-blockers、incomplete见 types.ts。只有就绪评估返回前两种状态迁移才能宣称关闭且ready-with-accepted-blockers要求每个阻塞项都显式命名 owner、理由、受影响单元、证据、被阻止的结果与开发者接受schemas.ts 的migrationBlockerSchema以accepted: boolean强制这一表达。实践要点把本参考文档嵌入完整迁移闭环将assessment-and-contract.md放入工作流可总结为以下可执行闭环Stage 2按十大主题取证输出风险与覆盖报告为每个生命周期敏感发现归档唯一处置Covered / Characterize / Unsupported / Accepted uncovered riskStage 3在未变更的 RxJS 7 上补齐表征测试并跑绿基线记录精确命令与结果起点门starting gate失败必须显式处理而非静默降级Stage 4按 schema 接受的生命周期值划分迁移单元填写 7 项记录暂停一切“两种行为都可能”的推断将有意分歧以旧声明/新声明/用户影响/证据/审批的形式写入 manifestStage 5–6依据能力注册表与 fixture 证据选择能力参考 engine-and-batches.md先 dry-run 后写盘并验证幂等性Stage 7–8按从窄到宽的验证阶梯复跑门禁用失败分类表区分迁移缺陷、产品缺口、有意分歧、基线/环境问题与未知最后以 migration-report.md 模板向开发者交付声明“测量到的项目结果及其局限”而不是“自动迁移成功”。结语assessment-and-contract.md把 RxJS 7 → RxJS Next 迁移从“codemod 运行”升格为“由证据支撑的意图型契约工程”。它的价值不在于表格本身而在于三条不可动摇的纪律证据先于意图、每个敏感点都有唯一归档、任何歧义都必须暂停并交由开发者批准。配合rxjs/migrate的 schema、能力注册表与就绪评估schemas.ts、capabilities.ts、cli.ts这套契约机制让迁移的可信度不再依赖运气而是依赖一份版本化、可校验、可审计的决策与证据记录。【免费下载链接】rxjsA reactive programming library for JavaScript项目地址: https://gitcode.com/gh_mirrors/rx/rxjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考