[!info] 关联笔记

• 所属 MOC：语言基础 · 工具链与工程结构 · 学习路线
• 前置概念：程序结构
• 后续概念：Modules、项目布局
• 类型侧：接口、struct 与方法

Go 包、导入与可见性

这个概念为什么会出现

代码稍大就要回答：

1. 文件如何分组编译？
2. 谁能依赖谁？
3. 哪些名字构成对外 API，哪些是实现细节？

许多语言用 public/private/protected 与命名空间层级。Go 把答案压成更少概念：

• 包（package）：标识符作用域与编译单元的基本边界
• 导入（import）：显式依赖
• 导出（exported）：标识符首字母大写则对包外可见

再配合 modules 的导入路径（见 Modules）与 internal 目录约定，形成从语言到工程的封装体系。

[!abstract] 一句话理解 同一目录同一包名共享所有未导出名字；包外只能看到首字母大写的标识符；import 路径由模块路径 + 目录决定，与包名相关但不相等。

最小可运行示例

先把示例放进业务场景，再看代码：

场景：用户中心包对外暴露资料 API

账号服务把“用户资料”拆成独立包 user：

• 对外：构造函数 NewProfile、字段 Name
• 对内：年龄 age、名字规范化 normalize

HTTP handler（main）只能走导出 API，不能直接摸内部实现。

下面两段是同模块里两个文件的示意；真实仓库中 user/profile.go 与根目录 main.go 分属不同目录。
若只粘贴单文件运行，可先把逻辑缩进同一 main 包理解导出规则，再拆目录。

// 文件：user/profile.go
package user

import "strings"

// Profile 是对外资料模型。
// 业务意图：包外能读展示名，但不能直接改内部年龄。
// 教学点：类型名大写 = 导出；字段级也各自决定是否导出。
type Profile struct {
	Name string // 导出字段：user.Profile{}.Name 包外可读可写
	age  int    // 未导出字段：包外写 p.age 会编译失败
}

// NewProfile 是导出构造函数：唯一推荐的创建入口。
// 业务意图：创建时统一做 trim，避免前后空格脏数据进库。
func NewProfile(name string) Profile {
	// 包内可调用未导出的 normalize。
	return Profile{Name: normalize(name), age: 0}
}

// normalize 未导出：实现细节，包外不可见。
// 教学点：首字母小写 = 仅同包可见（同目录其他文件也算同包）。
func normalize(name string) string {
	return strings.TrimSpace(name)
}

// 文件：main.go（可执行入口，依赖 user 包）
package main

import (
	"fmt"

	// 导入路径 = 模块路径 + 目录；默认限定符是包名 user。
	"example.com/app/user"
)

func main() {
	// 业务：注册页提交了带空格的昵称，交给 user 包规范化。
	p := user.NewProfile("  Ada  ")
	fmt.Println(p.Name) // Ada
	// p.age = 1          // 编译错误：age 未导出
	// user.normalize("x") // 编译错误：normalize 未导出
}

建议运行（在已 go mod init example.com/app 且存在 user/profile.go 的模块根）：

go run .

期望输出：

Ada

结合场景再看三个关注点

1. 导出是标识符级，不是文件级
   同一 profile.go 里既有导出的 Profile/NewProfile，也有私有的 age/normalize。

2. 导入路径 ≠ 包名，但常相关
   路径末段是目录 user，源码里 package user 决定默认限定符 user.XXX。

3. 未导出字段仍可间接使用
   年龄可以以后加包内方法 Birthday() 修改；包外永远只能走你愿意公开的 API。

核心概念与准确模型

包声明

每个 Go 源文件以：

package name

规则：

1. 同一目录下的 .go 文件通常属于同一包，且 package 名应一致（测试文件 package foo_test 是刻意例外）。
2. 包名宜短、小写、无下划线；不与导入路径强制相同，但常取路径最后一段。
3. package main 表示可构建可执行程序的包；需有 func main()。
4. 包是声明的作用域：同包多文件直接共享私有类型与函数，无需 forward declare。

编译单元与文件

• 工具以包为单位类型检查与编译。
• 文件切分是组织手段，不是可见性边界。
• _test.go：
  • package foo：白盒测试，可访问未导出符号。
  • package foo_test：黑盒测试，仅导出 API（外部测试包）。

导入声明

import "fmt"
import "example.com/app/user"

import (
	"fmt"
	"example.com/app/user"
)

import (
	u "example.com/app/user" // 别名
	_ "example.com/app/driver/mysql" // 只跑 init 副作用
	. "legacy" // 点导入：把导出名注入当前文件，罕用
)

要点：

1. 导入路径是字符串，来自模块系统解析，不是随意文件系统相对路径（replace 除外，见 modules）。
2. 默认限定符是包名（package 子句），不一定等于路径最后一段。
3. 导入后必须使用（否则编译错误），_ 导入除外。
4. 循环导入非法：A import B 且 B import A（直接或间接）会失败。

导出规则（可见性）

语言规则极简：

标识符	包外可见
Name 首字母大写（Unicode 大写）	是
name 首字母小写	否

适用于：类型、函数、变量、常量、结构体字段、方法名、接口方法名等。

推论：

1. 未导出类型的方法即使大写，包外也难以直接持有该类型（仍可能通过导出接口暴露行为）。
2. 导出接口的方法名必须导出（接口要在包外可实现/可调用时尤其重要）。
3. 字段未导出时，包外字面量不能直接初始化该字段；常用构造函数。
4. 可导出与否是编译期强制，不是运行时权限。

合格标识与选择器

fmt.Println
user.NewProfile
p.Name

包外通过 pkg.Name 访问导出符号。同包内直接 Name / name。

init 函数

func init() { /* 包初始化 */ }

• 可有多个 init。
• 不能被直接调用。
• 导入依赖先初始化。
• 滥用 init 做复杂逻辑会让依赖隐式化；优先显式 New。

internal 目录约定

工具强制：

.../internal/...

仅允许 internal 的父目录树内的代码导入该 internal 包。用于模块内“准私有”子系统，比单靠小写标识符更大粒度。

包文档与 Godoc

• 包注释写在 package 子句前。
• 导出符号注释以名称开头，供 pkg.go.dev / go doc 展示。
• 好的包名是文档的一部分：http、json、user 比 util 更可导航。

设计动机

1. 少概念的封装
   无 public/private 关键字表，阅读 diff 时首字母即 API 信号。
2. 显式依赖
   每个文件 import 列表即耦合声明。
3. 目录即边界
   包与文件系统对齐，降低“同名不同包”的散乱（仍可能有同包名不同路径）。
4. 可执行与库统一
   只是 main 与否的区别。

边界情况与反直觉行为

1. 包名 ≠ 导入路径

import "github.com/shopspring/decimal"
// package decimal → decimal.NewFromInt

路径末段常相同，但以 package 子句为准；冲突时用别名。

2. 主模块内相对导入不推荐

现代 modules 下用完整模块路径导入，不用 import "./foo" 风格老路径。

3. 导出字段被 encoding/json 等反射使用

json 默认只看到导出字段。未导出字段不会被标准 encoding 包含（除非自定义）。

4. 嵌入与导出

嵌入未导出类型时，其导出方法的提升规则需查规范；设计上避免用嵌入“偷偷扩大 API”。

5. 测试包 foo_test 的导入

黑盒测试必须导入被测包，只能测导出行为——这是刻意的 API 纪律。

6. main 与 TestMain 等

package main 的库测试、插件等场景有特殊构建模式；日常服务把 main 做薄，逻辑放可导入包。

7. 大小写与 Unicode

导出判定基于 Unicode 大写字母，不限于 ASCII A-Z，但生态几乎全用 ASCII 导出标识符。

常见误区

[!warning] 常见误区：以为“一个文件一个包” 错误：把可见性当成文件私有。
正确：目录/包才是边界；同包文件共享私有名。

[!warning] 常见误区：包名起 util/common/misc 错误：垃圾桶包，循环依赖温床。
正确：按领域能力命名：auth、billing、httpmw。

[!warning] 常见误区：导出一切“以后可能有用” 错误：放大 API 兼容面。
正确：默认未导出；需要时再导出并写文档/测试。

[!warning] 常见误区：用点导入消除前缀 错误：import . "fmt" 污染命名空间。
正确：仅测试等极少数场景。

[!warning] 常见误区：混淆 package 名与模块路径 错误：import "user" 期望自动解析本地目录。
正确：import "example.com/app/user"（你的 module path + 子目录）。

与相邻概念对比

概念	差异
Modules	版本与依赖图；包是其内的编译单元
接口	跨包抽象常依赖导出方法集
项目布局	cmd/、internal/ 是工程约定，建立在包规则之上
文件名	组织手段；非可见性

工程实践

1. 一个目录一个包（除 _test 外部测试包）。
2. 包名简短有意义，避免与标准库冲突（本地别名可解）。
3. internal/ 放不对外承诺的代码。
4. cmd/<app>/main.go 只做组装，业务在可测试包中。
5. 构造函数 NewXxx 隐藏未导出字段与不变量。
6. 导入分组：标准库 / 第三方 / 本模块，中间空行（gofmt/goimports）。
7. 避免循环依赖：用接口倒置、挪动类型到更基础包、或合并包。
8. API 审查看导出符号列表：go doc / pkg.go.dev。
9. 不要为“层次”建过多小包导致 import 噪音与循环；也不要单包巨型。

// 导出接口 + 未导出实现，是常见稳定 API 形状
type Store interface {
	Get(ctx context.Context, id string) (Item, error)
}

type pgStore struct{ db *sql.DB }

func NewStore(db *sql.DB) Store { return &pgStore{db: db} }

可验证实验

实验 1：导出字段

定义导出/未导出字段，从 main 访问，观察编译错误。

实验 2：同包多文件

a.go 未导出函数，b.go 调用，确认可编译。

实验 3：外部测试包

foo_test 调用未导出函数，确认失败。

实验 4：循环导入

两包互相 import，阅读编译器错误。

实验 5：internal

在模块外路径尝试 import internal 包，确认被拒绝。

本节总结

• 包是 Go 的封装与编译边界；目录承载包。
• 导入路径由 module + 目录决定；包名决定默认限定符。
• 首字母大小写即导出规则。
• internal 提供目录级强制隐私。
• 下一步：Modules 管理包从何而来与版本如何选。

自测题

概念题

1. 为什么同目录两个文件能共用未导出函数？
2. 导入路径最后一段一定是包名吗？
3. internal 解决了小写标识符解决不了的什么问题？

代码推理题

package counters

type counter struct{ n int }

func New() *counter { return &counter{} }

func (c *counter) Inc() { c.n++ }

func (c *counter) N() int { return c.n }

其他包能否写 counters.New().Inc()？*counter 出现在导出函数签名中有何争议？

工程思考题

团队把所有 DTO、工具函数塞进 package common，出现循环依赖。如何按包规则拆？

参考答案

展开

1. 可见性以包为单位，文件只是包的一部分。
2. 不一定；以源文件 package 子句为准，路径末段只是惯例。
3. 跨目录、模块内子系统级强制不可被外部导入，而不仅是标识符隐藏。
   代码题：可以调用导出方法；但返回未导出类型 *counter 作为 API 不理想——调用方难以在签名中写出该类型，应导出 Counter 类型或接口。
   工程题：按领域拆 user/order/money 等；共享类型下沉到无反向依赖的基础包；用接口在边界解耦；慎用 common。

延伸阅读与资料来源

资料	类型	支撑
Spec — Packages	规范	包声明与组织
Spec — Exported identifiers	规范	导出规则
Spec — Import declarations	规范	import 形态
How to Write Go Code	官方文档	包、路径、工作区基础
Package names	官方博客	命名实践
Go Modules Reference	参考	导入路径解析与 internal

---

笔记元信息

• 建议文件名：go-packages-and-visibility.md
• 所属阶段：阶段一末 / 工具链衔接
• 学习顺序：程序结构之后，modules 之前
• 建议下一篇：Go Modules
• 本篇状态：已深化（导出、import、internal 与包设计）