pjt222 嬗变
将特定的代码或数据从一种形式转换为另一种——语言翻译、范式转换、格式转换或 API 迁移——同时保持本质行为和语义。
适用场景
- 将函数从一种语言转换为另一种（Python 到 R，JavaScript 到 TypeScript）
- 将模块从一种范式转换为另一种（基于类到函数式，回调到 async/await）
- 将 API 消费者从外部服务的 v1 迁移到 v2
- 在格式之间转换数据（CSV 到 Parquet，REST 到 GraphQL 模式）
- 用等价物替换依赖（moment.js 到 date-fns，jQuery 到原生 JS）
- 当转换范围是单个函数、类或模块（而非完整系统）时
输入
- 必需：源材料（文件路径、函数名或数据样本）
- 必需：目标形式（语言、范式、格式或 API 版本）
- 可选：行为契约（测试、类型签名或预期的输入/输出对）
- 可选：约束（必须保持向后兼容性、性能预算）
步骤
第 1 步：分析源材料
在尝试转换之前，确切理解源代码做了什么。
- 完整阅读源代码——每个分支、边界情况和错误路径
- 识别行为契约：
- 它接受什么输入？（类型、范围、边界情况）
- 它产生什么输出？（返回值、副作用、错误信号）
- 它维护什么不变量？（排序、唯一性、引用完整性）
- 编目依赖：源代码导入、调用或依赖什么？
- 如果存在测试，阅读它们以理解预期行为
- 如果没有测试，在嬗变之前编写行为特征测试
预期结果： 完全理解源代码做了什么（而非它如何做）。行为契约是明确的且可测试的。
失败处理： 如果源代码对于单次嬗变来说太复杂，考虑将其分成更小的部分或升级到完整的 athanor 流程。如果行为模糊，请求澄清而不是猜测。
第 2 步：映射源到目标形式
设计转换映射。
- 对源中的每个元素，识别目标等价物：
- 语言构造：循环 → map/filter，类 → 闭包等
- API 调用：旧端点 → 新端点，请求/响应形状变化
- 数据类型：数据框列 → 模式字段，嵌套 JSON → 平面表
- 识别没有直接等价物的元素：
- 目标中缺失的源特性（例如在没有模式匹配的语言中进行模式匹配）
- 源中不存在的目标惯用法（例如 R 的向量化 vs. Python 循环）
- 对每个差距，选择适应策略：
- 仿真：用目标原生构造重现行为
- 简化：如果源构造是一个变通方案，使用目标的原生解决方案
- 记录：如果行为略有变化，明确注明差异
- 编写转换映射：源元素 → 目标元素，涵盖每个部分
预期结果： 一个完整的映射，其中每个源元素都有目标去处。差距被识别且适应策略已选定。
失败处理： 如果太多元素缺乏直接等价物，转换可能不合适（例如将高度面向对象的设计嬗变为没有类的语言）。重新考虑目标形式或升级到 athanor。
第 3 步：执行转换
按照映射编写目标形式。
- 创建具有适当结构和样板的目标文件
- 按照第 2 步的映射嬗变每个元素：
- 保持行为契约——相同输入产生相同输出
- 使用目标原生惯用法而非字面翻译
- 维护或改进错误处理
- 处理依赖：
- 用目标等价物替换源依赖
- 如果依赖没有等价物，实现一个最小适配器
- 仅在转换不明显处添加行内注释
预期结果： 一个遵循转换映射的完整目标实现。代码读起来像是用目标形式原生编写的，而不是机械翻译的。
失败处理： 如果特定元素抵抗转换，将其隔离。先转换其他所有内容，然后集中注意力处理抵抗的元素。如果它真的无法嬗变，记录原因并提供变通方案。
第 4 步：验证行为等价性
确认嬗变后的形式保持了原始的行为。
- 对目标实现运行行为契约测试
- 对每个测试用例，验证：
- 相同输入 → 相同输出（数值转换在可接受容差范围内）
- 相同错误条件 → 等价的错误信号
- 副作用（如有）被保留或记录为已变更
- 明确检查边界情况：
- Null/NA/undefined 处理
- 空集合
- 边界值（最大整数、空字符串、零长度数组）
- 如果目标形式增加了能力（例如类型安全），也验证这些
预期结果： 所有行为契约测试通过。边界情况被等价处理。任何行为差异都被记录且是有意为之的。
失败处理： 如果测试失败，对比源和目标行为以找到分歧。修复目标以匹配源契约。如果分歧是有意的（例如修复原始中的错误），明确记录。
验证清单
- 源材料已完全分析，行为契约明确
- 转换映射覆盖每个源元素
- 差距已识别并记录了适应策略
- 目标实现使用原生惯用法（非字面翻译）
- 所有行为契约测试对目标通过
- 边界情况已验证（null、空、边界值）
- 依赖已用目标等价物解决
- 任何行为差异都已记录且是有意为之的
常见问题
- 字面翻译：写出 Python 风格的 R 或 Java 风格的 JavaScript，而不是使用目标惯用法。结果应该看起来是原生的
- 跳过行为测试：没有测试的嬗变意味着无法验证等价性。先编写特征测试
- 忽略边界情况：快乐路径容易嬗变；边界情况是错误潜藏之处
- 过度工程化适配器：如果一个依赖需要 200 行适配器，嬗变范围太大了
- 逐字嬗变注释：注释应该解释目标代码，而不是回显源代码。重写它们
相关技能
athanor— 对于单次嬗变过大的系统的完整四阶段转换chrysopoeia— 优化嬗变后的代码以获取最大价值review-software-architecture— 用于较大转换的嬗变后架构审查serialize-data-formats— 专门的数据格式转换流程