嬗变

将特定的代码或数据从一种形式转换为另一种——语言翻译、范式转换、格式转换或 API 迁移——同时保持本质行为和语义。

适用场景

• 将函数从一种语言转换为另一种（Python 到 R，JavaScript 到 TypeScript）
• 将模块从一种范式转换为另一种（基于类到函数式，回调到 async/await）
• 将 API 消费者从外部服务的 v1 迁移到 v2
• 在格式之间转换数据（CSV 到 Parquet，REST 到 GraphQL 模式）
• 用等价物替换依赖（moment.js 到 date-fns，jQuery 到原生 JS）
• 当转换范围是单个函数、类或模块（而非完整系统）时

输入

• 必需：源材料（文件路径、函数名或数据样本）
• 必需：目标形式（语言、范式、格式或 API 版本）
• 可选：行为契约（测试、类型签名或预期的输入/输出对）
• 可选：约束（必须保持向后兼容性、性能预算）

步骤

第 1 步：分析源材料

在尝试转换之前，确切理解源代码做了什么。

1. 完整阅读源代码——每个分支、边界情况和错误路径
2. 识别行为契约：
   • 它接受什么输入？（类型、范围、边界情况）
   • 它产生什么输出？（返回值、副作用、错误信号）
   • 它维护什么不变量？（排序、唯一性、引用完整性）
3. 编目依赖：源代码导入、调用或依赖什么？
4. 如果存在测试，阅读它们以理解预期行为
5. 如果没有测试，在嬗变之前编写行为特征测试

预期结果： 完全理解源代码做了什么（而非它如何做）。行为契约是明确的且可测试的。

失败处理： 如果源代码对于单次嬗变来说太复杂，考虑将其分成更小的部分或升级到完整的 athanor 流程。如果行为模糊，请求澄清而不是猜测。

第 2 步：映射源到目标形式

设计转换映射。

1. 对源中的每个元素，识别目标等价物：
   • 语言构造：循环 → map/filter，类 → 闭包等
   • API 调用：旧端点 → 新端点，请求/响应形状变化
   • 数据类型：数据框列 → 模式字段，嵌套 JSON → 平面表
2. 识别没有直接等价物的元素：
   • 目标中缺失的源特性（例如在没有模式匹配的语言中进行模式匹配）
   • 源中不存在的目标惯用法（例如 R 的向量化 vs. Python 循环）
3. 对每个差距，选择适应策略：
   • 仿真：用目标原生构造重现行为
   • 简化：如果源构造是一个变通方案，使用目标的原生解决方案
   • 记录：如果行为略有变化，明确注明差异
4. 编写转换映射：源元素 → 目标元素，涵盖每个部分

预期结果： 一个完整的映射，其中每个源元素都有目标去处。差距被识别且适应策略已选定。

失败处理： 如果太多元素缺乏直接等价物，转换可能不合适（例如将高度面向对象的设计嬗变为没有类的语言）。重新考虑目标形式或升级到 athanor。

第 3 步：执行转换

按照映射编写目标形式。

1. 创建具有适当结构和样板的目标文件
2. 按照第 2 步的映射嬗变每个元素：
   • 保持行为契约——相同输入产生相同输出
   • 使用目标原生惯用法而非字面翻译
   • 维护或改进错误处理
3. 处理依赖：
   • 用目标等价物替换源依赖
   • 如果依赖没有等价物，实现一个最小适配器
4. 仅在转换不明显处添加行内注释

预期结果： 一个遵循转换映射的完整目标实现。代码读起来像是用目标形式原生编写的，而不是机械翻译的。

失败处理： 如果特定元素抵抗转换，将其隔离。先转换其他所有内容，然后集中注意力处理抵抗的元素。如果它真的无法嬗变，记录原因并提供变通方案。

第 4 步：验证行为等价性

确认嬗变后的形式保持了原始的行为。

1. 对目标实现运行行为契约测试
2. 对每个测试用例，验证：
   • 相同输入 → 相同输出（数值转换在可接受容差范围内）
   • 相同错误条件 → 等价的错误信号
   • 副作用（如有）被保留或记录为已变更
3. 明确检查边界情况：
   • Null/NA/undefined 处理
   • 空集合
   • 边界值（最大整数、空字符串、零长度数组）
4. 如果目标形式增加了能力（例如类型安全），也验证这些

预期结果： 所有行为契约测试通过。边界情况被等价处理。任何行为差异都被记录且是有意为之的。

失败处理： 如果测试失败，对比源和目标行为以找到分歧。修复目标以匹配源契约。如果分歧是有意的（例如修复原始中的错误），明确记录。

验证清单

• 源材料已完全分析，行为契约明确
• 转换映射覆盖每个源元素
• 差距已识别并记录了适应策略
• 目标实现使用原生惯用法（非字面翻译）
• 所有行为契约测试对目标通过
• 边界情况已验证（null、空、边界值）
• 依赖已用目标等价物解决
• 任何行为差异都已记录且是有意为之的

常见问题

• 字面翻译：写出 Python 风格的 R 或 Java 风格的 JavaScript，而不是使用目标惯用法。结果应该看起来是原生的
• 跳过行为测试：没有测试的嬗变意味着无法验证等价性。先编写特征测试
• 忽略边界情况：快乐路径容易嬗变；边界情况是错误潜藏之处
• 过度工程化适配器：如果一个依赖需要 200 行适配器，嬗变范围太大了
• 逐字嬗变注释：注释应该解释目标代码，而不是回显源代码。重写它们

相关技能

• athanor — 对于单次嬗变过大的系统的完整四阶段转换
• chrysopoeia — 优化嬗变后的代码以获取最大价值
• review-software-architecture — 用于较大转换的嬗变后架构审查
• serialize-data-formats — 专门的数据格式转换流程