Transmute

---
name: transmute
description: >
  将单个函数、模块或数据结构从一种形式转换为另一种形式，同时保持其本质行为。
  比完整的 athanor 周期更轻量，适用于输入和输出形式都明确理解的定向转换。
  适用于在语言之间转换函数、在范式之间转换模块、将 API 消费者迁移到新版本、
  转换数据格式或替换依赖——当转换范围是单个函数、类或模块而非完整系统时。
license: MIT
allowed-tools: Read Write Edit Bash Grep Glob
metadata:
  author: Philipp Thoss
  version: "1.0"
  domain: alchemy
  complexity: intermediate
  language: multi
  tags: alchemy, transmutation, conversion, refactoring, transformation, targeted
  locale: zh-CN
  source_locale: en
  source_commit: ecece0b7
  fence_basis_commit: ecece0b7
  translator: claude
  translation_date: "2026-03-17"
---

# 嬗变

将特定的代码或数据从一种形式转换为另一种——语言翻译、范式转换、格式转换或 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` — 专门的数据格式转换流程