2.Go 程序结构

1. 包声明决定“这个文件属于谁”#

Go 不是以“类”为组织中心，而是以“包”为组织中心。每个 .go 文件都必须以包声明开头：

1
package main

这行代码的含义不是“这是主程序”，而是“这个文件属于 main 包”。只有当一个包名叫 main 时，它才有资格被构建成可执行程序。

根据 Go 规范，一个源文件的基本组织顺序是：

1. package 子句
2. import 声明
3. 顶层声明：const、var、type、func

也就是说，包声明不是装饰语法，而是整个文件归属关系的起点。

图意：这张图具体说明 package 子句、import 声明 和 顶层 func/type/var/const 如何自上而下分层，重点看最上层先定义文件归属、第二层再定义外部依赖，最后理解 Go 源文件不是自由排布，而是有固定结构顺序。

同一目录下的文件为什么通常要同包#

一个包通常由同一目录下的多个 .go 文件共同组成。这些文件如果属于同一个包，就能直接共享同包内的顶层标识符，不需要彼此导入。

例如同目录下：

• main.go
• helper.go

都写成：

1
package main

那么它们会被看作同一个包的不同文件。

2. main 函数决定“程序从哪开始执行”#

func main() 是可执行程序的入口函数，但它只有放在 package main 中才有意义。

1
func main() {
2
  // 程序入口
3
}

这里有两个约束必须同时成立：

• 包名必须是 main
• 入口函数必须是 main，且签名固定为无参数、无返回值

也就是说，下面两者缺一不可：

1
package main
2

3
func main() {
4
}

如果你只是写了一个普通包：

1
package utils

即使里面定义了 func main()，它也不是程序入口，因为整个包不是 main 包。

表面语法 vs 实际角色#

表面上看，main 只是一个函数名；但在程序构建阶段，它承担的是“入口约定”的角色。Go 工具链在构建可执行程序时，会寻找 package main 中的 main.main 作为程序入口。

这意味着：

• main 不是普通业务函数名
• 它是 Go 可执行程序的协议入口

3. import 解决的是“当前文件依赖谁”#

import 声明的是当前源文件对其他包的依赖关系。例如：

1
import "fmt"

表示当前文件要使用 fmt 包的导出能力。

如果要导入多个包，通常写成分组形式：

1
import (
2
  "fmt"
3
  "os"
4
)

这里要注意两个关键点：

import 是按文件生效，不是按整个包自动共享#

虽然多个文件可以属于同一个包，但 import 是文件级声明。也就是说：

• a.go 导入了 fmt
• b.go 不能自动使用 fmt
• b.go 自己也要写 import "fmt"

这很容易和“同包共享标识符”混淆。共享的是同包定义的顶层名字，不是导入列表。

导入的是包路径，使用的是包名#

1
import "fmt"

这里写的是导入路径；真正使用时写的是包名：

1
fmt.Println("hello")

默认情况下，访问方式是：

1
包名.导出标识符

例如：

• fmt.Println
• os.Args

4. 为什么 Go 强调“未使用的导入”直接报错#

Go 对 import 很严格：导入了却不用，会编译失败。

例如：

1
import "fmt"
2

3
func main() {
4
}

这会报未使用导入错误。原因不是语法洁癖，而是 Go 希望依赖关系始终精确，避免：

• 无意义依赖残留
• 重构后垃圾导入堆积
• 阅读时误判当前文件真正依赖什么

所以 import 在 Go 里不只是“引入能力”，也是“声明当前文件真实依赖边界”。

图意：这张图具体说明 package main、func main() 和 import "fmt" 如何共同组成可执行程序，重点看左侧 import 提供外部能力、中间 main 函数作为入口调用，最后理解只有包归属和入口函数同时满足约定时，程序才能被直接运行。

5. 基本注释不只是说明文字，还有文档语义#

Go 支持两种注释：

1
// 行注释
2

3
/* 块注释 */

实际开发里最常用的是 // 行注释。

普通注释#

普通注释用于解释局部逻辑：

1
// 打印欢迎语
2
fmt.Println("hello")

它的作用是帮助人理解代码，不参与程序执行。

文档注释#

如果注释紧贴在包、函数、类型、变量、常量声明前，并且中间没有空行，那么它会被当作文档注释处理。

例如：

1
// main 是程序入口。
2
func main() {
3
  fmt.Println("hello")
4
}

这类注释不仅给人看，也会被 go doc、pkg.go.dev 这类文档工具提取。

基本注释的实践边界#

• 注释应该解释“为什么”或“这段代码在做什么”
• 不要把代码本身重复翻译一遍
• 导出的标识符通常应有文档注释
• 学习阶段的 main 程序虽然不强制，但最好养成习惯

1. 把包声明写错，导致程序不能作为可执行文件运行#

错误示例：

1
package hello
2

3
import "fmt"
4

5
func main() {
6
  fmt.Println("Hello")
7
}

问题在于：虽然存在 main 函数，但包不是 main，所以它不是可执行程序入口包。

正确写法：

1
package main

2. main 函数签名写错#

错误示例：

1
func main(args []string) {
2
}

或：

1
func main() int {
2
  return 0
3
}

main 函数不能带参数，也不能有返回值。Go 的入口函数签名是固定约定，不是可自定义接口。

3. 导入了包但没有使用#

错误示例：

1
package main
2

3
import "fmt"
4

5
func main() {
6
}

这会直接编译报错。Go 不允许“先导进来以后再说”。

正确做法：

• 要么真正使用 fmt
• 要么删除无用导入

4. 误以为同包文件的 import 可以共用#

例如 main.go 导入了 fmt，other.go 没导入却直接写：

1
fmt.Println("x")

这不行。import 是文件级的，不会因为“同包”而自动共享。

5. 注释只重复代码表面含义#

低质量注释：

1
// 调用 Println 打印字符串
2
fmt.Println("Hello")

这种注释价值很低，因为代码本身已经表达得很清楚了。更合适的是解释意图，例如：

1
// 输出启动提示，确认程序已正常运行
2
fmt.Println("Hello")

1. Go 用“包”而不是“文件”作为复用单元#

好处：

• 代码组织简单
• 同包内多个文件天然协作
• 易于形成稳定模块边界

代价：

• 初学者容易混淆“文件作用域”和“包作用域”
• 容易误判 import 是否共享

2. main 入口签名固定，降低灵活性但提升一致性#

好处：

• 工具链约定清晰
• 程序入口一眼可见
• 构建和运行模型简单

代价：

• 入口参数和返回值不能自定义
• 初始化逻辑需要通过 os.Args、配置文件、环境变量等方式获取外部输入

3. 强制清理未使用导入，牺牲一点宽松性换取依赖整洁#

好处：

• 文件依赖边界精确
• 重构后更少残留垃圾
• 代码审查更容易判断真实依赖

代价：

• 写代码过程中临时导入包会立刻触发编译错误
• 对初学者来说会觉得“太严格”

4. 注释在 Go 里兼具“说明”和“文档生成”双重角色#

好处：

• 文档和源码更接近
• go doc、pkg.go.dev 能直接利用源码注释
• 鼓励开发者写结构化说明

代价：

• 注释质量差时，自动生成文档也会一起变差
• 如果把注释当废话区，会降低整体可读性

1. 为什么 Go 可执行程序一定要写 package main#

因为 Go 工具链会把 main 包视为可执行程序入口包。只有 package main 中的 main.main 才会被当作程序入口处理。

2. func main() 可以带参数或返回值吗#

不可以。Go 入口函数签名固定为无参数、无返回值。命令行参数通常通过 os.Args 获取，退出码通常通过 os.Exit 控制。

3. import 是包级共享还是文件级生效#

是文件级生效。即使两个 .go 文件属于同一个包，它们的 import 列表也互不共享，每个文件都要声明自己用到的外部包。

4. 为什么 Go 不允许未使用的导入#

因为 Go 把 import 视为真实依赖声明。未使用导入通常意味着残留代码、错误重构或依赖边界不清，直接报错能保持代码整洁。

5. 普通注释和文档注释的区别是什么#

普通注释只是给人看；文档注释是紧贴顶层声明的注释，会被 go doc、pkg.go.dev 等工具提取，成为正式文档的一部分。