在实际项目开发中,一个软件往往包含几千甚至上万行代码。如果把所有代码都塞在同一个 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 则是子包文件夹路径,对应关系如下图所示。

在 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 名称都应该保持完全一致。
