Go项目如何禁止隐式依赖_Go模块依赖约束方法_技术教程

根本原因是Go模块的“最小版本选择”（MVS）机制：只要间接依赖被任一直接依赖声明在go.mod中，go mod tidy就会将其拉入顶层go.mod，即使代码未import。

为什么 `go mod tidy` 会拉入不该有的依赖

根本原因是 Go 模块的“最小版本选择”（MVS）机制：只要某个间接依赖被任意一个直接依赖声明在它的 go.mod 里，go mod tidy 就会把它拉进你的项目顶层 go.mod，哪怕你代码里一行都没 import 它。这不是 bug，是设计使然——但对依赖收敛很不友好。

常见诱因包括：

你依赖的库 A 依赖了库 B（比如 github.com/some/a → github.com/some/b），而 B 又悄悄引入了 golang.org/x/tools 这类重型工具包

某个测试用的 require 被错误写进了生产模块的 go.mod
本地 replace 或 exclude 没生效，因为 go mod tidy 会自动清理未被引用的 exclude 条目

用 `go mod edit -dropreplace` 和 `-dropexclude` 清理残留

go mod edit 是唯一能安全修改 go.mod 结构而不触发自动重写的方式。尤其当你要删除 replace 或 exclude 后再重新验证时，必须先清掉旧条目，否则 tidy 可能忽略你的意图。

实操步骤：

删掉所有 replace：

go mod edit -dropreplace=github.com/old/lib

删掉某条 exclude：

go mod edit -dropexclude='github.com/bad/dep v1.2.3'

批量清空 exclude（谨慎！）：
```
go mod edit -dropexclude=all
```
执行后务必手动运行 go mod tidy -v 观察输出，确认没意外拉入新依赖

用 `//go:build ignore` 隔离测试/工具依赖

很多隐式依赖来自 _test.go 文件或构建标签启用的工具代码（比如生成器、linter 配置）。Go 不会为 test 或 tools 构建目标解析依赖，但 go mod tidy 默认扫描全部文件。

正确做法是把纯工具代码放进独立目录，并加构建约束：

package tools

import _ "golang.org/x/tools/cmd/stringer"
import _ "github.com/golangci/golangci-lint/cmd/golangci-lint"

然后在该文件顶部加：

//go:build tools
// +build tools

package tools

再在主 go.mod 中显式 require 工具模块（防止 CI 环境缺失）：

go mod edit -require github.com/golangci/golangci-lint/cmd/golangci-lint@v1.54.2

这样 go mod tidy 就不会把它当作运行时依赖处理。

CI 中用 `go list -m all` 做依赖白名单校验

禁止隐式依赖最可靠的方式不是靠人盯，而是让 CI 拒绝任何未明确定义的模块出现在最终依赖图中。

在 CI 脚本中加入：

#!/bin/sh
set -e
ALLOWED_DEPS="\
  github.com/sirupsen/logrus \
  go.uber.org/zap \
  golang.org/x/net \
  "
for mod in $(go list -m -f '{{.Path}}' all); do
  if ! echo "$ALLOWED_DEPS" | grep -q "^$mod\$"; then
    echo "ERROR: unexpected module $mod" >&2
    exit 1
  fi
done

注意点：

go list -m all 输出的是 MVS 下实际解析出的所有模块，比 go.mod 更真实
白名单要包含所有直接依赖 + 显式需要的间接依赖（比如你用了 grpc-go 的某个子包，它依赖 golang.org/x/net/http2，那后者也得进白名单）
别忘了排除 std 和 cmd 等标准库模块，它们不会出现在 go list -m all 输出里

真正难控的从来不是怎么写规则，而是谁来维护那份白名单——每次加一个新库，都得同步更新它，否则 CI 立刻失败。这恰恰是约束生效的前提。