本资料是 Gram 代码库中关于编写和编辑 Go(Golang)代码的规则与最佳实践说明,属于项目内部的开发约定集合。
【语言版本与依赖原则】 该代码库使用 Go 1.25 及以上版本。在引入 go.mod 之外的第三方依赖时应保持务实,优先使用 Go 标准库,在建议第三方依赖之前先考虑标准库方案。
【错误处理】 需要实现正确的错误处理,必要时使用自定义错误类型。在低层函数中使用 fmt.Errorf 包装错误,提供独特且有用的上下文,例如 fmt.Errorf("save user: %w", err),避免使用无信息量的通用措辞。在 server/ 代码库的较上层函数(包括 HTTP 服务处理器)中,使用 server/internal/oops 包,将内部错误包装为用户可见的错误消息,例如 oops.E(oops.CodeBadRequest, err, "invalid cursor").Log(ctx, s.logger)。
【依赖注入】 始终通过构造函数将依赖直接注入服务结构体,不要使用会话管理器暂存服务后续需要的依赖。服务需要数据库访问时,注入 DB 连接,并在需要时在函数内初始化查询辅助对象(repo.New)。新服务不应将 repo.Queries 直接存储在服务结构体上。
【认证上下文】 读取 authctx 时假设 ActiveOrganisationID 存在,除非有具体代码路径证明相反,否则不要为其添加防御性空值检查。
【第三方客户端】 第三方客户端的构造函数应总是返回可用的客户端实现,避免内部代码反复检查客户端是否为 nil。为本地开发和测试提供 stub 实现,并在 deps.go 中基于 c.String("environment") 选择真实或 stub 实现。不要将第三方请求/响应类型暴露给代码库其余部分,应在边界定义自有类型。
【函数形态】 避免仅转发到另一个方法且无实质逻辑的辅助函数,避免仅为间接调用而提取单次使用的一行方法,倾向于在调用点内联平凡行为。
【日志】 使用 log/slog。始终使用 server/internal/attr/conventions.go 中定义的日志属性。适当使用 logger.With(attr.SlogXXX(...)) 创建子 logger 以捕获上下文属性。不要滥用日志语句,聚焦于适当记录错误,减少过多的 info 级日志。使用 slog logger 时始终使用上下文感知方法:DebugContext、InfoContext、WarnContext、ErrorContext。记录错误时始终使用 attr.SlogError(err) 将错误包含在日志负载中,例如 logger.ErrorContext(ctx, "failed to write to database", attr.SlogError(err))。
【Context 参数】 任何涉及 API 调用、数据库查询或定时器操作的函数或方法都应将 context.Context 作为第一个参数。
【Lint 与结构体】 在完成代码更改时始终运行 linter,使用 mise lint:server 对服务器代码库运行 linter。exhaustruct linter 要求结构体字面量中显式设置所有字段;向类型添加新字段时,需更新所有调用点,包括以零值构造结构体的地方(如 MyStruct{} → MyStruct{NewField: nil})。
【更新 API】 项目使用 Goa 设计 API 并生成服务器代码,所有 Goa 代码位于 server/design,DSL 文档见 https://pkg.go.dev/goa.design/goa/v3/dsl。进行 API 更改(如创建新服务或更新现有服务)时:更新 server/design 中的 Goa 设计文件,然后运行 mise run gen:goa-server 重新生成 server/gen 中的服务器代码,建议用 git 查看新增/变更文件。实现 Goa 服务时,服务应位于独立 go 包并包含 impl.go 文件(如 server/internal/<service>/impl.go)。若创建新的 Goa 服务,需确保在 server/cmd/gram/start.go 中将其挂载到 HTTP 服务器。
【转换与可观测性工具】 使用 conv 包(server/internal/conv)进行常见类型转换,关键函数包括 conv.PtrEmpty、conv.PtrValOr、conv.Default、conv.ToPGText 系列、conv.FromPGText、conv.FromPGBool、conv.PtrToPGBool、conv.Ternary,不要内联重新实现指针辅助、三元表达式或 pgtype 转换。使用 o11y 包(server/internal/o11y)进行延迟清理与错误记录,包括 o11y.LogDefer(清理错误应被记录时使用)和 o11y.NoLogDefer(清理错误可静默丢弃时使用,如事务回滚或关闭响应体),始终使用它们替代裸 defer resource.Close() 调用。
【测试】 编写断言时专门使用 github.com/stretchr/testify/require。测试中使用 t.Context() 而非 context.Background(),但 t.Cleanup(func()) 回调内部除外。避免使用 t.Run 创建子测试,优先编写单独的测试函数。所有测试设置(包括启动数据库、缓存和后台 worker)必须放在 setup_test.go 文件中。测试中禁止为任何 Postgres 操作编写原生 SQL(SELECT、INSERT、UPDATE、DELETE、事务、CopyFrom、SendBatch 均已覆盖),应使用 SQLc 生成的方法;默认在相关领域包自己的 queries.sql 中添加新 fixture 查询,仅当 fixture 查询确实在多个包间复用时才使用 server/internal/testenv/queries.sql(以及 testenv/testrepo)。glint 的 no-testing-raw-sql 规则会对 *_test.go 中的 *pgxpool.Pool、*pgx.Conn、pgx.Tx 和 pgx.Querier 接收者强制执行此规定;ClickHouse 使用不同驱动,不受此标记。使用 github.com/stretchr/testify/mock 在测试中 mock 第三方库,而非围绕 vendor 类型的临时 fake。使用 testenv.NewLogger(t)、testenv.NewTracerProvider(t) 和 testenv.NewMeterProvider(t),而非内联构造 logger 或 noop OTel provider;testenv.NewLogger(t) 在普通运行中丢弃日志,在 go test -v 下输出美观日志,这是内联 slog.New(slog.DiscardHandler) 和 slog.New(slog.NewTextHandler(os.Stdout, nil)) 所不具备的;例外是断言日志输出的测试应使用基于 bytes.Buffer 的捕获 handler。
【代码完整性】 API 实现中不得留下任何 TODO、占位符或缺失部分。包含必要的 import、包声明和所需设置代码。解释应简洁,但对复杂逻辑或 Go 特有惯用法提供简短注释。如果不确定最佳实践或实现细节,应说明不确定而非猜测。在 API 设计与实现中始终优先考虑安全、可扩展性和可维护性。避免编辑任何开头带有 "DO NOT EDIT" 注释的源文件。
【适用场景与限制】 该资料面向使用 Gram 代码库的 Go 开发者,提供编写、编辑与审查 Go 服务端代码时的具体约定,包括 API 设计生成、日志、错误、依赖注入和测试等方面。资料未说明其作为独立工具或产品的收费、价格、平台或效果信息。