Go 包和模块入门：把代码从一个文件整理成一个小项目

从一个文件走向一个项目

刚开始学 Go 时，所有代码写在 main.go 里很正常。几十行代码时，这样最直接；可是一旦你开始写命令行工具、HTTP 服务、批处理脚本，main.go 很快会变成一个混合了参数解析、业务规则、文件读写和输出格式的长文件。Go 的包和模块，就是用来帮你把这些代码拆开，同时保持引用关系清楚。

Go 的组织方式比很多语言简单：一个目录通常就是一个包，一个模块由 go.mod 定义，导入路径从模块名开始。你不需要先搭一套复杂工程骨架，也不需要为了“架构感”拆出很多空目录。更好的做法是：当一段代码有清楚职责，并且已经让当前文件变得拥挤时，再把它移动到合适的包里。

这篇文章用一个文章统计小工具为例，讲清楚 package、import、导出规则、go.mod 和目录组织。目标不是背规则，而是学会判断：哪些代码留在 main，哪些代码应该成为包，包名怎么取，跨包调用时要注意什么。

每个 Go 文件都属于一个包

一个最小程序：

package main

import "fmt"

func main() {
	fmt.Println("hello")
}

第一行 package main 表示这个文件属于 main 包。main 包有特殊含义：如果它包含 main 函数，就可以编译成可执行程序。普通库代码不会写 package main，而是写自己的包名。

同一个目录里的 .go 文件必须属于同一个包。下面结构是合法的：

wordstat/
├── go.mod
├── main.go
└── counter.go

两个文件都写：

package main

它们会被编译到同一个包里，彼此可以直接调用小写开头的函数。这适合简单程序，但当代码职责变多时，所有东西都在 main 包里也会混乱。

如果要创建独立包，可以建子目录：

wordstat/
├── go.mod
├── main.go
└── textstat/
    └── counter.go

textstat/counter.go 写：

package textstat

import "strings"

func CountWords(text string) int {
	fields := strings.Fields(text)
	return len(fields)
}

main.go 引用：

package main

import (
	"fmt"

	"example.com/wordstat/textstat"
)

func main() {
	fmt.Println(textstat.CountWords("Go is simple and practical"))
}

导入路径从模块名 example.com/wordstat 开始，再加子目录 textstat。

go.mod 是模块的入口

初始化模块：

go mod init example.com/wordstat

生成：

module example.com/wordstat

go 1.20

模块名不一定真的能访问，但真实项目最好使用仓库路径，比如 github.com/birdor/wordstat。模块名会成为包的导入前缀，所以不要随便改。项目发布后修改模块名，会影响所有引用者。

查看当前模块：

go list ./...

输出可能是：

example.com/wordstat
example.com/wordstat/textstat

./... 表示当前目录和所有子目录下的包。这个命令很适合检查包是否组织正确。

当你引入外部依赖时，go.mod 会记录依赖版本，go.sum 会记录校验信息。入门阶段可以先尽量用标准库，等你理解模块后再引入第三方包，会少很多困惑。

导出规则：大小写不是风格问题

Go 用首字母大小写决定名字是否导出。大写开头可以被其他包访问，小写开头只能包内使用。

package textstat

func CountWords(text string) int {
	return countWords(text)
}

func countWords(text string) int {
	return len(strings.Fields(text))
}

CountWords 可以被 main 包调用，countWords 不行。这个规则适用于函数、类型、变量、常量、结构体字段和方法。

结构体字段也一样：

type Result struct {
	Words int
	Lines int

	rawText string
}

其他包可以访问 Words 和 Lines，不能访问 rawText。这给你一个很简单的封装工具：只导出调用方真正需要的能力，内部细节保持小写。

不要为了方便把所有东西都大写。导出的名字会成为包的公共 API，别人可能依赖它，你以后修改就更谨慎。初学阶段可以先默认小写，确认需要跨包访问时再大写。

包名要短，但不要含糊

Go 包名通常短小，且不重复父目录信息。比如目录叫 textstat，包名也叫 textstat。调用时会写：

textstat.CountWords(text)

不要取成 utils、common、helper。这类名字看似方便，最后会变成杂物间。一个包应该有明确主题。处理文本统计，就叫 textstat；处理配置，就叫 config；处理文章存储，就叫 article 或 store，取决于职责。

也不要让包名和函数名重复：

textstat.TextStatCountWords(text)

调用处已经有包名前缀，所以函数名可以简洁：

textstat.CountWords(text)

Go 的可读性很依赖调用处的组合。包名和函数名连起来应该像一句短语。

一个小项目的自然拆法

假设我们要做一个文本统计命令：

wordstat/
├── go.mod
├── main.go
├── textstat/
│   ├── counter.go
│   └── counter_test.go
└── output/
    └── json.go

textstat 负责统计：

package textstat

import "strings"

type Result struct {
	Words int `json:"words"`
	Lines int `json:"lines"`
	Chars int `json:"chars"`
}

func Analyze(text string) Result {
	lines := 0
	if text != "" {
		lines = strings.Count(text, "\n") + 1
	}

	return Result{
		Words: len(strings.Fields(text)),
		Lines: lines,
		Chars: len([]rune(text)),
	}
}

output 负责输出 JSON：

package output

import (
	"encoding/json"
	"io"
)

func WriteJSON(w io.Writer, value interface{}) error {
	encoder := json.NewEncoder(w)
	encoder.SetIndent("", "  ")
	return encoder.Encode(value)
}

main 负责连接：

package main

import (
	"fmt"
	"os"

	"example.com/wordstat/output"
	"example.com/wordstat/textstat"
)

func main() {
	if len(os.Args) < 2 {
		fmt.Fprintln(os.Stderr, "usage: wordstat <text>")
		os.Exit(1)
	}

	result := textstat.Analyze(os.Args[1])
	if err := output.WriteJSON(os.Stdout, result); err != nil {
		fmt.Fprintln(os.Stderr, err)
		os.Exit(1)
	}
}

这就是一个健康的小项目：main 不做复杂业务，只负责输入输出和组装；包的职责单一；包之间通过导出的函数和类型交互。

避免循环依赖

Go 不允许包循环引用。比如 article 引用 store，store 又引用 article，编译会失败。这不是限制你，而是在保护项目结构。循环依赖通常说明边界没有想清楚。

常见解决方法是把共享类型放到更合适的位置，或者让依赖方向单向。比如文章类型放在 article 包，存储包引用文章类型：

article/
  article.go
store/
  memory.go

store 可以 import article，但 article 不应该再 import store。业务核心不应该反过来依赖具体存储实现。

入门阶段如果遇到 import cycle，不要急着找技巧绕过。先画一下：哪个包是更底层的能力，哪个包是更外层的组装？依赖应该从外层指向内层，或者从具体实现指向抽象类型，而不是互相拉扯。

小结

Go 的包和模块规则很少，但影响很大。一个目录一个包，go.mod 定义模块路径，大写导出，小写隐藏，导入路径从模块名开始。掌握这些规则后，你就能把代码从单文件整理成小项目。

好的拆包不是越多越好，而是职责清楚。main 负责启动和连接，业务包负责规则，输出包负责格式，存储包负责数据访问。包名要表达主题，导出的名字要谨慎，循环依赖要及时处理。

当你的 Go 程序开始有多个文件时，不要害怕整理结构。只要按照职责自然拆分，并让调用处读起来清楚，项目就会比一大坨 main.go 更容易维护。