Go-08-包、模块与代码组织

字数统计: 1.6k字   |   阅读时长≈ 7分

Go-08-包、模块与代码组织

本节目标：掌握 Go 的包（package）系统、模块（module）/ go.mod、init 机制，理解 import 路径解析。

1. 包（package）基础

包是 Go 基本的代码组织单元。每个 .go 文件开头必须声明 package 名：

1
2
package mypkg
// ...

同包内的多个 .go 文件 组成一个编译单元，共享私有（未导出）标识符。

1.1 包名 vs 目录名

惯例：包名和所在目录名相同（最后一段路径）。

1
2
3
4
5
mypkg/
├── add.go       // package mypkg
├── sub.go       // package mypkg
└── internal/    // 私有子包
    └── helper.go

例外：main 包是入口包，目录名可以任意但 package 必须是 main。

1.2 导出规则

  • 首字母大写 = 导出（public）
  • 首字母小写 = 包内可见（private）
1
2
3
4
package mypkg

func Public() {}    // 其他包可调用
func private() {}   // 仅 mypkg 内部可调用

2. import 语法

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
import "fmt"                              // 单个
import (
    "fmt"                                 // 标准库
    "os"
    "github.com/gin-gonic/gin"            // 第三方
    "myapp/internal/auth"                 // 内部包
)

// 别名
import (
    f "fmt"
    crand "crypto/rand"
)

// 匿名导入（只执行 init，不直接使用）
import _ "github.com/lib/pq"  // 注册 postgres 驱动
import _ "image/png"          // 注册 PNG 解码器

// 点导入（不推荐）
import . "fmt"  // Println 不用前缀，但和本地函数冲突

3. go.mod 与模块（Module）

模块 = 一个或多个包的集合，有版本号，通过 go.mod 文件标识。

3.1 创建模块

1
2
3
$ mkdir myapp && cd myapp
$ go mod init github.com/myuser/myapp
go: creating new go.mod: module github.com/myuser/myapp

生成的 go.mod：

1
2
3
module github.com/myuser/myapp

go 1.22

3.2 常用命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 添加依赖
go get github.com/gin-gonic/gin@latest    # 最新
go get github.com/gin-gonic/gin@v1.9.1    # 指定版本
go get github.com/gin-gonic/gin@upgrade   # 升级到最新 minor/patch
go get github.com/gin-gonic/gin@patch     # 升级到最新 patch

# 删除未使用的依赖
go mod tidy

# 查看依赖图
go mod graph

# 下载所有依赖到本地 cache
go mod download

# vendor 模式（把依赖复制到 vendor/ 目录）
go mod vendor

# 验证依赖完整性
go mod verify

3.3 go.mod 文件结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
module github.com/myuser/myapp

go 1.22

require (
    github.com/gin-gonic/gin v1.9.1
    github.com/spf13/viper v1.18.0
)

require (
    // indirect dependencies
    github.com/xxx/yyy v1.0.0 // indirect
)

// 替换（私有 fork）
replace github.com/original/lib => github.com/myuser/lib v1.0.0

// 排除有问题的版本
exclude github.com/bad/lib v1.0.0

4. import 路径解析规则

1
import "github.com/gin-gonic/gin"

Go 工具链查找顺序：

  1. 标准库：fmt, os, net/http 直接在 $GOROOT/src 找
  2. 模块内相对路径：module-path/...
  3. GOPATH/pkg/mod：第三方依赖缓存
  4. **vendor/**（如果存在）：优先于 GOPATH

示例：

1
module github.com/myuser/myapp

文件 github.com/myuser/myapp/cmd/server/main.go 想 import 同模块的包：

1
2
3
4
import (
    "github.com/myuser/myapp/internal/auth"   // OK
    "github.com/myuser/myapp/pkg/util"        // OK
)

5. internal 包（私有性）

internal 目录是个魔法：myapp/internal/foo 只能被 myapp/... 下的代码 import，外部模块看不到。

1
2
3
4
5
6
7
8
github.com/myuser/myapp/
├── internal/
│   └── auth/         ← 只能被 myuser/myapp 下的代码 import
├── pkg/
│   └── util/         ← 公开，谁都能 import
└── cmd/
    └── server/
        └── main.go

Go 工具会在 go build 时检查，import 别人 internal 包直接编译错误。

6. init 函数：包级初始化

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

import "log"

func init() {
    log.Println("redis package initialized")
}

var client *Client  // 包级变量

func init() {
    client = NewClient()  // 在 init 里初始化
}

init 触发时机：

  • 包被 import 时（只一次）
  • 多个 init 按声明顺序执行
  • 依赖包的 init 先于当前包
  • main 包的 init 在 main 函数前执行

典型用途：

  • 注册驱动（database/sql、image 解码器）
  • 加载配置
  • 启动后台 goroutine
  • 设置全局状态

警告：init 里 panic 会让整个程序启动失败。

7. 包级变量 vs init 初始化

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
// 简单情况用 var 初始化
var (
    DefaultPort = 8080
    Version     = "1.0.0"
)

// 复杂情况用 init
var db *sql.DB

func init() {
    var err error
    db, err = sql.Open("postgres", os.Getenv("DATABASE_URL"))
    if err != nil {
        log.Fatal(err)  // init 失败直接退出
    }
}

8. 实战：项目结构

典型 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
myapp/
├── cmd/
│   └── server/
│       └── main.go         ← 入口
├── internal/                ← 私有包
│   ├── auth/
│   │   ├── auth.go
│   │   └── auth_test.go
│   ├── config/
│   │   └── config.go
│   └── handler/
│       ├── user.go
│       └── user_test.go
├── pkg/                     ← 公开 API
│   └── models/
│       └── user.go
├── api/                     ← API 协议定义（OpenAPI/protobuf）
├── configs/                 ← 配置文件
│   └── config.yaml
├── deployments/             ← 部署相关（docker-compose, k8s）
├── docs/                    ← 文档
├── scripts/                 ← 脚本
├── test/                    ← 集成测试
├── go.mod
├── go.sum
├── Makefile
└── README.md

为什么这样分：

  • cmd/：多个可执行文件入口
  • internal/：业务逻辑，不暴露给外部
  • pkg/：可以独立 import 的库
  • api/：接口契约
  • deployments/：基础设施

9. 多模块项目（Monorepo）

1
2
3
4
5
6
7
8
9
10
11
myorg/
├── go.work                  ← workspace 文件
├── service-a/
│   ├── go.mod
│   └── main.go
├── service-b/
│   ├── go.mod
│   └── main.go
└── shared/
    ├── go.mod
    └── util.go

go.work：

1
2
3
4
5
6
7
go 1.22

use (
    ./service-a
    ./service-b
    ./shared
)
1
2
3
# 在 workspace 模式下
go work use ./service-a     # 加入 workspace
go work sync                # 同步依赖

10. 实战：发布自己的 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
# 1. 初始化
mkdir mylib && cd mylib
go mod init github.com/myuser/mylib

# 2. 写代码
echo 'package mylib
func Hello() string { return "Hello, World!" }' > mylib.go

# 3. 写测试
echo 'package mylib
import "testing"
func TestHello(t *testing.T) {
    if Hello() != "Hello, World!" {
        t.Error("wrong")
    }
}' > mylib_test.go

# 4. 推送到 GitHub
git init && git add . && git commit -m "init"
git remote add origin git@github.com:myuser/mylib.git
git push -u origin main

# 5. 别人用
go get github.com/myuser/mylib

11. 循环依赖

包 A 引用 B，B 又引用 A → 编译错误。解决方法：

1
2
3
4
5
6
7
8
9
10
// 错：循环引用
// a/a.go
package a
import "myapp/b"
func UseB() { b.Do() }

// b/b.go
package b
import "myapp/a"   // 循环！
func Do() { a.UseA() }

解决 1：抽公共部分到第三个包

1
2
3
4
a/   b/   common/
       \  /
        ↕
      shared

解决 2：用接口解耦

1
2
3
4
5
6
7
8
9
10
// b/b.go: 不直接 import a，而是接受一个接口
package b
type ADep interface {
    UseA() string
}
func Do(a ADep) { a.UseA() }

// a/a.go: 实现 ADep
package a
func UseA() string { return "from A" }

12. 最佳实践

  1. 包名短而清晰：bytes, http, time（不要 util, common, helper）
  2. 避免包级状态：少用全局变量，多用依赖注入
  3. 小而专的包：每个包做一件事
  4. import 分组：标准库 / 第三方 / 内部 用空行分隔
  5. 不要 import . （点导入）
  6. vendor 还是 module：Go 1.16+ 默认 module，不用 vendor（除非有网络限制）

小结

概念 作用
package 代码组织单位，编译单元
go.mod 模块定义 + 依赖版本
internal/ 包私有性（魔法）
init() 包级初始化，import 时触发
import 标准库、第三方、内部
replace 模块替换（debug 私有 fork）
go.work 多模块 workspace

最常用命令：

1
2
3
4
5
go mod init mymodule
go mod tidy
go get package@version
go mod vendor
go work init

下一节讲 I/O 与文件处理，Go 用 io.Reader/io.Writer 接口统一了所有 I/O。

赏

谢谢你请我吃糖果

支付宝
微信

扫一扫，分享到微信

tag:

    缺失模块。
    1、请确保node版本大于6.2
    2、在博客根目录（注意不是yilia-plus根目录）执行以下命令：
    npm i hexo-generator-json-content --save

    3、在根目录_config.yml里添加配置： 

      jsonContent:
    meta: false
    pages: false
    posts:
      title: true
      date: true
      path: true
      text: false
      raw: false
      content: false
      slug: false
      updated: false
      comments: false
      link: false
      permalink: false
      excerpt: false
      categories: false
      tags: true

主要涉及技术：
Java后端开发、Linux开发、
公众号开发、开源爱好者、Linux

联系QQ:562054870