Go 包与可见性：让依赖关系能被编译器检查

把一个大文件拆成十个文件，代码不一定更容易维护；把一个包拆成十个互相导入的包，甚至会直接编译失败。Go 的组织边界是包：哪些名字能被外面使用，哪些目录只允许内部代码导入，启动时先初始化谁，都是沿着这个边界确定的。

这篇文章从一个小程序展开：它有计数器、内部实现、初始化依赖，以及用接口接上的存储层。读完应该能回答三个实际问题：一个名字为什么看得见或看不见；程序还没进 main 时运行了什么；两个包互相需要对方时该怎样拆。正文结果在 Go 1.27.2、Linux/amd64 上实测，完整项目在文末。

先分清模块、目录、包名和导入路径

go.mod 中的 module example.com/packagelab 标识一个模块。模块负责把一组包作为同一个依赖与版本单元管理，包才是编译和导入时直接面对的单位。子目录中的包，其导入路径通常由模块路径加相对目录组成。^[1]

比如这棵目录：

text

packagelab/
├── go.mod                       module example.com/packagelab
├── counter/counter.go           package counter
├── service/
│   ├── api/api.go               package api
│   └── internal/token/token.go  package token
└── cmd/demo/main.go             package main

名称	本例的值	它决定什么
模块路径	`example.com/packagelab`	模块身份，组成包的导入路径
包所在目录	`counter/`	哪些源文件放在一起构建
包声明	`package counter`	导入后默认使用的包名
导入路径	`example.com/packagelab/counter`	工具链究竟去找哪个包
当前文件里的导入别名	`count`	这个文件内用什么限定名访问它

导入路径与包名不是一回事。下面可以给同一个包换一个本地名字，counter 包本身没有被重命名：^[2]

import count "example.com/packagelab/counter"

这个别名只在当前文件生效。同包的另一个文件想调用该包，仍要自己写 import；包级变量和函数则在同包文件之间共享可见性。一般一个目录内参与同次构建的普通 Go 文件要属于同一个包，外部测试文件可以用 xxx_test 这个专门约定。构建标签还可能决定本次实际选中了哪些文件，不能只凭目录里出现了哪个 .go 文件就断言它会被编译。^[2:1]^[3]

main 也是包名，但可执行程序有额外要求：主包叫 main，并定义不带参数、没有返回值的 main 函数。cmd/ 是常用项目布局，目录名字本身不会把一个包变成命令。^[4]

导出看名字，但并不是所有大写名字都能在外面访问

日常代码里可以记成“首字母大写对外，小写留在包内”。完整规则还包括声明位置：标识符以 Unicode 大写字母开始，并且是包级声明，或字段名、方法名，才是导出的标识符。函数里的局部变量即使叫 Result，也不会成为包的公开 API。^[5]

声明	同包其他文件	其他包	说明
`type Counter struct {...}`	可见	可见	导出类型
`func New() *Counter`	可见	可见	导出函数
`func secret()`	可见	不可直接访问	包内辅助函数
`Counter.value`	可见	不可直接访问	未导出字段
`(*Counter).Add`	可见	可调用	导出方法
函数内 `Result := 1`	不可见	不可见	局部作用域，不因大写而扩大

下面的计数器保留了修改方式，但没有开放内部字段：

package counter

type Counter struct{ value int }

func (c *Counter) Add(n int) { c.value += n }
func (c Counter) Value() int { return c.value }
func secret() int { return 99 }

调用方这样使用：

var c counter.Counter
c.Add(3)
fmt.Println("counter", c.Value())

实际输出：

text

counter 3

而以下两行已在独立反例中编译，均失败：

_ = c.value
_ = counter.secret()

这次编译器分别报：

text

c.value undefined (type counter.Counter has no field or method value, but does have method Value)
undefined: counter.secret

value 明明在源代码里，但跨包选择器不允许调用者直接选中它。这样以后把内部存储换掉，只要保留 Add 和 Value 的约定，调用方就不用一起改。这里的设计收益是基于可见性规则的工程判断，不意味着导出方法自动保证正确性；例如这个 Counter 没有并发保护，不能让多个 goroutine 任意同时修改。

还有一个容易混淆的点：包可以导出一个函数，返回未导出类型的值；调用者不能写出那个类型名，却仍可能通过类型推断持有它、调用它的导出方法。可见性约束的是名字的使用，不是“这个值从此无法到达外部”。是否采用这种 API，要看它是否让使用者容易理解。^[5:1]^[6]

internal 约束的是“谁能导入这个目录”

大小写管的是包里的标识符，internal 管的是整个包的导入资格。这是 Go 工具链的目录规则：含有 internal 路径段的代码，只能被 internal 的父目录树内的代码导入。^[7]

对本例 service/internal/token，保护边界是 service/，不是整个仓库，也不只是 token/ 自己。模块模式下，go 命令按对应的导入路径前缀判断这个范围；不能仅凭“同仓库”或“同模块”判断，父路径范围内的子模块也不因模块不同就自动被禁止。^[8]

正在绘制图示…

查看图源代码

flowchart LR
    subgraph S["service/：允许导入的父目录树"]
        A["service/api"] -->|允许 import| T["service/internal/token"]
    end
    M["cmd/demo"] -->|允许 import| A
    M -.->|禁止直接 import| T
    O["service 父路径范围外的包"] -.->|禁止直接 import| T

原始尺寸下可横向或纵向滚动；按 Escape 关闭。

正在绘制图示…

查看图源代码

flowchart LR
    subgraph S["service/：允许导入的父目录树"]
        A["service/api"] -->|允许 import| T["service/internal/token"]
    end
    M["cmd/demo"] -->|允许 import| A
    M -.->|禁止直接 import| T
    O["service 父路径范围外的包"] -.->|禁止直接 import| T

token 包中的 Label 可以大写导出，因为同一内部区域里的多个包也要共享它：

// service/internal/token/token.go
package token
func Label() string { return "private implementation" }

// service/api/api.go
package api
import "example.com/packagelab/service/internal/token"
func Label() string { return token.Label() }

cmd/demo 通过公开的 api.Label() 得到：

text

internal private implementation

但 testdata/badinternal 直接导入 token 包时，go build 返回退出码 1：

text

use of internal package example.com/packagelab/service/internal/token not allowed

因此，决定能否导入的不是“大家是否在同一个 Git 仓库”，也不是“有没有使用导出的符号”，而是它们是否处于该 internal 父路径的允许范围。若把 internal 放在模块根目录，通常整个模块里的包都处于允许区域；放在 service/ 下，范围就缩小到这棵子树。^[7:1]

internal 不是安全隔离。 它不会阻止有文件读取权限的人看源码，也不会给运行中的进程加沙箱；调用者仍能从公开 API 得到它有意返回的数据。这条规则适合表达“这里不是稳定的外部 API”，不能用来藏密钥、保护用户数据，或代替权限校验。

init 顺序：先依赖，再变量，最后初始化函数

程序启动阶段并不是按 main.go 的 import 文本从上往下运行。先看包的依赖图，再看每个包内部的初始化。规范保证一个包的依赖先完成初始化，每个包只初始化一次；某包完成自己的包级变量初始化以后，再按顺序运行它的 init 函数。全部包完成初始化后才调用 main.main。^[9]

本例中，cmd/demo 导入 config，而 config 导入 base：

正在绘制图示…

查看图源代码

flowchart LR
    BV["base：包级变量"] --> BI["base：init"]
    BI --> CV["config：按依赖初始化包级变量"]
    CV --> CA["config：a.go 中的 init"]
    CA --> CB["config：b.go 中的 init"]
    CB --> M["main.main"]

原始尺寸下可横向或纵向滚动；按 Escape 关闭。

正在绘制图示…

查看图源代码

flowchart LR
    BV["base：包级变量"] --> BI["base：init"]
    BI --> CV["config：按依赖初始化包级变量"]
    CV --> CA["config：a.go 中的 init"]
    CA --> CB["config：b.go 中的 init"]
    CB --> M["main.main"]

先看 config 的两份文件。mark 只是打印名字，再返回参数值：

// a.go
var A = mark("A", B+base.Value)
var Independent = mark("Independent", 7)
func init() { fmt.Println("config init a") }

// b.go
var B = mark("B", 40)
func init() { fmt.Println("config init b") }

完整主程序的前八行实际输出是：

text

base variable
base init
config variable Independent 7
config variable B 40
config variable A 41
config init a
config init b
main 41 40 7

这里有两处值得慢一点看。

第一，base.Value 和 base.init 先于 config。这是包之间的依赖顺序：config 需要 base，必须等它准备好。

第二，A 虽然写在 Independent 前面，却最后初始化。因为 A 依赖 B，B 尚未准备好；工具链先选声明顺序中第一个已经满足依赖的变量，也就是 Independent，然后是 B，再回到 A。不能把规则简化成“所有变量严格按文件里的行号赋值”。如果变量初始化依赖形成环，也是不合法的。^[9:1]

文件名顺序与语言保证要分开

同一文件里的声明有明确先后。多个文件之间，规范用“文件被交给编译器的顺序”来确定声明顺序，并鼓励构建系统采用文件名的词法顺序，以便复现结果。标准 go 工具通常按这个顺序处理，所以本例的 a.go 在 b.go 前面。^[9:2]^[10]

这不等于应当把业务正确性押在“a.go 的 init 一定早于 b.go”上。改名、换构建方式或加入新的初始化依赖，都可能让代码的隐含假设暴露。需要严格步骤的工作，写成一个显式函数调用更容易看清楚。

多个互不依赖的包也不是随 import 的书写顺序初始化。规范描述的是：对所有包按导入路径排序，每次取第一个尚未初始化、且依赖已经就绪的包。最稳妥的设计仍是只依赖明确的 import 关系，不靠旁支包的副作用碰巧先发生。^[9:3]

init 可以做什么，又会带来什么成本

init 是一种特殊声明：可以在一个包里出现多个，无参数、无返回值，不能作为普通函数调用或取值。包初始化通常在单个 goroutine 中按顺序推进；但 init 自己启动的 goroutine 可以与后续初始化并发运行，不能靠“它是在 init 里启动的”就假定它已经完成。^[9:4]

工作	放在 init 的结果	更容易控制的选择
向包内注册表登记一个实现	导入时自动发生	这种用途可以合理使用 init
连接数据库、读部署配置	仅导入或测试就会触发 I/O，失败没法直接 return error	`New`、`Open` 或显式 `Run` 返回错误
启动后台循环	退出、取消和测试生命周期容易藏起来	由拥有服务生命周期的代码启动并等待结束
按顺序执行多步业务准备	顺序分散到多个文件里	一个显式初始化函数组织步骤

表中的后两列是基于可测试性与错误传播的建议，不是语法禁令。init 本身并不坏，隐藏的副作用才让调用者难以控制。比如 image 解码依赖格式注册，匿名导入 _ "image/png" 就是在明确表达：只需要这个包的初始化副作用，不在当前文件使用它的名字。^[2:2]^[11]

匿名导入仍然是真实依赖，会触发初始化，也不会绕开 internal 或循环导入检查。把普通 import 换成 _ 不能修复错误的依赖方向。

循环依赖为什么不能靠调整 import 顺序解决

假设 a 导入 b，而 b 又导入 a：

// testdata/cycle/a/a.go
package a
import "example.com/packagelab/testdata/cycle/b"
var A = b.B

// testdata/cycle/b/b.go
package b
import "example.com/packagelab/testdata/cycle/a"
var B = a.A

本次构建得到：

text

imports example.com/packagelab/testdata/cycle/b from a.go
imports example.com/packagelab/testdata/cycle/a from b.go: import cycle not allowed

Go 禁止包直接或间接导入自身。问题发生在依赖图上，和 import 语句的排列无关；即使把变量访问换成函数调用，只要两条 import 边还在，环就还在。^[2:3]

处理时先问两个问题：这两个包是否真的拥有独立职责？上层到底需要下层哪一项能力？常见选择如下。

原因	可以怎样调整	代价或边界
两个包总是一起改，边界仅来自文件太大	合并包，继续用多个文件组织	包会变大，但消除了虚假的分层
两边都依赖同一种稳定数据结构	把这小部分放到更基础的包	避免把所有东西塞进 `common`
上层需要存储，下层却反过来依赖上层业务类型	上层声明小接口，在程序入口组装	接口应只覆盖实际使用的能力
双向运行时通知造成双向 import	注入回调或接口	仍需说明调用和退出时机

这是一组设计选择，不是“遇到环一律加接口”。接口适合解决能力依赖，不能替两个职责含混的包自动找到边界。

用一个小接口把服务和存储接起来

本例让 app 只描述自己要的行为：给定 ID，返回名字。它不导入存储实现。

// app/app.go
package app

type Names interface {
    Name(id int) string
}

type Service struct{ repo Names }

func New(repo Names) *Service { return &Service{repo: repo} }
func (s *Service) Greeting(id int) string {
    return "hello " + s.repo.Name(id)
}

存储包只提供同名、同签名的方法，不需要显式声明“实现 app.Names”，也不需要导入 app。接口的结构式实现规则使这条反向依赖可以消失。^[6:1]

// store/store.go
package store

type Memory map[int]string
func (m Memory) Name(id int) string { return m[id] }

最终由 main 同时导入两者并组装：

svc := app.New(store.Memory{1: "Ada"})
fmt.Println(svc.Greeting(1))

实际输出：

text

hello Ada

正在绘制图示…

查看图源代码

flowchart TB
    M["main：选择实现并组装"] --> A["app：使用 Names 接口"]
    M --> S["store：Memory 实现 Name"]
    S -.->|结构上满足，源码无需 import app| I["Names：Name(int) string"]
    A --> I

原始尺寸下可横向或纵向滚动；按 Escape 关闭。

正在绘制图示…

查看图源代码

flowchart TB
    M["main：选择实现并组装"] --> A["app：使用 Names 接口"]
    M --> S["store：Memory 实现 Name"]
    S -.->|结构上满足，源码无需 import app| I["Names：Name(int) string"]
    A --> I

虚线表示满足接口的关系，不是 import。真正的包导入只有 main → app 和 main → store，因此没有环。测试 app 时也可以传一个手写替身，不需要连接外部存储；文末 TestGreeting 就采用了这个办法。本例为了突出依赖关系省略了“ID 不存在”的错误设计，真实业务应在接口里明确未找到、超时等结果，不能照搬成完整仓储接口。

包的边界最后会体现在这类具体动作里：外部只通过承诺的 API 使用它；内部目录限制误用；有副作用的启动工作由清楚的调用链承担；依赖图可以按一个方向展开。目录树画得再整齐，也代替不了这几项检查。

本次验证与适用范围

2026-10-13 在 Go 1.27.2、Linux/amd64 上执行：

检查	结果
`go run ./cmd/demo`	输出与正文一致
`go test -count=1 -v ./...`	`TestGreeting` 通过，其他包成功构建
`go test -count=1 -race ./...`	通过，未报告已执行路径中的数据竞争
`go vet ./...`	通过
越界导入 internal	编译失败，退出码 1
跨包访问小写名字	编译失败，退出码 1
两个包循环导入	编译失败，退出码 1

文件初始化顺序的观察来自标准 go 命令。没有测试其他构建系统；文章没有把本次文件顺序推广成所有编译器必须遵守的文件名字规则。计数器示例也没有实现并发安全，race 通过不能替它增加这项保证。

参考资料

附录：全部项目文件与命令

在一个空目录保存下列文件，再运行：

bash

go version               # 本次为 go1.27.2 linux/amd64
go run ./cmd/demo
go test -count=1 -v ./...
go test -count=1 -race ./...
go vet ./...
# 以下三个命令预期失败：
go build ./testdata/badinternal
go build ./testdata/badexport
go build ./testdata/cycle/a

testdata 不会被普通 ./... 自动当作测试包扫描，因此这些故意失败的例子不影响正向测试。下面列出的每个文件都是复现所需文件，没有省略隐藏初始化代码。

go.mod

module example.com/packagelab

go 1.27

base/base.go

package base

import "fmt"

var Value = initValue()

func initValue() int { fmt.Println("base variable"); return 1 }
func init()          { fmt.Println("base init") }

config/a.go

package config

import (
	"example.com/packagelab/base"
	"fmt"
)

var A = mark("A", B+base.Value)
var Independent = mark("Independent", 7)

func mark(name string, value int) int { fmt.Println("config variable", name, value); return value }
func init()                           { fmt.Println("config init a") }

config/b.go

package config

import "fmt"

var B = mark("B", 40)

func init() { fmt.Println("config init b") }

counter/counter.go

package counter

// Counter's zero value is ready for use. It is not safe for concurrent use.
type Counter struct{ value int }

func (c *Counter) Add(n int) { c.value += n }
func (c Counter) Value() int { return c.value }
func secret() int            { return 99 }

service/internal/token/token.go

package token

func Label() string { return "private implementation" }

service/api/api.go

package api

import "example.com/packagelab/service/internal/token"

func Label() string { return token.Label() }

app/app.go

package app

// Names declares only the capability consumed by Service.
type Names interface{ Name(id int) string }
type Service struct{ repo Names }

func New(repo Names) *Service             { return &Service{repo: repo} }
func (s *Service) Greeting(id int) string { return "hello " + s.repo.Name(id) }

store/store.go

package store

type Memory map[int]string

func (m Memory) Name(id int) string { return m[id] }

cmd/demo/main.go

package main

import (
	"example.com/packagelab/app"
	"example.com/packagelab/config"
	"example.com/packagelab/counter"
	"example.com/packagelab/service/api"
	"example.com/packagelab/store"
	"fmt"
)

func main() {
	fmt.Println("main", config.A, config.B, config.Independent)
	var c counter.Counter
	c.Add(3)
	fmt.Println("counter", c.Value())
	fmt.Println("internal", api.Label())
	svc := app.New(store.Memory{1: "Ada"})
	fmt.Println(svc.Greeting(1))
}

app/app_test.go

package app_test

import (
	"example.com/packagelab/app"
	"testing"
)

type fakeNames struct{}

func (fakeNames) Name(int) string { return "test" }
func TestGreeting(t *testing.T) {
	if got := app.New(fakeNames{}).Greeting(7); got != "hello test" {
		t.Fatal(got)
	}
}

testdata/badinternal/main.go

package main

import "example.com/packagelab/service/internal/token"

func main() { _ = token.Label() }

testdata/badexport/main.go

package main

import "example.com/packagelab/counter"

func main() {
	var c counter.Counter
	_ = c.value
	_ = counter.secret()
}

testdata/cycle/a/a.go

package a

import "example.com/packagelab/testdata/cycle/b"

var A = b.B

testdata/cycle/b/b.go

package b

import "example.com/packagelab/testdata/cycle/a"

var B = a.A

Go Modules Reference：Modules, packages, and versions、Module paths。 ↩︎
Go 规范：Packages、Import declarations、Declarations and scope。 ↩︎ ↩︎ ↩︎ ↩︎
Go 1.27.2 cmd/go：Package lists and patterns、Build constraints、Test packages。 ↩︎
Go 规范：Program execution；Go 官方：Organizing a Go module。 ↩︎
Go 规范：Exported identifiers、Selectors。 ↩︎ ↩︎
Go 规范：Interface types、Method sets。 ↩︎ ↩︎
Go 1.27.2 cmd/go：Internal directories。这是 go 命令施加的导入约束，不是文件系统权限控制。 ↩︎ ↩︎
Go 1.27.2 cmd/go/internal/load 固定源码，disallowInternal 中模块内的包使用 importerPath 与 parentOfInternal 做路径前缀判断。 ↩︎
Go 规范：Package initialization、Program initialization。包含变量依赖、文件呈现顺序、init 以及包初始化的排序规则。 ↩︎ ↩︎ ↩︎ ↩︎ ↩︎
Go 1.27.2 go/build 固定源码，目录项按名称排序后处理；本例通过同版本 go 命令实际验证。 ↩︎
Go 1.27.2 image 包，解码格式注册与匿名导入 image/png 的用法。 ↩︎

Go 包与可见性：让依赖关系能被编译器检查 ​

先分清模块、目录、包名和导入路径 ​

导出看名字，但并不是所有大写名字都能在外面访问 ​

internal 约束的是“谁能导入这个目录” ​

init 顺序：先依赖，再变量，最后初始化函数 ​

文件名顺序与语言保证要分开 ​

init 可以做什么，又会带来什么成本 ​

循环依赖为什么不能靠调整 import 顺序解决 ​

用一个小接口把服务和存储接起来 ​

本次验证与适用范围 ​

参考资料 ​

附录：全部项目文件与命令 ​

go.mod ​

base/base.go ​

config/a.go ​

config/b.go ​

counter/counter.go ​

service/internal/token/token.go ​

service/api/api.go ​

app/app.go ​

store/store.go ​

cmd/demo/main.go ​

app/app_test.go ​

testdata/badinternal/main.go ​

testdata/badexport/main.go ​

testdata/cycle/a/a.go ​

testdata/cycle/b/b.go ​

Go 包与可见性：让依赖关系能被编译器检查

先分清模块、目录、包名和导入路径

导出看名字，但并不是所有大写名字都能在外面访问

internal 约束的是“谁能导入这个目录”

init 顺序：先依赖，再变量，最后初始化函数

文件名顺序与语言保证要分开

init 可以做什么，又会带来什么成本

循环依赖为什么不能靠调整 import 顺序解决

用一个小接口把服务和存储接起来

本次验证与适用范围

参考资料

附录：全部项目文件与命令

go.mod

base/base.go

config/a.go

config/b.go

counter/counter.go

service/internal/token/token.go

service/api/api.go

app/app.go

store/store.go

cmd/demo/main.go

app/app_test.go

testdata/badinternal/main.go

testdata/badexport/main.go

testdata/cycle/a/a.go

testdata/cycle/b/b.go