River 编码规范与测试指南:从 Go 代码风格到并行测试实践的完整解读

原创2026-10-11 20:05:311,927 阅读
文章标签:任务调度后端

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 分区,顺序为:

  1. Standard(标准库)
  2. Default(第三方库)
  3. 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\. 模式,并提示 "Use require variants 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 有两项重要的工程约定:

  1. 驱动接口视为内部接缝而非对外 API:riverdriver 的包注释明确指出它不应由用户代码实现或调用,对其修改不被视为 semver-breaking。因此不要为外部消费者保留驱动接口的方法或语义;可以根据需要增删或重塑它们,只要不损害或能改进用户可见功能即可。
  2. 跨驱动一致性测试:把 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 的规则整理出完整的贡献者工作流:

  1. 修改代码前:确认新代码遵循字母序、gci 导入分区、snake_case JSON 标签、Func 后缀、require 断言、Postgres 术语等风格约束;
  2. 涉及 .sql 变更时:运行 make generate 重新生成 sqlc 目标与各语言迁移;
  3. 涉及依赖变更时:运行 make tidy;
  4. 运行测试:默认 make test;需要竞态检测用 make test/race;只想跑 SQLite 系驱动用 make test TEST_DATABASE=sqlite;单独调试用 cd $MODULE && go test ./path/to/package -run TestName;
  5. 运行 lint:默认 make lint(等价于对所有子模块执行 golangci-lint run --fix,可自动修复格式问题);
  6. 收尾:在无沙箱限制(完整权限)环境下再跑一次 make test 与 make lint,确保与本地开发及 CI 一致。

十、总结

AGENTS.md 表面上是给 AI Agent 的指令,实质上是一份浓缩的 Go 工程最佳实践清单:统一的 make 命令入口保证了本地与 CI 行为一致;gci 分区、字母序、文档注释等风格规则让万行级代码库保持可预期;riverdriver 内部接缝与 riverdrivertest 跨驱动一致性套件保障了多驱动架构的演进安全;而并行测试束 + setup(t) + TestSignal 的组合,则为并发后台任务系统的测试提供了高隔离、零 flaky 的工程范式。理解并遵守这套规范,是高质量地为 River 贡献 Go 代码的前提,也是阅读和扩展这个多语言队列项目的最短路径。

登录后查看全文
river