River 编码规范与测试指南:从 Go 代码风格到并行测试实践的完整解读
River 编码规范与测试指南:从 Go 代码风格到并行测试实践的完整解读
本文是 River(Go 语言实现的高性能后台任务队列,支持 Postgres 与 SQLite,并拥有 Ruby、Rust、JavaScript/TypeScript 等多语言移植)的面向 Agent 与贡献者的编码与测试规范指南。文档以 AGENTS.md 为核心,完整覆盖了 make 命令体系、Go 代码风格、包组织原则、文件内排序约定,以及一套基于并行测试束(parallel test bundle)与测试信号(TestSignal)的测试工程方法论。读者读完本文将掌握:如何正确运行 River 的测试与 lint、如何写出符合项目规范且可通过 CI 的 Go 代码,以及如何按照项目标准编写稳定、隔离、可读的并发测试。
一、总览:River 仓库的工程规范结构
River 是一个采用 Go workspace 组织的多语言仓库(参见根目录 go.work),Go 是核心实现语言,同时包含 java/、js/、ruby/、rust/ 四个移植版本。因此其编码规范体系也分层设计:
- Go 主模块遵循本文(AGENTS.md)描述的全部规则;
- 非 Go 语言移植拥有各自的开发文档与
make test/<language>目标,例如 docs/development.md 明确写道 Ruby、Rust、JavaScript 移植分别有独立的开发说明。
需要特别说明的是,仓库根目录还存在一份对 AGENTS.md 的规范性佐证——.golangci.yaml。AGENTS.md 中提到"see .golangci.yaml for allowed short variable names"等规则,正是该配置文件的落地体现。下表梳理了 AGENTS.md 的主题与对应的仓库实体:
| AGENTS.md 主题 | 落地实体(相对路径) |
|---|---|
make test / make lint 命令体系 |
Makefile |
| 并发测试束模式 | 各包 _test.go 中大量 type testBundle struct 用例,如 client_test.go、internal/jobcompleter/job_completer_test.go |
| TestSignal 测试信号 | rivershared/testsignal/test_signal.go 及其测试 test_signal_test.go |
| 短变量名、require 替代 assert、Func 后缀等 lint 规则 | .golangci.yaml 的 forbidigo、varnamelen 配置 |
| JSON 标签 snake_case | .golangci.yaml 的 tagliatelle 配置 |
| gci 导入分区 | .golangci.yaml 的 gci formatter 配置 |
二、测试与 Lint:统一使用 make 命令
AGENTS.md 的第一条硬性要求是:默认使用 make 封装命令,而非直接调用 go test 或 golangci-lint,只有在必须传递特定参数时才直接调用底层工具。
2.1 默认命令
- 测试:默认运行
make test。仅在需要传-run、-count、-race、build tags 等参数,或需要单独调试某个测试时,才用go test ...。 - Lint:默认运行
make lint。仅当必须传特定 flag 时才直接调用golangci-lint ...。 - 收尾要求:除非明确被告知不需要(例如未改动任何 Go 代码/测试),否则在认为任务完成之前必须先运行 test 与 lint。
- 沙箱说明:如果执行环境有沙箱/权限模型,
make test与make lint应在**非沙箱(完整权限)**环境下运行,以保证结果与本地开发及 CI 一致。
2.2 其他构建/测试命令
| 命令 | 用途 |
|---|---|
make test/race |
启用竞态检测器运行全部测试 |
cd $MODULE && go test ./path/to/package -run TestName |
单独运行某个测试 |
make bench |
运行各子模块的基准测试(默认 ITERATIONS=100) |
make generate |
生成各类产物(sqlc 等,见下文) |
make tidy |
依赖变更后对全部子模块执行 go mod tidy |
关于 make generate 与 make tidy,AGENTS.md 给出了两条触发规则:
- generate 规则:任何
.sql文件被修改后,都需要重新生成对应的.sql.go文件,即执行make generate; - tidy 规则:当依赖发生变更时执行
make tidy。
从 Makefile 可以进一步看到,make generate 实际聚合了多项生成任务:generate/fixtures(生成跨语言 conformance fixtures)、generate/java-migrations、generate/js-migrations、generate/migrations(将 riverpgxv5 迁移同步到 database/sql)、generate/ruby-migrations、generate/rust-migrations 以及 generate/sqlc。其中 generate/sqlc 会分别在 riverdriver/riverdatabasesql/internal/dbsqlc、riverdriver/riverpgxv5/internal/dbsqlc、riverdriver/riversqlite/internal/dbsqlc 三个目录下执行 sqlc generate。对应的校验目标是 make verify(含 verify/sqlc 等,通过 sqlc diff 检查生成的产物与预期一致)。
2.3 TEST_DATABASE 变量:按数据库裁剪测试套件
Makefile 中定义了 TEST_DATABASE 变量(取值 all、postgres、sqlite,默认 all),它会影响 make test 与 make test/race 实际覆盖的子模块集合:
TEST_DATABASE=sqlite:只运行 SQLite、libSQL、Turso 相关驱动测试(无需 Postgres);TEST_DATABASE=postgres:运行常规套件并排除 SQLite 命名测试;- 其他取值会直接报错:
TEST_DATABASE must be all, postgres, or sqlite。
这套设计的目的在 docs/development.md 中有明确说明:CI 将两套测试分开,使 Postgres 版本矩阵不必重复运行 SQLite 测试。另外,Makefile 中还有专门的 legacy subtransaction 回退测试(通过环境变量 RIVER_USE_LEGACY_SUBTRANSACTIONS=1 执行),用于覆盖临时 savepoint 回退路径。
三、Go 代码风格指南
AGENTS.md 用一节定义了完整的 Go 代码风格约束,这些规则大多能在 .golangci.yaml 中找到对应配置。
3.1 导入分区(Imports)
导入必须使用 gci 分区,顺序为:
- Standard(标准库)
- Default(第三方库)
github.com/riverqueue(本仓库/项目自身导入)
这一配置在 .golangci.yaml 的 formatter 段中体现为:
gci:
sections:
- Standard
- Default
- Prefix(github.com/riverqueue)
- Prefix(riverqueue.com/riverpro)
在真实测试文件中可以直观看到这一分区实践,例如 internal/jobcompleter/job_completer_test.go 的导入块:先是 context、errors、fmt 等标准库,接着是 github.com/jackc/puddle/v2、github.com/stretchr/testify/require 等第三方包,最后是以 github.com/riverqueue/river/... 开头的项目内部包。
3.2 格式化与命名
- 格式化:使用
gofmt、gofumpt、goimports(.golangci.yaml 的 formatters 段同时启用了这四者,另有gci)。 - JSON 标签:使用 snake_case。对应配置为
tagliatelle规则的json: snake。 - 错误处理:倾向使用 context-rich(携带上下文的)错误;禁用 lint 规则前需先审视规则本身。
- 测试断言:使用
require变体,而非assert。这在 .golangci.yaml 的forbidigo中直接禁止了^assert\.模式,并提示 "Userequirevariants instead."。仓库测试中大量使用require.NoError、require.Equal,例如 internal/maintenance/job_cleaner_test.go 中的require.Equal断言。 - 函数变量后缀:使用
Func后缀(而非Fn)。对应 forbidigo 规则禁止Fn\b模式。 - 文档注释:所有导出的函数与类型都必须包含注释。
- 术语:优先写 "Postgres" 而非 "PostgreSQL"。
- 命名:使用惯用的 Go 命名;允许的短变量名见 .golangci.yaml。该文件中
varnamelen.ignore-names列出了db、eg、f、i、id、j、mu、r、sb、t、tb、tt、tx、w、wg等短名。
3.3 依赖与 SQL 访问约束
- 依赖最小化:尽量只依赖标准库与
pgx,减少外部依赖。 - SQL 访问(非测试代码):禁止在库/运行时代码中编写临时拼接的 SQL 字符串。应当新增或扩展一条 sqlc 查询,通过
make generate重新生成,再经由驱动接口(driver interface)暴露。只有测试和基准/管理工具才允许直接写 SQL(例如pg_stat_statements与VACUUM)。
3.4 驱动接口稳定性与跨驱动测试
AGENTS.md 对 riverdriver 有两项重要的工程约定:
- 驱动接口视为内部接缝而非对外 API:
riverdriver的包注释明确指出它不应由用户代码实现或调用,对其修改不被视为 semver-breaking。因此不要为外部消费者保留驱动接口的方法或语义;可以根据需要增删或重塑它们,只要不损害或能改进用户可见功能即可。 - 跨驱动一致性测试:把
riverdriver/riverdrivertest视为驱动行为的共享一致性测试套件。当修改riverdriver或某个具体驱动(如 riverdriver/riverpgxv5、riverdriver/riversqlite、riverdriver/riverdatabasesql)时,应更新或扩展riverdrivertest,让预期语义在所有驱动上都被覆盖,而不只是在某一个驱动的测试里。
四、包命名与组织(Package Naming and Organization)
AGENTS.md 对包命名与目录组织给出明确约束:
- 包名小写、简短、有代表性;避免
common、util或过于宽泛的名称; - 使用单数包名,避免
httputils这类复数形式; - 保持导入路径干净,避免
src/、pkg/或其他仓库结构泄漏; - 按职责组织,而不是塞进
models/types之类的桶;类型应贴近其使用位置; - 不导出仅用于构建二进制的
main包中的标识符; - 为包添加文档注释,文档较长时使用
doc.go。仓库中internal/leadership/doc.go、根目录 doc.go 都是这一约定的实例。
五、代码组织:字母序是硬性要求
AGENTS.md 特别强调:新增代码时保持字母序非常重要(除非被要求,否则不要重组已有代码)。具体规则包括:
- 类型按名称字母序排列;
- 结构体字段按名称字母序排列(除非有充分理由偏离,例如 ID 字段放最前、把被 mutex 保护的字段分组在 mutex 之后);
- 声明结构体实例时,字段同样按名称字母序排列,除非有类似的合理例外;
- 类型的方法按名称字母序排列;
- 构造函数紧跟类型定义之后;
- 一个类型的所有方法集中放在类型定义与构造函数之后,按名称字母序排列,不要与其他类型或函数交错(除非某个小型工具类型仅服务于该方法且别处不用);
- 单元测试中:外层测试块按名称字母序排列,内层测试块在外层块内同样按字母序排列。
以 internal/jobcompleter/job_completer_test.go 为例,TestCompleterJobUpdatedFromStateAndReason 内部的 t.Run 子测试名按字母序排列:AvailableFailed、AvailableInterrupted、AvailableRequestedCompleted、AvailableSnoozed、Cancelled、Completed、Discarded、Pending、Retryable、Running、Scheduled、UnknownState。
六、Go 测试约定:并行测试束 + setup 辅助函数
AGENTS.md 最大篇幅用于描述这套测试模式,其灵感来自 Brandur 的并行测试束(parallel test bundle)实践。核心目标是:让并行子测试彼此隔离,并让 setup 与 fixtures 保持 DRY。
6.1 始终启用并行(Always opt into parallel)
- 顶层测试:每个
TestXxx的第一条语句必须是t.Parallel(); - 子测试:每个
t.Run(..., func(t *testing.T) { ... })的第一条语句必须是t.Parallel(),除非该子测试有意非并行,并且要加一行简短注释说明原因。
6.2 语句顺序与空行
- 顶层测试:
t.Parallel()→ 空行 → 测试前奏(ctx、setup、辅助函数)→ 空行 → 子测试/断言; - 子测试:
t.Parallel()→ 空行 → 子测试前奏; - 如果子测试调用了
setup(...),在 setup 赋值与断言/动作之间建议留一个空行; - 对于很小、显而易见的子测试(
t.Parallel()或setup(...)之后只有一条短语句),省略其中一处空行是可接受的。
6.3 上下文与 setup 的先后顺序
- 如果
setup需要ctx(即setup(ctx, t)),应先赋值/派生ctx,再调用setup; - 如果
setup不需要ctx(即setup(t)),则先调用setup,并把专用上下文(WithCancel、WithTimeout)放在靠近使用处派生; - 除非共享 setup 确实需要,否则避免在远离使用处创建/派生
ctx。
6.4 优先使用局部测试束(Prefer local bundles)
- 在
TestXxx函数内部定义一个type testBundle struct { ... },其中放被测系统(system under test)与跨子测试频繁使用的 fixtures; - 每个并行子测试应调用
setup(t)获取全新的 bundle;避免跨并行子测试共享可变状态。
在 client_test.go 中可以看到非常典型的实现(约第 380 行起):
func Test_Client_Common(t *testing.T) {
t.Parallel()
ctx := context.Background()
type testBundle struct {
config *Config
dbPool *pgxpool.Pool
driver *riverpgxv5.Driver
schema string
}
setupConfig := func(t *testing.T) (*Config, *testBundle) {
t.Helper()
// ... 构造 dbPool、driver、schema、config ...
return config, &testBundle{config: config, dbPool: dbPool, driver: driver, schema: schema}
}
setup := func(t *testing.T) (*Client[pgx.Tx], *testBundle) {
t.Helper()
config, bundle := setupConfig(t)
client, err := NewClient(bundle.driver, config)
require.NoError(t, err)
return client, bundle
}
t.Run("StartInsertAndWork", func(t *testing.T) {
t.Parallel()
// ...
})
}
internal/maintenance/job_cleaner_test.go 则展示了带 TestSignals.Init(t) 的 bundle 形式:
func TestJobCleaner(t *testing.T) {
t.Parallel()
ctx := context.Background()
type testBundle struct {
cancelledDeleteHorizon time.Time
completedDeleteHorizon time.Time
exec riverdriver.Executor
discardedDeleteHorizon time.Time
}
setup := func(t *testing.T) (*JobCleaner, *testBundle) {
t.Helper()
tx := riverdbtest.TestTxPgx(ctx, t)
bundle := &testBundle{
cancelledDeleteHorizon: time.Now().Add(-riversharedmaintenance.CancelledJobRetentionPeriodDefault),
completedDeleteHorizon: time.Now().Add(-riversharedmaintenance.CompletedJobRetentionPeriodDefault),
exec: riverpgxv5.New(nil).UnwrapExecutor(tx),
discardedDeleteHorizon: time.Now().Add(-riversharedmaintenance.DiscardedJobRetentionPeriodDefault),
}
cleaner := NewJobCleaner(
riversharedtest.BaseServiceArchetype(t),
&JobCleanerConfig{},
bundle.exec)
cleaner.StaggerStartupDisable(true)
cleaner.TestSignals.Init(t)
t.Cleanup(cleaner.Stop)
return cleaner, bundle
}
// 子测试:Defaults / StartStopStress / DeletesCancelledCompletedAndDiscardedJobs ...
}
6.5 setup 辅助函数规则
setup定义为测试内的局部闭包:setup := func(t *testing.T) *testBundle { ... };setup顶部必须调用t.Helper();- 只在确实需要时才接受 context 参数:
- 默认:
setup(t)不应接收ctx; - 若 setup 必须派生/播种 context:优先返回它:
setup := func(t *testing.T) (*testBundle, context.Context); - 若 setup 必须接收已有 context:把
ctx作为第一个参数:setup := func(ctx context.Context, t *testing.T) *testBundle;
- 默认:
- 保持
setup确定性且自包含,它只应使用传入的*testing.T(以及明确要求时的ctx)。
6.6 官方模板
AGENTS.md 给出了可直接套用的模板:
func TestThing(t *testing.T) {
t.Parallel()
type testBundle struct {
// Put SUT + common fixtures here.
}
setup := func(t *testing.T) *testBundle {
t.Helper()
return &testBundle{}
}
t.Run("CaseName", func(t *testing.T) {
t.Parallel()
bundle := setup(t)
// ... use `bundle` in assertions/actions ...
})
t.Run("CaseNameWithCtxRequiredBySetup", func(t *testing.T) {
t.Parallel()
setupWithCtx := func(ctx context.Context, t *testing.T) *testBundle {
t.Helper()
_ = ctx
return &testBundle{}
}
ctx := context.Background()
bundle := setupWithCtx(ctx, t)
// ... use `bundle` in assertions/actions ...
})
}
七、测试信号(TestSignal):让并发测试稳定不 flaky
7.1 约定
AGENTS.md 要求:优先使用 rivershared/testsignal.TestSignal(放在一个 ...TestSignals 结构体中,并配 Init(tb) 辅助函数),而不是在 spy/fake 里临时使用 chan struct{} 字段。配套规则:
- 测试信号结构体默认保持零值,只在需要观察这些信号的测试中调用
Init(t); - 等待异步事件用
WaitOrTimeout();负向断言用RequireEmpty()或WaitC()+ 带超时的 select; - 除非有具体且已说明的理由,否则避免自造 channel 信号辅助函数与手工管理 channel 容量。
7.2 源码实现
rivershared/testsignal/test_signal.go 实现了这一机制。其设计巧妙之处在于对生产代码几乎零侵入:
TestSignal[T]内部持有一个容量为 50(testSignalInternalChanSize)的带缓冲 channel 与一个tb;Signal(val T):在生产环境(未Init)中调用会安全地 no-op——这正是"嵌入该类型的实体在非测试环境下也能安全调用 Signal"的设计目标。其注释明确说明:"在未初始化的原始 signal(也就是测试之外应该发生的情况)下直接返回"。已初始化时通过select非阻塞写入,channel 满则记录测试错误而非阻塞生产代码;Init(tb):只能从测试调用,用于初始化内部 channel;WaitOrTimeout():等待下一次Signal注入的值,超时会通过tb.Errorf报告;RequireEmpty():断言信号未收到任何值,未初始化时 panic;WaitC():返回可等待值的 channel,用于与select组合做超时控制。
其测试 rivershared/testsignal/test_signal_test.go 覆盖了四个场景:Uninitialized(未初始化时反复 Signal 安全)、Initialized(初始化后可多次发送但容量有限)、RequireEmpty、WaitC、WaitOrTimeout。
7.3 在真实测试中的使用
- client.go 中定义了
clientTestSignals结构体(约第 785 行),聚合了jobCleaner、jobRescuer、jobScheduler、periodicJobEnqueuer、queueCleaner、queueMaintainerLeader、reindexer等各维护组件的*TestSignals,并提供Init(tb)逐一初始化; - internal/maintenance/job_cleaner_test.go 中
setup内调用cleaner.TestSignals.Init(t),然后在子测试中用cleaner.TestSignals.DeletedBatch.WaitOrTimeout()等待清理批次执行完毕。
此外,.golangci.yaml 中还为 testsignal 设计了专门的 depguard 规则:testsignal(非测试代码中也会用到)及其依赖的 testutil 只允许使用标准库,避免把 Testify、Goleak、YAML 等测试依赖间接带进所有使用 River 构建的二进制文件(此前曾因误导入导致二进制膨胀约 10 kB)。
八、把这些规范应用到多语言仓库
River 仓库的 Go 规范是其多语言体系的"参考实现":conformance 目录下的 fixtures(由 Go 实现生成,见 conformance/cmd/generatefixtures)被 Java、JS、Ruby、Rust 各移植的测试直接引用比对。这意味着 Go 侧的任何协议级改动,都要通过各语言的 conformance 测试目标来校验:
make test/java/conformance、make test/js/conformance、make test/ruby/conformance、make test/rust/conformance分别运行各移植与 Go 生成 fixtures 的对比测试;make generate/fixtures负责从 Go 实现生成这些跨语言 fixtures。
对于主要贡献 Go 代码的开发者,规范中还有一条贴心约定:Rust、Java、JS 等语言的 test/lint 目标与 Go 的 make test、make lint 相互独立(见 Makefile 注释),这样仅涉及 Go 的贡献者无需安装 Rust 工具链、JDK 或 Node.js 也能完成完整的 Go 侧校验。相应地,docs/development.md 也说明了测试数据库的搭建方式(createdb river_test 后运行 make test,可选 TEST_DATABASE=sqlite 在无 Postgres 环境下运行)。
九、常见工作流速查
以下按 AGENTS.md 的规则整理出完整的贡献者工作流:
- 修改代码前:确认新代码遵循字母序、gci 导入分区、snake_case JSON 标签、
Func后缀、require断言、Postgres 术语等风格约束; - 涉及
.sql变更时:运行make generate重新生成 sqlc 目标与各语言迁移; - 涉及依赖变更时:运行
make tidy; - 运行测试:默认
make test;需要竞态检测用make test/race;只想跑 SQLite 系驱动用make test TEST_DATABASE=sqlite;单独调试用cd $MODULE && go test ./path/to/package -run TestName; - 运行 lint:默认
make lint(等价于对所有子模块执行golangci-lint run --fix,可自动修复格式问题); - 收尾:在无沙箱限制(完整权限)环境下再跑一次
make test与make lint,确保与本地开发及 CI 一致。
十、总结
AGENTS.md 表面上是给 AI Agent 的指令,实质上是一份浓缩的 Go 工程最佳实践清单:统一的 make 命令入口保证了本地与 CI 行为一致;gci 分区、字母序、文档注释等风格规则让万行级代码库保持可预期;riverdriver 内部接缝与 riverdrivertest 跨驱动一致性套件保障了多驱动架构的演进安全;而并行测试束 + setup(t) + TestSignal 的组合,则为并发后台任务系统的测试提供了高隔离、零 flaky 的工程范式。理解并遵守这套规范,是高质量地为 River 贡献 Go 代码的前提,也是阅读和扩展这个多语言队列项目的最短路径。