SuperAPI AI 工具集

go-code-review

编程与开发

查看项目

更新于 10-15 14:38

技能介绍

用途

go-code-review 是一个用于审查 Go 代码的 AI 技能,主要检查代码是否符合惯用模式、错误处理是否得当、并发是否安全,以及是否存在常见错误。它适用于审查 .go 文件、检查错误处理等场景。

主要能力

该技能提供了一套结构化的审查工作流,要求按顺序执行以下步骤:

  1. 读取 go.mod 基线:打开 go.mod 并读取 go 指令,记录确切的 go X.YY 值。只有与该基线匹配时才应用版本相关的建议(例如循环变量捕获适用于 1.22 之前,slog/结构化日志适用于 1.21 起,errors.Join 适用于 1.20 起)。
  2. 阅读周边代码:对于每个变更的 .go 文件,阅读包含编辑的完整函数或逻辑单元,而不仅仅是 diff 片段。每个变更文件至少阅读一个包含该变更的完整外层函数(或包级 init/var 块)。
  3. 确定清单范围:决定哪些审查清单块适用(错误处理、并发、接口/类型、资源、命名),加载这些块的参考文档,跳过与 diff 无关的块。审查或工作笔记中需列出应用的清单块,或将不相关的块标记为 N/A 并附上与 diff 相关的一行原因。
  4. 报告前验证:加载并遵循 review-verification-protocol,对每个将要报告的问题满足其报告前验证清单(实际阅读代码、检查周边上下文、区分“错误”与“不同风格”等)。

审查清单

错误处理:所有错误都被检查(没有无理由注释的 _ = err);错误用上下文包装(fmt.Errorf("...: %w", err));使用 errors.Is/errors.As 而非字符串匹配;使用 errors.Join 聚合多个错误(Go 1.20+);错误时返回零值。

并发:无 goroutine 泄漏(存在 context 取消或关闭信号);通道仅由发送方关闭且只关闭一次;共享状态由 mutex 或 sync 类型保护;使用 WaitGroup 等待 goroutine 完成;context 沿调用链传播;处理循环变量捕获(仅限 Go 1.22 之前的代码库)。

接口与类型:接口由消费者而非生产者定义;接口名遵循 -er 约定;接口最小化(1-3 个方法);构造函数返回具体类型;优先使用 any 而非 interface{}(Go 1.18+);在适当处使用泛型而非 any 或代码生成。

资源与生命周期:资源创建后立即用 defer 关闭;HTTP 响应体始终关闭;循环中无未包装的 defer;避免 init() 函数,改用显式初始化。

命名与风格:导出的名称有文档注释;无重复名称(user.UserService → user.Service);超过 5 行的函数中无裸返回;context 作为第一个参数传递;使用 slog 而非 log 进行结构化日志(Go 1.21+)。

严重程度分级

  • Critical(阻止合并):I/O、网络或数据库操作上未检查的错误;goroutine 泄漏(无关闭路径);共享状态上的竞态条件(并发 map 访问无同步);无界资源累积(循环中 defer、未关闭的连接)。
  • Major(应修复):错误返回时无上下文(裸 return err);生成的 goroutine 缺少 WaitGroup;对可恢复错误使用 panic;context 未传播到下游调用。
  • Minor(可考虑修复):Go 1.18+ 代码库中使用 interface{} 而非 any;导出项缺少文档注释;重复名称;已知大小时未预分配切片。
  • Informational(仅提示):在已有代码生成处建议添加泛型;接口设计的重构想法;无实测影响的性能优化。

使用方式

该技能以审查工作流为核心,要求按顺序执行四个步骤(读取 go.mod 基线、阅读周边代码、确定清单范围、报告前验证),并遵循硬性门禁。输出格式为:[FILE:LINE] ISSUE_TITLE,随后是严重程度(Critical | Major | Minor | Informational)以及问题描述和重要性说明。

适用场景

适用于审查 Go 代码,特别是检查错误处理、并发安全、接口设计、资源管理和命名风格。当审查错误返回模式时加载 error-handling.md;审查 goroutine、通道或 sync 类型时加载 concurrency.md;审查类型定义、接口或泛型时加载 interfaces.md;一般审查(资源、命名、init、性能)时加载 common-mistakes.md。

限制

该技能明确列出了不应标记的有效模式,以避免浪费开发者时间,例如:带原因注释的 _ = err、真正泛型代码中的空接口/any、短函数中的裸返回、通过 context 取消而非通道关闭的消费者、保护结构体字段的 mutex、带原因的 //nolint 指令、有意为之的循环中 defer、函数式选项模式、热路径中的 sync.Pool、main/测试中的 context.Background()、带 default 的 select、小作用域中的短变量名。

此外,某些规则仅在特定条件下才标记:缺少错误检查仅在错误返回可操作时标记;goroutine 泄漏仅在无 context 取消路径时标记;缺少 defer 仅在资源未在下次获取或返回前显式关闭时标记;接口污染仅在接口有超过 1 个方法且只有一个消费者时标记;循环变量捕获仅在 go.mod 指定 Go < 1.22 时标记;缺少 slog 仅在 go.mod 指定 Go >= 1.21 且代码使用 log 包进行结构化输出时标记。

关于该技能的安装方式、收费、价格、平台等信息,资料中暂未提供。