Go 自定义包与多文件编程

在实际项目开发中,一个软件往往包含几千甚至上万行代码。如果把所有代码都塞在同一个 main.go 文件里,后续查找和修改都会非常麻烦。

在 Go 语言中,源代码是以代码包为单位来组织的。为了把项目结构划分得清晰有序,我们通常有两种拆分代码的方式:一种是新建子文件夹,创建自定义子包来按功能模块管理代码;另一种是在同一个文件夹下,把代码拆分成多个同属一个包的 .go 源文件。

创建与调用自定义子包

在通过 Go Modules 初始化过的项目中,每个子文件夹都代表一个独立的自定义子包。当我们在子文件夹中写好代码后,如果想要在根目录的 main.go 中导入并使用它,需要按照下面的语法格式来编写。

语法:

// 子包文件开头声明包名
package 子包名

// 外部文件按模块路径导入
import "模块名/子包路径"

说明:

在创建和导入自定义子包时,小伙伴们需要重点掌握以下 3 条规则:

  • 子文件夹名与包名保持一致:子文件夹叫什么名字,该文件夹内部所有 .go 文件第一行的 package 一般就声明为什么名字。比如在 calc 子文件夹下编写代码,文件开头就统一写 package calc。
  • 导入时写模块路径,调用时写包名:使用 import 导入自定义子包时,双引号里写的是 "模块名/子包路径",比如 "myproject/calc"。而在代码中调用函数时,写的则是子包声明的包名,比如 calc.Add()。
  • 公开成员的首字母必须大写:子包中只有首字母大写的函数、变量、常量、结构体以及结构体字段,才能被外面的包跨包调用。

示例 1:创建并调用 calc 子包

假设我们已经通过 go mod init myproject 创建了一个名为 myproject 的项目,并在根目录下新建了一个 calc 子文件夹。整个项目的目录结构如下:

myproject/
├── go.mod
├── main.go
└── calc/
    └── calc.go

其中,根目录下的 go.mod 文件内容如下:

module myproject

go 1.24.0

接下来,我们先在子文件夹的 calc/calc.go 文件中编写两个加减法函数:

// calc/calc.go
package calc

// 公开函数,可跨包调用
func Add(a, b int) int {
    return a + b
}

// 私有函数,仅限包内使用
func sub(a, b int) int {
    return a - b
}

然后,我们在项目根目录下的 main.go 文件中导入 "myproject/calc" 子包,并调用 Add() 函数:

// main.go
package main

import (
    "fmt"

    "myproject/calc"
)

func main() {
    res := calc.Add(10, 20)
    fmt.Println("10 + 20 =", res)
}

在 myproject 根目录下打开终端执行 go run .,运行结果如下。

10 + 20 = 30

分析:

main.go 中的 import "myproject/calc" 表示导入当前项目下的 calc 子包。开头的 myproject 并不是电脑磁盘上的绝对路径,而是 go.mod 第 1 行声明的模块名,后面的 /calc 则是子包文件夹路径,对应关系如下图所示。

Go 自定义子包的目录结构与导入对应关系

在 calc/calc.go 中,我们定义了首字母大写的 Add() 和首字母小写的 sub() 两个函数。因为在 main.go 中属于跨包调用,所以我们只能调用公开的 calc.Add(10, 20),下面这种跨包调用私有函数的写法就是错误的。

res := calc.sub(20, 10)

如果我们尝试在 main.go 中调用 calc.sub(),编译器会直接报错 undefined: calc.sub,意思是该名称未定义或未导出,无法在 calc 包外部访问。

除了函数之外,结构体和它的字段在跨包使用时同样受首字母大小写控制。下面我们再来看一个自定义结构体的跨包访问示例。

示例 2:跨包访问结构体与字段

我们在 myproject 下新建一个 model 子文件夹,并在里面创建 student.go 文件,目录结构如下:

myproject/
├── go.mod
├── main.go
└── model/
    └── student.go

在 model/student.go 中定义 Student 结构体,其中 Name 首字母大写,age 首字母小写:

// model/student.go
package model

type Student struct {
    Name string    // 公开字段,可跨包读写
    age  int       // 私有字段,仅限 model 包内部使用
}

在根目录的 main.go 中导入 "myproject/model",并创建结构体实例读取公开字段:

// main.go
package main

import (
    "fmt"

    "myproject/model"
)

func main() {
    stu := model.Student{Name: "Jack"}
    fmt.Printf("学生姓名:%s\n", stu.Name)
}

在 myproject 根目录下执行 go run .,运行结果如下。

学生姓名:Jack

分析:

在 model.Student 中,类型名 Student 和字段 Name 的首字母都是大写的,因此在 main 包中既能创建 model.Student 实例,也能正常初始化和读取 stu.Name。

但字段 age 的首字母是小写的,属于 model 包内部的私有字段。如果我们在 main.go 里尝试初始化或读取 stu.age,编译就会报错:

// 错误方式
stu := model.Student{Name: "Jack", age: 20}
fmt.Println(stu.age)

上面第 1 行会报错 unknown field age in struct literal,意思是结构体字面量中找不到公开字段 age,第 2 行同样会提示无法访问未导出字段。

遇到需要跨包读写的结构体字段,小伙伴们记得把首字母写成大写。如果确实希望隐藏某个内部字段,也可以设为小写,再在同包里提供大写的公开方法(如 GetAge())供外部读取。

注意:

  • 只在项目根目录初始化一次:一个项目通常只在最外层的根目录下执行一次 go mod init 生成一个 go.mod 文件。新建 calc、model 等子文件夹时,我们直接在里面创建 .go 文件就可以了,千万不要进入子文件夹里重复执行 go mod init。
  • 编辑器直接打开模块根目录:使用 VSCode 或 GoLand 编写多包项目时,记得直接打开 go.mod 所在的 myproject 根目录。如果打开了更外层的上级文件夹,编辑器可能会找不到 go.mod,导致自定义包导入路径标红报错。

自定义包内部的多文件互通

随着项目不断扩展,如果 calc 子包里的计算功能越来越多,我们同样可以在 calc 子文件夹下继续新建多个 .go 源文件,方便大家按功能拆分代码。

只要这些文件都在同一个 calc 文件夹下,并且文件开头都声明了 package calc,它们就属于同一个包。同一个包内部的多个文件之间是直接互通的,不需要写任何 import 语句,就能直接使用对方文件里的变量和函数,哪怕是首字母小写的私有函数也能直接调用。

示例 3:子包内部多文件互通

我们在示例 1 的基础上,往 calc 子文件夹里再新建一个 mul.go 文件。此时项目的目录结构如下:

myproject/
├── go.mod
├── main.go
└── calc/
    ├── calc.go
    └── mul.go

在新建的 calc/mul.go 文件中,我们直接调用旁边 calc.go 里定义的私有函数 sub():

// calc/mul.go
package calc

// 直接调用同包私有函数
func DoubleSub(a, b int) int {
    diff := sub(a, b)
    return diff * 2
}

随后我们在根目录的 main.go 中调用新增的公开函数 calc.DoubleSub():

// main.go
package main

import (
    "fmt"

    "myproject/calc"
)

func main() {
    fmt.Println(calc.DoubleSub(20, 5))
}

在项目根目录下执行 go run .,运行结果如下。

30

分析:

在 calc/mul.go 中,虽然私有函数 sub() 定义在旁边的 calc.go 里,但这两个文件都声明了 package calc。因为同属一个包,所以在 DoubleSub() 中可以直接调用 sub(20, 5) 算出差值 15,乘以 2 后得到结果 30。

main 包下的多文件拆分与运行

除了在子包中拆分多个文件,我们也可以直接在项目根目录下,把入口包 package main 拆分成多个 .go 文件。比如把主流程留在 main.go 中,把辅助函数拆分到同目录的 utils.go 中。

示例 4:拆分并运行 main 包

假设我们在 myproject 根目录下并排放置 main.go 和 utils.go 两个文件,目录结构如下:

myproject/
├── go.mod
├── main.go
└── utils.go

其中,utils.go 同样声明为 package main,并定义一个打招呼的辅助函数 sayHi():

// utils.go
package main

import "fmt"

func sayHi(name string) {
    fmt.Printf("你好,%s!\n", name)
}

在同目录的 main.go 文件中,我们直接在主函数里调用 sayHi():

// main.go
package main

func main() {
    sayHi("Jack")
}

在项目根目录下打开终端,执行以下命令运行整个目录:

go run .

运行结果如下。

你好,Jack!

分析:

因为 main.go 和 utils.go 都在项目根目录下且都声明了 package main,所以 main.go 可以直接调用 utils.go 里的 sayHi("Jack")。

不过在终端运行这个程序时,很多初学的小伙伴会习惯性地输入 go run main.go,结果终端却直接报错。

# 正确方式
go run .

# 错误方式
go run main.go

为什么 go run main.go 会报 undefined: sayHi 错误呢?因为当我们指定某一个具体的 .go 文件名时,Go 只会单独编译 main.go 这一份文件,不会去加载旁边的 utils.go,自然就找不到定义在里面的 sayHi() 函数了。

虽然也可以把文件名逐个列出来写成 go run main.go utils.go,但文件一多就会非常麻烦。

写成 go run . 时,注意 run 后面有一个空格和英文点号(.)。这个点号代表当前整个目录,Go 会自动把目录下所有属于 package main 的源文件一起加载进来编译运行。

此外还要留意,把 package main 拆分成多个源文件时,同一个目录下只能保留唯一一个 main() 函数作为程序入口。如果我们在 utils.go 里也写了一个 main() 函数,执行 go run . 或使用 go build 编译时都会报重复定义错误。

常见问题

1. 为什么导入自己写的 calc 子包时,不能写相对路径 import "./calc"?

在 Go Modules 模式下,Go 官方规定不支持使用 import "./calc" 或 import "../calc" 这样的相对路径导入包,直接这样写会触发编译报错。

所有自定义子包的导入路径都必须以 go.mod 中的模块名开头,比如写成 "myproject/calc"。这样做有一个明显的好处:无论当前代码文件位于项目的哪一层子目录中,导入同一个子包时的路径永远固定不变,移动文件位置时也不需要去修改容易出错的相对路径。

2. 子文件夹的名字和文件里声明的 package 包名不一致可以吗?

语法上允许,但日常开发中强烈不推荐这样做。如果文件夹叫 calc,里面文件开头却写了 package mathutil。此时外部导入依然要按文件夹路径写 import "myproject/calc",但在代码里调用函数却必须写 mathutil.Add()。

这种 “路径名和调用名对不上” 的写法非常容易让人看混。为了方便自己和团队成员阅读代码,除了入口包 package main 之外,其他子包的文件夹名和 package 名称都应该保持完全一致。

给站长反馈

绿叶网正在不断完善中,小伙伴们如果发现任何问题,还望多多给站长反馈,谢谢!

邮箱:lvyenet@vip.qq.com

「绿叶网」服务号
绿叶网服务号放大
关注服务号,微信也能看教程。
绿叶网服务号