企业官网建设流程全解析

• 数据库
• 文档数据库
• 后端

mongo-go-driver 是 MongoDB 官方 Go 驱动，仓库中内置了一套面向开发者的提交前（pre-PR）验证流程，集中定义在 .claude/skills/pre-pr/SKILL.md 中。这篇指南将带你逐条拆解该流程的五个步骤：如何通过task一次性跑完构建、版权、格式、模块、静态检查与测试六道关卡，如何用git merge-base+api-report识别公开 API 变更，以及如何确保迁移文档与提交信息符合仓库规范。读完你不仅能理解这条质量门禁的完整链路，还能在自己提交 PR 前按同样的标准自查，减少来回 review 的成本。

一、Pre-PR 验证的整体脉络

根据 SKILL.md，一次完整的 pre-PR 验证按顺序执行五个动作：

1. 运行默认 task target：执行task，一次跑完 build、check-license、check-fmt、check-modules、lint、test-short，任何失败都要带着精确错误输出上报。
2. 检查公开 API 变更：用git diff --name-only $(git merge-base HEAD master)..HEAD列出本分支相对 master 合并基点改动过的文件，如果命中mongo/、bson/、event/、tag/任一目录，就提醒开发者运行task api-report并把报告附进 PR 描述。
3. 检查迁移文档更新：如果本次改动引入了用户可见的破坏性变更，提醒同步更新 docs/migration-2.0.md。
4. 检查提交信息格式：逐条校验本分支的提交信息是否符合GODRIVER-NNNN Short description格式，不符合的一一标记。
5. 总结：汇总通过项、失败项和后续必做事项（api-report、迁移文档、JIRA 前缀）。

这套流程的设计意图很清晰：把"能否合入 master"的大部分硬性校验前置到 PR 提交之前，让 CI（仓库通过 Evergreen 等平台运行同类检查）与人工 review 只聚焦真正的代码质量。注意 SKILL.md 末尾还提示，本仓库另一份更深入的mongo-go-driver-pr-reviewskill 负责对代码改动本身做深度审查，应在上述验证通过之后再运行。

二、第一步：task默认流水线到底跑了什么

SKILL.md 说task会运行 "build, check-license, check-fmt, check-modules, lint, and test-short"。打开仓库根目录的 Taskfile.yml 可以确认这条依赖链的真实定义：

default: deps: [build, check-license, check-fmt, check-modules, lint, test-short]

也就是说，执行task时 Taskfile（基于 taskfile.dev 的任务运行器）会按依赖顺序触发上面六个子任务，任何一个退出码非零都会让整个流水线失败。下面逐一拆解每个子任务在仓库里对应的真实实现。

2.1 build：多 tag 编译 + 测试编译 + 编译检查

Taskfile.yml 中的build任务不是简单的go build ./...，它包含五段：

• go build ./...：默认构建所有包；
• go build ${BUILD_TAGS} ./...：按构建标签（如 gssapi、cse 等）再构建一遍；
• task: build-tests：即go test -short ${BUILD_TAGS} -run ^$ ./...，用空的正则只编译测试二进制而不真正执行测试；
• task: compilecheck：进入 internal/test/compilecheck 独立模块执行go test -timeout 30m -v ./...，验证示例/辅助代码在GOTOOLCHAIN=auto下可编译；
• task: build-awsauth-compilecheck：进入 internal/test/awsauth 模块执行go build ./...，确保 AWS 认证相关扩展代码可编译。

此外build还依赖install-libmongocrypt，即 etc/install-libmongocrypt.sh，用于客户端侧加密（CSFLE）场景所需的 libmongocrypt 原生库。这意味着本地的第一次task可能要先下载并编译这个库，属于正常现象。

2.2 check-license：逐文件核对 Apache 版权头

etc/check_license.sh 扫描仓库内所有*.go文件（跳过.开头的隐藏目录），对每个文件做三项判定：

• 文件头 24 字节等于// Copyright (C) MongoDB视为已有标准版权头；
• 文件头 14 字节等于// Copied from视为第三方拷贝文件，放行；
• 两者都不是则报错：Missing copyright notice in "<file>". Run "task add-license" to add missing licenses.并退出码非零。

也就是说，该检查要求所有 Go 源文件必须带 MongoDB 的 Apache License 2.0 版权声明（LICENSE），或者显式标注来源。需要批量修复时可以运行task add-license（等价于bash etc/check_license.sh -a，自动把版权头写入缺失文件）。

2.3 check-fmt：gofumpt 严格格式化

check-fmt先通过内部任务安装gofumpt@v0.9.2与lll（超长行检查工具），再执行go run ./internal/cmd/check-fmt。仓库对 Go 代码的格式化采用比gofmt更严格的 gofumpt 风格，任何未格式化的文件都会在此步失败。本地格式化命令是task fmt（gofumpt -w .），建议提交前先跑一遍。

2.4 check-modules：go mod tidy无差异校验

etc/check_modules.sh 会find . -name go.mod找出仓库内所有 Go module（当前仓库结构下至少包括根模块go.mongodb.org/mongo-driver/v2（见 go.mod），以及 examples/go.mod、ext/awsauth/go.mod 等独立模块），对每个模块执行go mod tidy -v，然后git diff --exit-code go.mod go.sum确认没有产生任何意外变更。它的注释说明了意图：应当始终能对 go.mod 执行 tidy 且不产生无关改动，从而保证依赖声明"恰好正确"。

2.5 lint：跨平台静态分析

etc/golangci-lint.sh 固定使用 Go 1.26.0 与 golangci-lint v2.8.0，并特别强调"与 Evergreen 静态分析构建变体使用的 Go 版本保持一致"。脚本会先下载对应 Go 工具链，再以六个GOOS/GOARCH组合分别执行golangci-lint run --config .golangci.yml ./...：

• linux/386、linux/arm、linux/arm64、linux/amd64、linux/ppc64le、linux/s390x

跨平台 lint 的目的是捕获只在特定架构下暴露的静态分析问题——例如 32 位架构上原子变量对齐的 SA1027 告警。这说明该驱动的 lint 不仅关心逻辑正确性，还关心跨架构可移植性。

2.6 test-short：短时 + 竞态检测

test-short定义为go test ${BUILD_TAGS} -timeout 60s -short -race ./...：对所有包运行短模式测试，开启-race竞态检测，单包超时 60 秒。与之对应，本地完整测试请用task test（-timeout 1800s -p 1 ./...）或task test-race，它们需要本地有mongod监听默认 27017 端口（见 docs/CONTRIBUTING.md）。

三、第二步：识别公开 API 变更并生成 api-report

3.1 用 merge-base 圈定改动范围

SKILL.md 给出的命令是：

git diff --name-only $(git merge-base HEAD master)..HEAD

git merge-base HEAD master找到当前分支与 master 的最近共同祖先（分叉点），..HEAD列出从该基点之后本分支所有提交触及的文件。随后只需判断这些路径是否落在四个公开 API 目录下：

• mongo/：面向用户的客户端、集合、数据库、游标、会话等 API（如 mongo/client.go）；
• bson/：BSON 编解码与类型系统（如 bson/marshal.go）；
• event/：事件与监控接口（event/monitoring.go）；
• tag/：tag包（tag/tag.go）。

只要命中其中之一，就说明公开 API 可能发生变化，必须生成 API 变更报告。

3.2 api-report 的底层实现

task api-report实际执行 etc/api_report.sh，其关键流程：

1. 若BASE_SHA == HEAD_SHA（非 PR 运行）直接跳过；
2. 在临时分支test-api-report上提交本地改动，保证基线干净；
3. 安装gorelease（golang.org/x/exp/cmd/gorelease@latest）；
4. 执行gorelease -base=$BASE_SHA > api-report.txt || true生成原始报告；
5. 由 internal/cmd/parse-api-report/main.go 解析api-report.txt并输出人类可读的api-report.md：它会把形如go.mongodb.org/mongo-driver/...的路径缩写为.前缀、抑制internal/integration等内部路径的噪音，并在没有任何变更时写出No changes found!；
6. 通过 Evergreen 的 GitHub App 脚本把## API Change Report作为评论发布到对应 PR。

理解了这个实现，就能明白 SKILL.md 的提示为什么重要：api-report依赖BASE_SHA环境变量，本地直接跑bash etc/api_report.sh前需要先导出它（通常指向 master 上的某个基线提交），否则脚本会因为找不到基线而无法正确对比。

四、第三步：破坏性变更必须同步迁移文档

仓库的 docs/migration-2.0.md 是一份 1254 行的 v1.x → v2.0 升级指南，覆盖description包移除、事件常量重命名（如PoolCreated→ConnectionPoolCreated）、CommandFailedEvent.Failure从 string 改为 error 类型、mongo.Connect()移除context.Context参数、options 合并函数收敛（参见其中 GODRIVER-2696 的说明）等大量破坏性变更条目。

SKILL.md 第三步的意图是：任何让现有用户代码无法直接编译或行为改变的改动，都必须在此文档中记录，否则下游用户在升级驱动时会迷失方向。这也是为什么文档长期维护、条目按"事件包 / Mongo 包 / 选项包"等模块分节组织——它本质上是给所有使用者的迁移手册，改动它本身也需要遵循同样的 pre-PR 规范。

五、第四步：提交信息必须带 GODRIVER 前缀

仓库约定提交信息格式为GODRIVER-NNNN Short description。这并非凭空规定，docs/CONTRIBUTING.md 明确要求：提交信息与 PR 标题都要包含以GODRIVER前缀的 JIRA 票号（例如GODRIVER-123），并建议遵循经典的 Git 提交信息写作规范。仓库中的真实提交（如 go.mod 里的 replace 注释 提到的GODRIVER-3225）也印证了这一前缀的日常使用。

在执行这一步时，校验的对象是当前分支相对 master 的全部提交，而不是只查最新一条；发现不符合格式的提交，应在总结中逐个标记，提示开发者补票号或改写提交信息。

六、第五步：汇总输出与后续动作

验证的最后一步是把结果整理成一份清晰的报告，至少包含：

• 通过项：task 流水线六道关卡、API 检查、迁移文档、提交格式各自的结果；
• 失败项：精确的错误输出（编译错误、lint 告警、缺失版权头等），便于开发者直接定位；
• 必做的后续动作：task api-report并把api-report.md附入 PR 描述、必要时更新 docs/migration-2.0.md、为缺失 JIRA 前缀的提交补GODRIVER-NNNN。

值得补充的是，PR 生命周期在提交后还有自动化环节：仓库的 etc/pr-task.sh 定义了apply-labels（按 .github/labeler.yml 打标签）、assign-reviewer（按 .github/reviewers.txt 指派 reviewer）、backport-pr（把修复回移植到旧分支）等 Evergreen 任务，它们共同构成"提交前验证 + 提交后自动化"的完整协作闭环。

七、实操：如何在本地复现整套验证

把上面的流程落成本地操作，推荐顺序如下：

# 1. 安装 task 运行器（见 https://taskfile.dev/） # 2. 跑默认流水线（需要 libmongocrypt；如需 mongod 相关的完整测试，先启动本地 mongod:27017） task # 3. 检查公开 API 改动范围 git diff --name-only $(git merge-base HEAD master)..HEAD | grep -E '^(mongo|bson|event|tag)/' || true # 4. 若命中上述目录，导出基线并生成报告 export BASE_SHA=$(git merge-base HEAD master) task api-report # 产物为 api-report.md，将其内容附入 PR 描述 # 5. 逐条检查提交信息 git log --oneline $(git merge-base HEAD master)..HEAD # 6. 破坏性变更记得更新 docs/migration-2.0.md，随后重新跑 task 确认全绿

几点前提需要说明：task流水线中的lint与check-fmt会联网安装固定版本的 Go 工具链与 lint 工具；check-modules要求仓库处于干净的 git 状态（它会实际执行go mod tidy并 diff）；完整task test系列依赖本地mongod。若只是做纯静态的快速验证，task build check-license check-fmt check-modules lint test-short可拆开单独执行。

八、小结

pre-PR 验证是 mongo-go-driver 仓库把质量门槛前置的工程实践：SKILL.md 给出了五步操作清单，Taskfile.yml 与 etc/ 下的脚本则提供了每一步的可执行实现。对贡献者而言，在本地跑通这套流程意味着你的改动大概率能顺利通过 CI 与人工 review；对希望借鉴工程实践的团队而言，它也是一个"task 聚合多道静态/动态检查 + merge-base 圈定影响面 + 报告自动化"的完整参考范本。

• 数据库
• 文档数据库
• 后端