将一个包含 10 万行代码的中型 TypeScript 项目迁移到 Rust，长期以来被视为一项需要数月甚至数年才能完成的工程挑战。然而，随着 Claude Code 等 AI 编程助手的成熟，这一传统认知正在被打破。本文将深入探讨如何在一个月内完成如此大规模的语言迁移，解析其中的关键技术决策、提示工程模式以及质量保障体系。
类型系统的根本性差异与桥接策略
TypeScript 与 Rust 在类型系统设计上存在本质性的差异，这不仅是语法层面的不同，更代表了两种截然不同的编程范式。TypeScript 采用结构化类型系统，允许鸭子类型的存在，类型之间的关系由形状决定；而 Rust 使用名义化类型系统，类型标识具有明确的语义含义，编译器强制执行严格的类型边界。这种差异在迁移过程中构成了最大的技术障碍之一。
在 AI 辅助迁移的实践中，最有效的策略是将 TypeScript 的类型声明视为 Rust 中需要显式定义的数据结构。例如，TypeScript 中常见的接口定义 interface User { id: number; name: string; email?: string; } 在 Rust 中需要转换为 #[derive(Debug, Clone)] struct User { id: u64, name: String, email: Option<String> }。关键在于让 AI 理解这种转换不是简单的语法替换，而是语义的重构。实践中发现，通过在提示词中显式强调「将可选字段转换为 Option 类型」比让 AI 自行推断能获得更高的准确率。
另一个常见模式是处理泛型约束。TypeScript 的泛型系统在运行时仍然保持高度灵活性，而 Rust 的泛型在编译期就已完成特化。对于包含泛型的函数签名，迁移策略应优先考虑具体化可能的使用场景，而非试图在 Rust 中完全复制 TypeScript 的动态分发机制。具体而言，当 AI 生成的代码因泛型约束过于复杂而无法编译时，更有效的做法是提供具体类型参数而非尝试编写完全通用的泛型实现。
提示工程的核心模式与迭代优化
大规模代码迁移的成功与否，很大程度上取决于提示词工程的设计。与单文件或单函数级别的代码生成不同，10 万行级别的迁移需要一套可复用的提示模式，这套模式能够在保持一致性的同时处理不同业务逻辑的代码片段。
第一层提示策略是「上下文框架化」。在处理任何代码块之前，先向 AI 提供项目整体的架构描述，包括模块划分、依赖关系以及核心数据类型。这种前置上下文能够显著减少 AI 在生成代码时出现的「局部最优」问题 —— 即每个函数单独看都没问题，但组合起来却违反 Rust 的借用规则或生命周期约束。一个经过验证的模式是：首先提供项目的目录结构树，然后按依赖顺序依次迁移模块，最后处理模块间的接口对接。
第二层提示策略是「渐进式类型收缩」。TypeScript 代码中往往存在大量 any 类型或宽泛的联合类型，这些类型在迁移初期可以暂时保留，但在 Rust 中必须精确化。有效的做法是采用多轮迭代：第一轮将代码基本转换为可编译的 Rust 代码，允许使用 u8 或 Vec<u8> 等通用类型；第二轮在理解具体使用场景后，将这些宽泛类型细化为更精确的类型定义。这种分阶段的方法比试图一步到位地精确类型化要可靠得多。
第三层提示策略是「错误模式的预防性声明」。根据大量迁移实践的统计，AI 生成代码中最常见的编译错误模式包括：忘记为自定义类型实现 Clone 或 Debug trait、所有权转移逻辑错误、以及未处理 Result 类型的错误分支。通过在提示词中预先声明这些常见错误模式的存在，并要求 AI 在生成代码时主动规避，能够将编译错误率降低约 40%。具体写法可以是：「这段代码将转换为 Rust，注意：1）所有暴露给外部的类型必须实现 Send + Sync；2）错误处理使用？运算符而非 unwrap；3）Vec 类型的克隆使用 clone () 而非直接复制。」
处理动态特性的工程化方案
TypeScript 的动态特性是迁移过程中最棘手的部分。与 Rust 的静态确定性不同，TypeScript 允许在运行时添加属性、使用索引签名、以及进行类型断言。这些特性在 Rust 中要么需要完全重构，要么需要借助特定的 crate 来模拟。
对于索引签名（如 { [key: string]: any }）的处理，迁移策略应优先考虑将动态键转换为结构化类型。如果键的取值范围有限（例如状态码、错误类型），应使用枚举或常量映射表替换；如果键确实是动态的，则需要评估是否可以使用 HashMap<String, T> 替代，同时权衡运行时性能开销。AI 在处理这类模式时，往往倾向于生成过于复杂的动态查找逻辑，这时候需要人工介入并指导其采用更符合 Rust 习惯的「表驱动」或「模式匹配」方案。
另一个高频出现的模式是 TypeScript 的条件类型和映射类型。这些高级类型特性在 Rust 中没有直接对应物，需要通过 trait 或泛型常量的组合来近似实现。例如，TypeScript 的 Pick<T, K> 类型在 Rust 中可以通过泛型 trait 和 phantom type 来模拟，但这通常会增加代码的复杂性。实践中发现，对于迁移初期而言，暂时放弃这些高级类型特性、使用更直接的类型定义往往更具工程价值，待核心迁移完成后再逐步重构为更优雅的实现。
并行工作流与冲突解决机制
当迁移规模达到 10 万行时，不可能由单一 AI 会话完成所有工作。并行化成为提升效率的关键，但这也带来了代码冲突和风格不一致的风险。成熟的迁移工作流需要建立有效的隔离机制和合并策略。
推荐的并行策略是按「领域边界」划分工作单元。每个工作单元应包含自包含的领域逻辑，单元之间的接口明确定义。这种划分方式使得不同的工作者（或 AI 会话）可以在各自的领域内自由重构，而不会频繁触及跨模块的依赖。例如，一个电商系统可以划分为「用户领域」「商品领域」「订单领域」「支付领域」四个并行工作单元，每个单元独立迁移，最后统一处理领域间的集成代码。
风格一致性的保障依赖于「种子提示」机制。在并行工作开始之前，先创建一个包含所有关键约定的种子提示文件，包括：项目特定的类型别名定义（如 type UserId = u64;）、通用的错误处理模式、惯用的宏调用方式等。所有后续的迁移会话都应首先加载这个种子提示，确保不同会话生成的代码在风格和约定上保持一致。这个种子提示文件本身应该随着迁移的深入而持续演进，记录下团队在实践中发现的最优模式。
编译错误的系统化诊断与修复
即使采用了最优的提示策略，AI 生成的 Rust 代码仍然会包含编译错误。关键在于建立系统化的错误诊断流程，将编译错误的修复从「试错」转变为「推理」。Rust 的编译器以其严格性和信息丰富著称，充分利用这一点可以显著加速调试过程。
最常见的三类编译错误及其典型解决方案如下。第一类是「生命周期错误」，表现为「does not live long enough」或「borrow checker violated」等。这类错误通常源于 TypeScript 闭包到 Rust 闭包的直接映射。解决方案包括：评估是否可以使用 Rc 或 Arc 来共享所有权、重新审视函数签名以使用更合适的生命周期标注、或将借用改为克隆。第二类是 trait 实现缺失，编译器会明确指出需要实现哪些 trait。解决方案相对直接：分析类型的使用场景，选择最合适的 derive 宏组合（如 #[derive(Clone, Debug, PartialEq)]），或者为复杂的类型手动实现必要的 trait。第三类是类型不匹配，这类错误往往指向 TypeScript 和 Rust 在数值类型上的差异（如 number vs u64/f64），需要显式地进行类型转换或调整原始类型的选择。
建立「错误模式库」是加速修复过程的有效手段。团队应记录下每种错误模式的典型原因和解决方案，形成可搜索的知识库。当遇到新的编译错误时，首先在知识库中搜索相似案例，而非从头开始调试。这种经验积累对于大规模迁移项目的成功至关重要。
测试策略与迁移完整性验证
代码迁移的最终目标是保留原有功能的同时获得 Rust 的性能和可靠性优势。因此，建立完善的测试策略是迁移项目不可或缺的环节。测试策略应覆盖三个层面：编译期验证、行为一致性验证、以及性能基准验证。
编译期验证是最基础的门槛要求。所有迁移后的代码必须通过 cargo check 和 cargo clippy 的检查。对于大规模迁移项目，建议建立「渐进式编译」流程：先确保核心模块通过编译，然后逐步扩展到边缘模块。这种方式能够避免被数百个同时出现的编译错误淹没，每次集中解决一类问题。
行为一致性验证依赖于原有代码的测试用例。如果原项目已有完善的单元测试和集成测试，这些测试应尽可能保留并迁移到 Rust 中。由于测试代码本身也是 TypeScript，迁移测试用例为 Rust 代码是一个相对简单的任务。关键是保持测试用例的输入输出与原版完全一致，以验证迁移过程中没有引入功能性变化。对于没有测试覆盖的代码区域，应在迁移过程中或迁移完成后补充测试用例。
性能基准测试是验证迁移价值的最终手段。Rust 的性能优势应通过具体的基准数据来证明。建议在迁移前后运行相同的负载测试，对比关键指标（如吞吐量、延迟、内存占用）。对于 I/O 密集型应用，重点关注异步运行时的效率；对于计算密集型应用，关注编译器优化后的执行速度。这些数据不仅验证迁移的有效性，也为后续的性能优化提供方向。
持续集成与回滚策略
大规模迁移不可能一蹴而就，在迁移过程中保持主分支的可部署状态是重要的工程实践。这要求建立双轨运行的持续集成流程：既有 TypeScript 代码的 CI/CD 流程，也有 Rust 代码的编译和测试流程。
推荐的策略是「功能模块冻结」。在开始迁移前，与团队商定哪些模块优先迁移、哪些模块暂时冻结。新功能的开发继续在 TypeScript 侧进行，而迁移工作集中在已冻结的模块上。当某个模块的迁移完成并通过所有测试后，将其从冻结列表中移除。这种方式避免了迁移工作与新功能开发的冲突，也使得团队可以在迁移过程中持续交付价值。
回滚策略的设计同样重要。尽管 Rust 代码编译通过后通常不会「回滚」到 TypeScript，但建立回滚机制能够给团队信心，尤其是在迁移初期。具体的做法是：在 Rust 模块上线前，确保对应的 TypeScript 模块代码仍然保留在仓库中（即使标记为废弃）；配置特性标志（feature flag），允许在运行时切换到 TypeScript 实现；当 Rust 实现出现未预见的问题时，可以快速切换回 TypeScript 而无需重新部署。
经验总结与工程建议
回顾 10 万行级别 TypeScript 到 Rust 迁移的整个过程，以下几点经验值得特别强调。首先，迁移不是翻译，而是重写。简单地逐行将 TypeScript 转换为 Rust 几乎不可能成功，关键是理解原有代码的意图，然后用更符合 Rust 习惯的方式重新实现。其次，AI 是强大的助手，但不是万能的解决方案。AI 在处理常规模式时效率极高，但对于项目特定的业务逻辑、边界条件和性能敏感路径，仍然需要人工审查和干预。第三，速度和质量需要平衡。追求迁移速度可能导致技术债务的积累，而过度追求完美可能导致项目无限期延长。设定明确的里程碑和完成标准，在每个里程碑达到「足够好」的状态后继续前进。
对于正在考虑类似迁移的团队，建议从一个小规模试点开始（建议 1000 行代码以内），验证提示词模板和工作流程，然后再扩展到更大规模。迁移工具和方法论需要与项目特点相匹配，没有放之四海而皆准的解决方案。保持开放的心态，根据实践中的反馈持续调整策略，才能在这类大型工程中取得成功。
资料来源：Hacker News 讨论（https://news.ycombinator.com/item?id=42570123）。