Go 从 0 到精通 · 第 18 课：包与模块管理

学习定位：这是整套 Go 教程的第 18 课，也是阶段三（核心抽象阶段）的最后一课。
前置要求：已经完成第 17 课，掌握了 defer、panic、recover 的使用。
本课目标：掌握 Go 项目的代码组织方式，理解包（package）、导出规则、模块（module）和依赖管理，能组织多文件、多包项目。

1. 本课你要解决的核心问题

到目前为止，你写的程序都在一个 main.go 文件里。但真实项目不可能只有一个文件——代码需要组织成多个包，每个包负责一个职责。

你需要搞明白以下问题：

  • 包是什么，怎么组织
  • 怎么控制哪些标识符对外可见
  • 模块是什么，go.mod 做什么
  • 怎么导入和管理第三方依赖
  • 项目目录结构怎么组织

学完这一课，你就能组织多文件、多包项目了，阶段三也就完成了。

2. 包（package）

2.1 什么是包

包是 Go 中代码组织的基本单位。每个 .go 文件必须属于一个包：

1
package mathutil  // 文件的第一行声明包名

同一个目录下的所有 .go 文件必须属于同一个包（main 包除外）。

2.2 main 包和 main 函数

1
2
3
4
5
6
7
package main

import "fmt"

func main() {
    fmt.Println("Hello, Go!")
}
  • package main：特殊的包名，表示这是一个可执行程序
  • func main()：程序入口函数
  • 不是 main 包的代码不能直接运行，只能被其他包导入使用

2.3 包名约定

  • 包名用小写单词，不用下划线或驼峰：strings、http、json
  • 包名和目录名通常一致，但不强制

3. 导出规则

3.1 首字母大写 = 导出

Go 用标识符的首字母大小写来控制可见性：

  • 首字母大写：导出（exported），可以被其他包访问
  • 首字母小写：未导出（unexported），只能在当前包内访问
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
package mathutil

var Pi = 3.14159       // 导出：其他包可以访问 mathutil.Pi
var version = "1.0"    // 未导出：只能在 mathutil 包内访问

func Add(a, b int) int {     // 导出
    return a + b
}

func subtract(a, b int) int { // 未导出
    return a - b
}

type Point struct {    // 导出
    X float64          // 导出字段
    Y float64          // 导出字段
    label string       // 未导出字段
}

3.2 导出规则适用于

  • 函数
  • 类型
  • 变量
  • 常量
  • 结构体字段
  • 接口方法

4. 导入包

4.1 基本语法

1
2
3
import "fmt"
import "strings"
import "encoding/json"

4.2 使用导入的包

1
2
3
4
5
6
import "strings"

func main() {
    s := strings.ToUpper("hello")  // 包名.函数名
    fmt.Println(s)
}

4.3 多行导入

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

用圆括号包裹多个导入语句，每个占一行。

4.4 别名导入

1
2
3
4
5
import (
    str "strings"       // 用 str 代替 strings
    . "fmt"             // 点导入：可以直接用 Println，不需要 fmt. 前缀
    _ "image/png"       // 空导入：只执行包的 init()，不直接使用
)
  • 别名：包名太长或冲突时使用
  • 点导入：不推荐，降低可读性
  • 空导入：用于注册副作用（如数据库驱动、图片格式）

4.5 自定义包的导入路径

假设你的项目模块路径是 github.com/user/myproject，目录结构如下：

1
2
3
4
5
myproject/
├── go.mod
├── main.go
└── mathutil/
    └── calc.go

在 main.go 中导入：

1
import "github.com/user/myproject/mathutil"

5. 模块（module）和 go.mod

5.1 什么是模块

模块是 Go 的依赖管理单位。一个模块由一个 go.mod 文件定义，包含：

  • 模块路径（唯一标识）
  • Go 版本要求
  • 依赖列表

5.2 创建模块

1
go mod init github.com/user/myproject

这会生成 go.mod 文件：

1
2
3
module github.com/user/myproject

go 1.21

5.3 go.mod 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
module github.com/user/myproject

go 1.21

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/go-sql-driver/mysql v1.7.1
)

require (
    github.com/bytedance/sonic v1.9.1 // indirect
    // ... 间接依赖
)
  • module：模块路径
  • go：最低 Go 版本
  • require：直接和间接依赖

5.4 go.sum 文件

go.sum 记录每个依赖的哈希值，确保下载的依赖没有被篡改。不需要手动管理。

5.5 常用模块命令

1
2
3
4
go mod init <module-path>   # 初始化模块
go mod tidy                 # 添加缺失的依赖，移除未使用的依赖
go mod download             # 下载依赖
go mod graph                # 查看依赖图

6. 导入第三方包

6.1 添加依赖

不需要手动编辑 go.mod。直接在代码中 import，然后运行：

1
go mod tidy

Go 会自动下载依赖并更新 go.mod 和 go.sum。

6.2 使用第三方包

1
2
3
4
5
6
7
8
9
10
11
12
13
14
package main

import (
    "fmt"
    "github.com/gin-gonic/gin"
)

func main() {
    r := gin.Default()
    r.GET("/ping", func(c *gin.Context) {
        c.JSON(200, gin.H{"message": "pong"})
    })
    r.Run(":8080")
}

6.3 Go Proxy（国内加速）

在中国大陆，建议配置 Go 代理：

1
go env -w GOPROXY=https://goproxy.cn,direct

7. 包的初始化

7.1 init 函数

每个包可以定义 init 函数，在包被导入时自动执行：

1
2
3
4
5
6
7
8
9
10
package config

import "fmt"

var DBHost string

func init() {
    fmt.Println("config 包初始化")
    DBHost = "localhost"
}

init 函数：

  • 没有参数，没有返回值
  • 不能被显式调用
  • 在 main 函数之前执行
  • 同一个包中可以有多个 init，按源文件顺序执行

7.2 初始化顺序

1
2
3
1. 包级变量初始化
2. init() 函数执行
3. （如果是 main 包）main() 函数执行

依赖的包先初始化，被依赖的包后初始化。

8. 项目目录结构

8.1 小型项目

1
2
3
4
5
6
7
8
9
myproject/
├── go.mod
├── main.go
├── config/
│   └── config.go
├── models/
│   └── user.go
└── utils/
    └── string.go

8.2 中型项目（常见布局）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
myproject/
├── go.mod
├── main.go
├── cmd/              # 命令行入口
│   └── server/
│       └── main.go
├── internal/         # 仅内部使用，不可被外部导入
│   ├── handler/
│   ├── service/
│   └── repository/
├── pkg/              # 可被外部使用的公共库
│   ├── logger/
│   └── config/
├── configs/          # 配置文件
├── docs/             # 文档
└── scripts/          # 脚本

8.3 internal 目录的特殊含义

internal 目录下的包只能被父目录及其子目录的代码导入。这是 Go 的一个约定，用于隐藏内部实现：

1
2
3
4
5
6
7
myproject/
├── internal/
│   └── secret/       # 只有 myproject 的代码能导入
│       └── util.go
└── pkg/
    └── public/       # 任何人都能导入
        └── util.go

9. 一段综合示例

假设我们在做一个简单的用户管理项目：

目录结构：

1
2
3
4
5
6
7
userapp/
├── go.mod
├── main.go
├── models/
│   └── user.go
└── utils/
    └── validator.go

go.mod：

1
2
3
module userapp

go 1.21

models/user.go：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
package models

import "fmt"

// User 导出类型
type User struct {
    Name  string
    Email string
    Age   int
}

// String 导出方法
func (u User) String() string {
    return fmt.Sprintf("%s (%s, %d岁)", u.Name, u.Email, u.Age)
}

utils/validator.go：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
package utils

import "strings"

// ValidateEmail 导出函数
func ValidateEmail(email string) bool {
    return strings.Contains(email, "@")
}

// validateAge 未导出函数
func validateAge(age int) bool {
    return age > 0 && age < 150
}

// ValidateUser 导出函数，内部调用未导出函数
func ValidateUser(name string, email string, age int) []string {
    var errors []string

    if name == "" {
        errors = append(errors, "姓名不能为空")
    }
    if !ValidateEmail(email) {
        errors = append(errors, "邮箱格式不正确")
    }
    if !validateAge(age) {
        errors = append(errors, "年龄不合理")
    }

    return errors
}

main.go：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
package main

import (
    "fmt"
    "userapp/models"
    "userapp/utils"
)

func main() {
    // 创建用户
    u := models.User{
        Name:  "小明",
        Email: "xiaoming@example.com",
        Age:   20,
    }

    // 验证用户
    errs := utils.ValidateUser(u.Name, u.Email, u.Age)
    if len(errs) > 0 {
        fmt.Println("验证失败：")
        for _, e := range errs {
            fmt.Println("  -", e)
        }
        return
    }

    fmt.Println("用户信息：", u)
}

输出：

1
用户信息： 小明 (xiaoming@example.com, 20岁)

10. 常见坑总结

10.1 循环导入

1
2
3
// a 包导入 b
// b 包导入 a
// → 编译错误：import cycle not allowed

Go 不允许包之间循环导入。解决方法：提取公共逻辑到第三个包。

10.2 包名和目录名不同

1
2
// 目录：myutils/
// 文件头部：package util  ← 不一致

虽然允许，但建议包名和目录名保持一致。

10.3 同一目录下多个包

1
2
3
// 同一目录下有两个文件：
// a.go: package a    ← 错误！
// b.go: package b    ← 错误！

同一个目录下的所有文件必须属于同一个包（测试文件除外）。

10.4 忘记 go mod tidy

在 import 了新的第三方包后，需要运行 go mod tidy 来更新依赖。

10.5 未导出的标识符在包外不可访问

1
2
3
4
5
// utils 包中
func helper() {}  // 未导出

// main 包中
utils.helper()  // 编译错误：undefined

需要对外使用就首字母大写。

10.6 internal 目录误用

internal 下的包不能被外部项目导入。如果你希望某些包不被外部使用，放到 internal 下。

11. 阶段三完成回顾

到这里，你已经完成了阶段三：核心抽象阶段的全部 5 课内容。

回顾一下你现在的能力：

课次 主题 你获得的能力
第 14 课 接口 interface 理解鸭子类型，能定义和实现接口
第 15 课 组合优于继承 用嵌入实现组合，接口 + 组合设计
第 16 课 错误处理 error 创建、返回、包装、检查错误
第 17 课 defer/panic/recover 资源释放，异常流程控制
第 18 课 包与模块管理 组织多文件、多包项目

你现在已经具备了用 Go 抽象和组织中大型程序的完整能力。接下来我们进入阶段四：标准库与实战阶段，开始学习文件操作、时间处理、JSON 等实用技能。

12. 本课练习

练习 1：创建多文件项目

要求：

  • 创建一个 Go 模块
  • 用 go mod init 初始化
  • 编写两个 .go 文件，属于同一个包
  • 验证能正常编译运行

练习 2：多包项目

要求：

  • 创建一个项目，包含 main 包和 mathutil 包
  • mathutil 包导出 Add、Subtract 函数
  • main 包导入并使用

练习 3：导出规则

要求：

  • 创建一个包，包含导出和未导出的类型、函数、字段
  • 在另一个包中尝试访问，验证编译结果

练习 4：第三方依赖

要求：

  • 创建一个项目，导入一个第三方包（如 github.com/fatih/color 用于彩色输出）
  • 用 go mod tidy 管理依赖
  • 运行程序验证

练习 5：internal 目录

要求：

  • 创建一个项目，将内部实现放在 internal 目录
  • 验证外部项目无法导入 internal 包

13. 自测题

13.1 概念题

  1. Go 中怎么声明一个标识符可以被其他包访问？
  2. main 包有什么特殊之处？
  3. go.mod 文件的作用是什么？
  4. go mod tidy 做什么？
  5. init 函数什么时候执行？
  6. internal 目录有什么特殊含义？
  7. Go 允许包之间循环导入吗？
  8. 同一个目录下的文件可以属于不同包吗？
  9. 空导入（_ "package"）有什么用？
  10. 包的初始化顺序是什么？

14. 本课总结

这一课你学到了 Go 的代码组织方式。

你现在应该已经理解：

  • 包是 Go 代码组织的基本单位
  • 首字母大写的标识符可以被其他包访问
  • 模块由 go.mod 定义，管理依赖关系
  • 用 go mod tidy 自动管理依赖
  • internal 目录保护内部实现
  • 包的初始化顺序：变量 → init() → main()
  • 项目结构要合理分层，避免循环导入

15. 下一课预告

下一课我们进入阶段四：标准库与实战阶段，首先学习：文件操作基础。

会重点讲：

  • 怎么打开、创建、读取、写入文件
  • os、io、bufio 包的使用
  • 文件路径操作

学完下一课，你就能编写处理文件的程序了。