Go
这些规则是本仓库做出的选择。通用 Go 风格不在此重复。
服务/基础设施
我们喜欢使用的服务:
Stream:用于 Agents、Chat、Video 和 Moderation
Planetscale:Postgres/数据库托管
Cloudflare:用于存储、媒体等
Resend:邮件
Stripe:支付
包
redis 使用 rueidis
postgres 和 ORM 使用 bun
迁移使用 pressly/goose
测试使用 stretchr/testify
OpenAPI 使用 Huma,路由使用 Chi
使用 OpenAPI 以便正确生成客户端 SDK
yaml 配置使用 koanf
监控使用 otel
规则
在使用较新特性之前,先检查最近的 go.mod 的 go 指令。8 个模块固定了不同版本:acceleration 是 1.27,tui 是 1.26,sdks/go 是 1.25。
用 %w 包装错误。消息以包名开头,说明正在做什么,不要用“failed to”:oauth2cc: token: %w。如果错误本身已经说明足够,就原样返回。在 acceleration/ 中,当错误进入代码库时调用 stack.Wrap(internal/stack/stack.go),然后原样向上传递。
只处理一次错误。绝不要既记录错误又返回它。
使用 log/slog 记录日志。把数据放在键值字段中,而不是消息中:logger.Warn("could not store an MCP event subscription", "subscription", sub.ID, "error", err)。
HTTP 处理器返回错误,不记录日志。withRequestLog(internal/api/server.go)会连同堆栈记录错误,5xx 以 error 级别记录(见 AGENTS.md 的“HTTP API”)。
span 名称使用小写点分词,先区域后步骤:appconfig.read、quota.allow、turn.llm。
将 ctx context.Context 作为第一个参数传递。不要把请求的 context 存储在结构体中。服务可以在 New 中持有一个生命周期 context 及其 cancel 函数,就像 channels.Service 那样。
不要在 init() 或构造函数中启动 goroutine。在 Start(ctx) 或 Run(ctx) 中启动,就像 chatlog.Log.Start 那样。
对于“无”返回 nil 切片。JSON 响应是例外:它发送 [],而不是 null。
防御性代码(重试、回退、二次检查)需要注释说明具体威胁:并发写入者、调用方会重试的网络故障、格式错误的输入。如果无法指出一个,就不要添加(见 AGENTS.md 的“Code style”)。
注释
注释用最少的词说明一次原因。不要叙述代码做了什么。
不要在注释中写新的工单、PR 或计划引用:它们属于提交和 PR。保留已有的。
链接到公开、稳定的来源(RFC、引擎文档化的限制)是可以的。注释仍需陈述事实。
性能
Redis 客户端缓存非常适合不常更改的配置等
检查给定 API 调用执行了多少次 redis 和 postgres 查询
减少查询或使用流水线通常很有效
sync.Pool 可能很重要,看看哪里可以使用
测试
在添加测试或测试套件之前,阅读 Go testing。它链接到每种测试的指南:controllers、store 和 AI routing。
其他技能
出站调用和流的超时:security 技能(.claude/skills/security/go.md,“Abuse limits”)。
N+1 查询和批量大小:loop_performance_bench 技能(.claude/skills/loop_performance_bench/SKILL.md)。