go-development

Go 开发模式

核心原则

类型安全

• 避免： interface{}（改用 any）、sync.Map、零散的类型断言、反射
• 优先使用： 泛型 [T any]、errors.AsType[T]（Go 1.26）、具体类型
• 升级后运行 go fix ./...

一致性

• 每个问题领域采用一种模式
• 与现有代码库的模式保持一致
• 要么整体重构，要么不重构
• 配置优先级：默认值 < 配置文件 < 环境变量 < 标志

测试

• 使用构建标签隔离测试层级：单元测试（默认）、integration、e2e
• 始终使用 t.Parallel()、t.Helper() 和表驱动子测试
• 直接使用 log/slog——切勿将其封装在自定义 Logger 接口中

约定

• 命名：ID、URL、HTTP（而非 Id、Url、Http）——不由工具强制执行（ST1003 默认关闭）
• 错误包装：fmt.Errorf("failed to process: %w", err)

参考资料

Git 钩子：ls lefthook.yml 2>/dev/null && lefthook install || echo "Add lefthook — see references/lefthook-template.md"

按需加载：

参考资料	用途
references/architecture.md	包结构、状态变更的完整性
references/logging.md	使用 log/slog 进行结构化日志记录、从 logrus 迁移
references/cron-scheduling.md	go-cron 模式：命名任务、运行时更新、弹性
references/resilience.md	指向 go-cron 内置的重试／断路器／超时包装器
references/docker.md	Docker 客户端模式、缓冲区池化
references/ldap.md	LDAP/Active Directory 集成
references/testing.md	构建标签、资源隔离、竞态问题
references/linting.md	golangci-lint v2、staticcheck
references/api-design.md	枚举／状态的防御性处理
references/fuzz-testing.md	Go 模糊测试模式、安全种子
references/contracts-and-invariants.md	契约、不变量、属性测试
references/mutation-testing.md	Gremlins 配置、测试质量衡量
references/makefile.md	CI/CD 的标准 Makefile 接口
references/modernization.md	go fix 现代化工具及其构建标签陷阱、errors.AsType[T]、b.Loop
references/dependencies.md	升级：go get -u all、主版本、构建集范围
references/lefthook-template.md	可直接用于 Go 项目 Git 钩子的 lefthook.yml
references/branch-protection.md	规则集水位线：三规则集门槛、绕过模式
references/reusable-workflows.md	可复用 Actions 工作流调用方、权限传递、发布门禁输出
references/single-build-release.md	单次构建发布：交叉编译一次，供发布和容器复用
references/awesome-go-submission.md	awesome-go 提交：由 CI 解析的 PR 正文、名称冲突

质量门禁

完成任何审查前运行：

golangci-lint run --timeout 5m    # Linting
go vet ./...                       # Static analysis
staticcheck ./...                  # Additional checks
govulncheck ./...                  # Vulnerability scan
go test -race ./...                # Race detection

标准库漏洞修复

当 govulncheck 报告标准库漏洞时：通过 vuln.go.dev 检查修复版本，在 go.mod 中更新 go X.Y.Z，然后运行 go mod tidy。

---

贡献： 请通过 https://github.com/netresearch/go-development-skill 提交改进。