SuperAPI AI 工具集

go-idiomatic

设计与创作

查看项目

更新于 10-16 07:24

技能介绍

用途:为特定仓库提供 Go 工程规范,说明该仓库在通用 Go 实践之上额外要求或收紧的规则,适用于每一次代码变更。

主要能力:按主题路由到参考文档,包括并发(goroutine、channel、sync、errgroup、泄漏与竞态)、错误(哨兵错误、错误类型、跨包与 HTTP 转换、defer 清理、panic)、中间件(Content-Type、CSRF、会话 Cookie)、密钥(会话与重置令牌、密码重置、列加密)、日志(logger 注入、级别选择、CLI 输出与日志区分)、设计模式(接口、零值、标识类型、反模式)、可选值 Option[T]、指针与值接收者、HTTP 客户端、os/exec 调用、SQL 存储。

核心规则:错误用 fmt.Errorf("<verb> <noun>: %w", err) 包装,错误字符串小写、无标点、不用 failed to;错误只处理一次,返回带上下文或链顶记录,不可两者兼有;仅在跨包调用方分支判断时导出哨兵错误;不得用 _ = 丢弃错误;panic 仅用于程序员错误。只有错误停止传播的组件(handler、worker、长驻服务)通过构造函数注入 slog.Logger,main 构建唯一 logger,禁止调用 log.、slog.Info、slog.Default();日志消息为常量,变量放入 snake_case 键值属性,禁止记录密钥与个人数据;面向用户的输出写入注入的 io.Writer。

代码组织:应用入口为 cmd/<app>/main.go,仅做依赖装配,其余放 internal/;pkg/ 仅用于外部导入的库模块。共享逻辑在第三个不同包重复时提取;包名按功能命名,禁止 helpers、common,utils 仅限跨多包且不导入 internal/ 时使用;禁止包级状态与 init() 中设置全局 *sql.DB;main 一次性解析环境为类型化配置并校验,启动失败即退出,cmd/ 以下不得调用 os.Getenv。

函数设计:参数超过 3–4 个时改为结构体或函数选项;复杂参数先声明具名局部变量;提前返回,主路径不缩进,return 后不加 else;用 switch 替代 if/else if 链;指针用于可变与较大结构体,值用于小型不可变类型,不用 *T 表示“可能未设置”。命名按返回值或行为,布尔用谓词形式,缩写仅限 Go 惯例。注释规则以 ~/.claude/rules/comments.md 为准。

工具与限制:完成前运行 gofmt、goimports、go vet ./... 与 golangci-lint run;不得对既有违规添加 //nolint。测试相关规则由 go-testing 技能负责。资料未提供具体安装命令、收费与平台信息。