SuperAPI AI 工具集

migrate-to-golang

编程与开发

查看项目

更新于 11-06 14:01

技能介绍

用途

该技能负责将非 Go 代码库(C、C++、Java、Python、Node.js、Rust)翻译为符合 Go 语言习惯的代码,直接以最新稳定版 Go 为目标,并用 A/B 对比证明迁移后行为与原始程序一致。迁移的核心原则是保留程序行为,而非复制原代码结构。

主要能力

  • 从 GitHub URL 或本地路径获取源代码,自动克隆并重建基线。
  • 解析最新稳定版 Go 版本(通过 go.dev/dl 的 JSON 接口),不依赖记忆。
  • 生成六部分迁移蓝图(BLUEPRINT.md),记录每个迁移机会和潜在遗留缺陷。
  • 按模块自底向上移植,每个模块通过测试后再进入下一个。
  • 使用 pprof 进行 CPU 和内存分配分析,仅根据剖析结果进行性能调优。
  • 执行验证熔炉:运行构建、vet、lint、race 测试、覆盖率检查等门禁命令,最多修复 5 轮。
  • 运行 A/B 等价性测试:在相同 N 个确定性用例上对比遗留程序与 Go 程序的行为,最多修复 5 轮。
  • 可选择使用 Go PGO(Profile-Guided Optimization):合并 default.pgo 并重新验证等价性。
  • 发布前卫生检查:执行 go fix、go mod tidy、govulncheck。
  • 生成遥测记录(migration_telemetry.json)、蓝图(BLUEPRINT.md)和迁移信息图(migration_infographic.html)。

使用方式

技能需要提供输入:GitHub URL 或代码库本地路径(缺失时询问);选择 Go 移植是放在新的 {repo_name}-go 模块中(默认)还是替换源树;确认 Go 模块路径(从 git remote 推导 github.com/{owner}/{repo},无 remote 时询问或使用 example.com/{repo_name}-go)。

执行步骤分为阶段:

  • 阶段 0:设置环境变量、克隆仓库、解析 Go 版本、初始化遥测、普查遗留代码,声明构建与运行命令并等待用户确认(外部克隆代码),重建基线并捕获黄金输出。
  • 阶段 1:编写蓝图,记录迁移机会和潜在缺陷,写入 BLUEPRINT.md。
  • 阶段 2(脚手架与移植):运行 go mod init 和 go mod edit -go={版本},按模块自底向上移植,每个模块通过测试后再继续,记录第一次 go test 为迭代 1。
  • 阶段 3(根据剖析调优):对遗留构建上运行 1 到 10 秒的工作负载收集 pprof CPU 和分配剖析,仅修复剖析显示的问题,记录调优结果或说明无需调优。
  • 阶段 4(验证熔炉):运行门禁命令,最多修复 5 轮,记录每次迭代。
  • 阶段 5(A/B 等价性):在相同 N 个确定性用例上运行遗留和 Go 程序,使用 ab_parity.sh 对比,最多修复 5 轮。
  • 阶段 6(Go PGO):使用合并的 default.pgo 构建,重新运行等价性测试,仅在保留 profile 时记录 PGO;若遗留基线运行少于 1 秒或工作负载为 I/O 密集型,可跳过 PGO 并说明原因。
  • 阶段 7(发布卫生与报告):运行 go fix、go mod tidy、govulncheck,扫描 Go 源码,记录亮点和故事,渲染信息图。
  • 总结:报告使用的 Go 版本、测量前后数据、信息图路径以及所有未解决的差距。

技能附带参考文档(按需加载最小集合)和脚本(telemetry.py 记录遥测,ab_parity.sh 捕获黄金输出并运行 A/B 对比),迁移过程中不得编辑这些脚本。

适用场景

  • 将遗留或外语代码库迁移到 Go,并需要证明行为一致性。
  • 需要以最新稳定版 Go 为目标,并遵循 Go 语言习惯(而非逐行转译)。
  • 需要可测量的迁移过程(遥测、性能剖析、A/B 对比)和详细报告。
  • 希望利用 Go PGO 优化性能,并有基准测试数据支撑。

限制

  • 迁移目标是行为而非结构,保留类层次、异常作为 panic、utils 包等逐行转译被视为失败。
  • 优先使用标准库,仅在蓝图有充分理由时添加依赖,添加后需运行 govulncheck。
  • 迁移代码不得包含 unsafe、cgo、//go:linkname。
  • 每个修复循环最多 5 轮或 15 分钟,超出则记录剩余差距。
  • 除非用户要求,否则不推送、打标签或发布迁移后的模块。
  • 从外部仓库克隆的代码在用户确认命令前不得编译或运行。
  • 不针对旧版 Go,除非用户批准。
  • 迁移完成需满足:go build、go vet、golangci-lint(或 staticcheck)无问题;go test -race 通过且迁移包语句覆盖率不低于 90%;go fix -diff 为空且 govulncheck 干净或每个发现已记录;A/B 等价性在容差内成立;基准测试已记录或阶段有理由省略;三个输出文件存在。未满足项需在总结中说明。