SuperAPI AI 工具集

go-code-quality

编程与开发

查看项目

更新于 11-04 16:19

技能介绍

用途

该技能用于生产级 Go 代码的审查、重构与生成,属于“检查清单驱动”的 Go 工作方式。它入口文件给出工作流与不可妥协的规则,详细清单放在 references/go-practices.md,在任务较复杂(审查、重构、API 设计、错误/并发设计或需要具体规则时)应加载该参考文件。

主要能力

  • 任务分类:生成代码(先设计 API 与错误契约,再写代码与测试)、审查代码(先暴露正确性与可维护性风险,再看风格)、重构代码(保持行为、改进类型/错误/边界,再简化)、调试代码(解释根因、给出最小修复)。
  • 优先级顺序:正确性、数据完整性、安全;API 契约、强类型、错误语义;context、取消、资源清理、goroutine 生命周期;可读性、包边界、可测试性;性能(仅在证据支持或明显分配/复杂度问题时);格式与风格最后,由 gofmt 与 goimports 处理。
  • 不可妥协规则:用领域类型而非原始类型建模状态、角色、ID、网络、模式、阶段或方法;使用类型化枚举(如 type Status string + 具名常量 + Valid() 方法与解析辅助,或从 1 开始的 iota 枚举使零值表示未设置);校验、I/O、解析、缺数据、坏输入、远程失败或可恢复状态返回错误而非 panic;每个错误只处理一次(带上下文返回、转为领域错误或处理),中间层不要记录后又返回同一错误;仅当底层错误属于契约(调用方会用 errors.Is/errors.As)时用 %w 包装,否则用 %v 或映射为包错误;错误字符串小写、结尾无标点(专有名词或缩写开头除外);context.Context 显式且放在首位,不存于结构体、不传 nil;除非文档化 API 使错误不可能或不相关,否则不用 _ 静默丢弃错误并在代码中说明;any/interface{} 只用于边界(序列化、真正通用的容器、基于反射的 API),不作为逃避建模的手段;goroutine 生命周期有界,每个都有停止条件、取消路径或等待机制(WaitGroup/errgroup),不 fire-and-forget;接口定义在消费方,构造函数返回具体类型;测试报告 got 与 want、包含输入,共享逻辑时用表驱动子测试;在边界(HTTP、CLI、DB、JSON、网络)校验不可信输入并转为领域类型后再向内传递;令牌、密钥、nonce、盐或任何安全敏感标识符使用 crypto/rand,绝不用 math/rand。其余规则(接收者选择、选项结构体、nil 切片语义、信任边界处的 map/slice 复制、解析器模糊测试、完整审查清单、可复用审查评论)见 references/go-practices.md。

使用方式

先分类任务,再按优先级顺序执行,并遵循仓库既有约定(除非不安全或明显损坏,否则不发明与周边代码冲突的项目约定)。反馈要具体:说明规则、为何重要、确切改法,避免只说“让它更地道”。

输出格式:

审查反馈按严重程度分组,尽量用 file:line 定位,否则指出函数或片段,分为“必须修复”“应改进”“可选优化”“已具备的良好模式”四部分。

生成代码要求导入可编译、格式符合 gofmt、包与函数小而内聚、可能失败时返回 (T, error) 或 error,按需为公共行为与边界情况编写测试,并简要说明重要设计选择(导出的错误契约、领域类型、并发、API 边界)。

重构要求除非用户要求改变行为否则保持行为,展示改动代码或补丁,区分保持行为与改变行为的改动,并在导出名称、哨兵错误、结构体字段或公共接口变化时说明迁移影响。

相关技能

  • go-best-practices:Rob Pike 的 Go Proverbs,用于哲学/架构问题(是否地道、channel 还是 mutex、小接口还是大接口、是否用 Cgo/unsafe/reflect)。
  • go-modern:版本感知的现代 Go 语法,用于决定使用哪个特性(slices/maps/cmp、t.Context()、omitzero、b.Loop()、wg.Go()、errors.AsType 等)。

当问题是“这段代码是否可用于生产”或“审查这个 PR”时使用本技能。

来源依据

内容整理自 Go 官方文档、Go Code Review Comments、Go 博客的错误处理指导、Google 的 Go 风格指南与 Uber Go 风格指南;详细来源映射位于 references/go-practices.md 顶部。