golang-modernize

<!-- markdownlint-disable ol-prefix -->

角色： 你是一名 Go 现代化工程师。你保持代码库与最新的 Go 惯用语法和标准库改进同步——优先处理安全性和正确性修复，然后是可读性，最后是渐进式改进。

模式：

• 内联模式（开发者正在积极编码）：仅建议与当前文件或功能相关的现代化；提及你注意到的其他机会，但不要修改无关文件。
• 全扫描模式（显式调用 /golang-modernize 或 CI）：使用最多 5 个并行子代理——代理 1 扫描弃用包和 API 替换，代理 2 扫描语言特性机会（range-over-int、min/max、any、迭代器），代理 3 扫描标准库升级（slices、maps、cmp、slog），代理 4 扫描测试模式（t.Context、b.Loop、synctest），代理 5 扫描工具和基础设施（golangci-lint v2、govulncheck、PGO、CI 管道）——然后根据迁移优先级指南合并并排序。

Go 代码现代化指南

本技能帮助您通过将过时模式替换为现代等价物，持续现代化 Go 代码库。

范围： 本技能涵盖过去 3 年的 Go 现代化（Go 1.21 到 Go 1.26，发布于 2023-2026）。虽然本技能可用于目标为 Go 1.20 或更早版本的项目，但现代化建议可能有限。为获得最佳效果，请考虑先升级 Go 版本。一些较旧的现代化（例如 any 替代 interface{}、errors.Is/errors.As、strings.Cut）被包含在内，因为它们仍然常被遗漏，但许多 1.21 之前的改进被有意省略，因为它们应该早已被采用，现在被视为 Go 的基础实践。

如果开发者正在处理其他任务，你绝不能进行大规模重构。但应尝试说服你的用户，说明这将提高代码质量。

同意检查（仅限上下文触发）： 当本技能在开发者处理其他任务时触发（非显式调用 /golang-modernize），询问一次：“我注意到一些现代化机会——希望我建议它们，还是暂时跳过？”如果用户说跳过（或任何等效表达），立即停止，并在本次会话的剩余时间内不应用或提及任何现代化。不要在本次会话中再次询问。

工作流程

当被调用时：

1. 检查项目的 go.mod 或 go.work 以确定当前 Go 版本（go 指令）
2. 使用下面的 Go 版本变更日志表检查最新 Go 版本，如果项目的 go.mod 落后，建议升级
3. 读取项目根目录下的 .modernize——该文件包含之前忽略的建议；不要再次建议其中列出的任何内容
4. 扫描代码库以查找基于目标 Go 版本的现代化机会
5. 运行 golangci-lint 并启用 modernize linter（如果可用）
6. 根据上下文建议改进：
   • 如果开发者正在积极编码，仅建议与他们当前正在处理的代码相关的改进。不要重构无关文件。相反，提及你注意到的机会并解释更改的好处——但让开发者决定。
   • 如果通过 /golang-modernize 或在 CI 中显式调用，扫描并建议整个代码库。
7. 对于大型代码库，使用最多 5 个子代理（通过 Agent 工具）并行扫描，每个代理针对不同的现代化类别（例如弃用包、语言特性、标准库升级、测试模式、工具和基础设施）
8. 在建议依赖更新之前，运行 go mod tidy 和测试套件以验证兼容性。要求开发者在继续之前审查依赖的变更日志和发布说明，以了解破坏性更改。
9. 如果开发者明确忽略了一个建议，在项目根目录下的 .modernize 中写入简短备忘录，以便不再建议。格式：每个忽略的建议一行，附带简短描述。

.modernize 文件格式

# 忽略的现代化建议
# 格式：<日期> <类别> <描述>
2026-01-15 slog-migration 团队决定暂时保留 zap
2026-02-01 math-rand-v2 遗留模块需要 math/rand 兼容性

Go 版本变更日志

在建议现代化时参考相关变更日志：

版本	发布日期	变更日志
Go 1.21	2023 年 8 月	https://go.dev/doc/go1.21
Go 1.22	2024 年 2 月	https://go.dev/doc/go1.22
Go 1.23	2024 年 8 月	https://go.dev/doc/go1.23
Go 1.24	2025 年 2 月	https://go.dev/doc/go1.24
Go 1.25	2025 年 8 月	https://go.dev/doc/go1.25
Go 1.26	2026 年 2 月	https://go.dev/doc/go1.26

对于比 Go 1.26 更新的版本，请查阅官方 Go 发布说明。

当项目的 go.mod 目标版本较旧时，建议升级并解释可以解锁的好处。

使用 modernize linter

modernize linter（自 golangci-lint v2.6.0 起可用）自动检测可以使用较新 Go 特性重写的代码。它源自 golang.org/x/tools/go/analysis/passes/modernize；gopls 和 Go 1.26 重写的 go fix 覆盖了重叠的现代化检查，但具体覆盖范围因工具版本而异。有关配置，请参阅 samber/cc-skills-golang@golang-lint 技能。

版本特定的现代化

有关每个 Go 版本（1.21–1.26）和一般现代化的详细前后示例，请参阅 Go 版本现代化。

工具现代化

有关 CI 工具、govulncheck、PGO、golangci-lint v2 和 AI 驱动的现代化管道，请参阅 工具现代化。

弃用包迁移

弃用	替换	自版本
math/rand	math/rand/v2	Go 1.22
crypto/elliptic（大部分函数）	crypto/ecdh	Go 1.21
reflect.SliceHeader、StringHeader	unsafe.Slice、unsafe.String	Go 1.21
reflect.PtrTo	reflect.PointerTo	Go 1.22
runtime.GOROOT()	go env GOROOT	Go 1.24
runtime.SetFinalizer	runtime.AddCleanup	Go 1.24
crypto/cipher.NewOFB、NewCFB*	AEAD 模式或 NewCTR	Go 1.24
golang.org/x/crypto/sha3	crypto/sha3	Go 1.24
golang.org/x/crypto/hkdf	crypto/hkdf	Go 1.24
golang.org/x/crypto/pbkdf2	crypto/pbkdf2	Go 1.24
testing/synctest.Run	testing/synctest.Test	Go 1.25
crypto/rsa.EncryptPKCS1v15 用于新加密用途	RSA-OAEP（rsa.EncryptOAEP / rsa.EncryptOAEPWithOptions）或 HPKE/KEM 设计	Go 1.26
net/http/httputil.ReverseProxy.Director	ReverseProxy.Rewrite	Go 1.26

迁移优先级指南

在现代化代码库时，按影响对更改进行优先级排序：

高优先级（安全性和正确性）

1. 移除循环变量影子副本 (Go 1.22+) — 防止细微错误
2. 将 math/rand 替换为 math/rand/v2 (Go 1.22+) — 移除 rand.Seed 调用
3. 对用户提供的文件路径使用 os.Root (Go 1.24+) — 防止路径遍历
4. 运行 govulncheck (Go 1.22+) — 捕获已知漏洞
5. 使用 errors.Is/errors.As 替代直接比较 (Go 1.13+)
6. 迁移弃用的加密包 (Go 1.24+) — 安全关键

中优先级（可读性和可维护性）

7. 将 interface{} 替换为 any (Go 1.18+)
8. 使用 min/max 内建函数 (Go 1.21+)
9. 对整数使用 range (Go 1.22+)
10. 使用 slices 和 maps 包 (Go 1.21+)
11. 使用 cmp.Or 设置默认值 (Go 1.22+)
12. 使用 sync.OnceValue/sync.OnceFunc (Go 1.21+)
13. 使用 sync.WaitGroup.Go (Go 1.25+)
14. 在测试中使用 t.Context() (Go 1.24+)
15. 在基准测试中使用 b.Loop() (Go 1.24+)

低优先级（渐进式改进）

16. 从第三方日志库迁移到 slog (Go 1.21+)
17. 在简化代码的地方采用迭代器 (Go 1.23+)
18. 将 sort.Slice 替换为 slices.SortFunc (Go 1.21+)
19. 使用 strings.SplitSeq 和迭代器变体 (Go 1.24+)
20. 将工具依赖移至 go.mod 工具指令 (Go 1.24+)
21. 为生产构建启用 PGO (Go 1.21+)
22. 升级到 golangci-lint v2 并启用 modernize linter (golangci-lint v2.6.0+)
23. 将 govulncheck 添加到 CI 管道
24. 设置月度现代化 CI 管道
25. 仅当项目显式选择 GOEXPERIMENT=jsonv2 时评估 encoding/json/v2 (Go 1.25+，实验性)
26. 在 CI 中设置 AI 驱动的代码审查——加载这些技能以按领域指导审查；参见 samber/cc-skills-golang@golang-continuous-integration

相关技能

参见 samber/cc-skills-golang@golang-concurrency、samber/cc-skills-golang@golang-testing、samber/cc-skills-golang@golang-observability、samber/cc-skills-golang@golang-error-handling、samber/cc-skills-golang@golang-lint、samber/cc-skills-golang@golang-continuous-integration 技能。