[!info] 关联笔记

• 所属 MOC：语言基础 · 学习路线
• 前置：Go、安装与第一程序
• 后续：包与可见性、Modules、函数
• 相关：设计哲学

Go 程序结构

这个概念为什么会出现

从其他语言转入 Go 时，常见困惑是：

• 为什么没有“一个文件一个 public class”？
• package main 和普通包差在哪？
• 同目录多个 .go 如何变成一个包？
• init 什么时候跑？

程序结构回答：源码如何被组织成可编译、可导入、可执行的单元。

[!abstract] 一句话理解 Go 以 package 为编译与可见性边界；文件通过 package/import/顶层声明组成包，可执行程序从 package main 的 main.main 进入。

最小可运行示例

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

场景：CLI 健康检查小工具的最小骨架

运维要一个本地命令：跑起来打印一句“服务就绪”探针文案。
这就是最小可执行 Go 程序：package main + import + func main。
真实项目会在 main 里解析 flag、读配置、起 HTTP；教学上先把骨架钉死。

package main

// fmt 是标准库格式化 I/O 包；未使用的 import 是编译错误。
import "fmt"

// main 是可执行程序入口：进程从这里开始，返回后默认以 0 退出。
// 业务意图：打印一条“就绪”探针，证明程序结构已跑通。
// 教学点：只有 package main 里的 func main 才是可执行入口。
func main() {
	fmt.Println("healthz: ok")
}

建议运行：

go run .

期望输出：

healthz: ok

结合场景再看三个关注点

1. 四层骨架齐了就能跑
   package → import → 顶层声明（这里是 main）→ 入口函数。

2. package main 才出二进制
   健康检查 CLI 必须是 main 包；库包不能当入口直接 go run 出同样语义。

3. go run . 以包为单位
   同目录多个 .go 只要同属 package main，会一起编进这一次运行。

核心概念

四层骨架

1. package 子句（每个文件第一行有效代码）
2. import 声明
3. 顶层声明：const / var / type / func
4. 入口：仅 package main 中的 func main()

参考：How to Write Go Code

package main vs 库包

	package main	其他包名
产物	可执行文件	库（被导入）
入口	需要 main	无 main 要求
导入	通常不被别人 import	按模块路径导入

main 是函数名约定，不是关键字；但可执行入口必须是 main 包中的 main 函数。

目录与包

• 同一目录下同一 package 名的文件共同构成一个包
• 导入路径由 module + 目录决定，不是文件名
• 测试文件 *_test.go 可同包或 package foo_test 黑盒测试

初始化顺序

规范：Program initialization and execution

1. 导入依赖按序初始化
2. 当前包级变量初始化
3. 当前包所有 init
4. main.main

init 可有多个，同文件按出现顺序；跨文件顺序依赖实现/构建细节，不要依赖跨文件 init 次序做关键逻辑。

import 形态

import (
    "fmt"
    "net/http"
    crand "crypto/rand" // 别名
    _ "image/png"       // 副作用导入
)

未使用的导入是编译错误（goimports 可整理）。

设计动机

• 包是边界：编译、依赖、导出（大写）一体
• 少仪式：无强制类包裹
• 工具友好：go build/go test 以包为单元

边界与反直觉

1. 同目录不能混两个 package 名（测试例外）。
2. init 无法显式调用；难测、难控，应克制。
3. 循环导入非法。
4. main 返回后程序结束（退出码默认 0；可用 os.Exit）。
5. 文件名不是类型名；组织靠包与标识符。

常见误区

[!warning] 常见误区：一个文件必须一个类型 Go 按包组织，文件是阅读切片。

[!warning] 常见误区：在 init 里读配置连数据库 使测试与生命周期变脆；应显式 main/wire 组装。

[!warning] 常见误区：用文件名当导入路径 导入的是包路径，不是 foo.go。

工程实践

1. 包名短而有意义，避免 util 万能包
2. main 包保持瘦：解析旗标、组装依赖、运行
3. 业务逻辑放可测试库包
4. 慎用 init 与空白导入（驱动注册等少数场景）
5. 用 gofmt/go vet 保持结构一致

可验证实验

1. 同目录拆两个文件同属 package main，共享函数。
2. 写库包并被 main 导入。
3. 故意循环导入，观察编译错误。
4. 在 init 打印，观察早于 main。

本节总结

• 本质：package 边界 + 声明 + 入口。
• 关键：同目录成包、初始化顺序、main 约定、init 克制。
• 下一步：go-packages-and-visibility 与 go-modules。

自测题

概念题

1. 可执行程序的 package 名必须是什么？
2. 同包多文件能否互相调用未导出标识符？
3. 为何避免复杂 init？

代码推理题

仅有 package main 与 func init(){} 而无 main，go build 如何？

工程思考题

CLI 项目如何划分 main、internal/app、internal/config？

参考答案

展开

1. main。
2. 能，未导出是包级私有不是文件私有。
3. 隐式、难测、顺序脆弱。
   无 main 的 main 包不能生成可执行入口（编译/链接失败）。
   工程：main 只组装；app 含业务；config 加载显式调用。

延伸阅读

资料	支撑
How to Write Go Code	组织方式
Spec — Packages	包规则
Spec — Program initialization	启动顺序
Package names blog	命名

---

笔记元信息

• 文件名：go-program-structure.md
• 状态：已深化