Go 包与工程笔记
本篇覆盖 Go 的包管理(
import、init()、go.mod)+ 常用标准库速查 + 错误处理。 对应 demo:05_packages
1. import 的 4 种写法
1.1 普通导入
import "fmt"
import "strings"
import (
"fmt"
"strings"
)
1.2 别名导入
import (
f "fmt" // 用 f.Println()
str "strings" // 用 str.Split()
)
典型场景:包名重复(如
crypto/rsavscrypto/ecdsa)、包名很长(如github.com/golang/protobuf/proto)。
1.3 点导入
import . "fmt" // 不写包名直接用 Println
⚠️ 慎用,会污染命名空间。一般只在
_test.go(测试)或少数框架(gin.H{})用。
1.4 匿名导入(只触发 init)
import _ "github.com/lib/pq" // 不直接用,只为触发驱动的 init()
典型场景:注册数据库驱动、image 解码器。
2. 包级可见性
- 首字母大写:导出(其他包可访问)
- 首字母小写:包内私有
package user
type Profile struct { // 导出
Name string
age int // 包内私有
}
func New() *Profile { ... } // 导出
func validate() { ... } // 包内私有
3. init() 函数
3.1 是什么
- 每个文件可以有多个
init(),无参数无返回值 - 在
main()之前自动执行 - 同一个包内按文件名字母序执行
- 多个包按 import 依赖关系执行
var startTime time.Time
func init() {
startTime = time.Now()
fmt.Println("[init] 包初始化完成")
}
3.2 典型用途
- 注册驱动:
import _ "github.com/lib/pq"触发init()注册postgres驱动 - 初始化全局配置:从文件读配置
- 校验包级变量:检查
const合法性
3.3 初始化顺序
常量 → 包级 var(按依赖)→ init() → main()
3.4 常见坑
- 不要在
init()里做依赖外部状态的事情(顺序不可控) - 不要在
init()里抛 panic(程序直接挂) - 测试时
init()会跑,可能影响测试 setup
4. go.mod 与模块化
4.1 是什么
go.mod 声明模块名、Go 版本、依赖项。Go 1.16+ 默认开启模块化(不再需要 GOPATH)。
4.2 基本结构
module github.com/hiyoungman/myapp
go 1.23.4
require (
github.com/gin-gonic/gin v1.10.0
github.com/spf13/viper v1.18.2
)
4.3 常用命令
go mod init <module-name> # 初始化(生成 go.mod)
go mod tidy # 增删依赖(同步 go.sum)
go mod download # 下载依赖到本地缓存
go mod verify # 校验缓存的依赖
go mod graph # 看依赖图
go mod vendor # 把依赖拷贝到 ./vendor/
go mod why -m <module> # 解释为什么需要某个依赖
go mod edit # 编程式编辑 go.mod
go get github.com/gin-gonic/gin # 装一个依赖(最新)
go get -u ./... # 升级所有依赖到最新 minor/patch
go get -u=patch ./... # 只升级 patch
go get foo@v1.2.3 # 装指定版本(也支持 @branch / @commit)
go list -m -u all # 列出可升级的依赖
go list -m all # 列出所有依赖模块
4.4 团队协作的版本固定
// go.mod
go 1.23.4
- 即便协作者本机装了 Go 1.22,
go.mod里的1.23.4也会强制使用对应工具链 - 配合 gvm(I_Go笔记)使用效果最佳
4.5 替代方案(备查)
- vendor 目录:
go mod vendor后用-mod=vendor编译,适合离线 / 内网 - replace 指令:临时把依赖指到本地路径或 fork 仓库
- internal 包:放在
internal/目录下的包只能被父目录的包 import
4.6 go module 精要
go.mod 文件的 4 个指令:
| 指令 | 作用 |
|---|---|
module | 模块名(包路径前缀) |
require | 依赖项及版本 |
replace | 替换依赖到本地或 fork |
exclude | 排除特定版本 |
go.sum 是什么:模块内容的加密哈希,保证依赖可复现。必须和 go.mod 一起提交。
GO111MODULE 模式(Go 1.16 之前的环境变量,现在基本不用管):
| 值 | 行为 |
|---|---|
off | 走老的 GOPATH 模式 |
on | 强制走 module,不查 GOPATH |
auto(默认) | 当前目录有 go.mod 启用,否则走 GOPATH |
go mod init <项目名> 怎么取名:
| 场景 | 推荐命名 | 示例 |
|---|---|---|
| 公开仓库(GitHub) | github.com/用户名/项目名 | go mod init github.com/hiyoungman/myapp |
| 公开仓库(GitLab / Gitee) | 同理 | go mod init gitee.com/hiyoungman/myapp |
| 公司内私有 | git.mycompany.com/team/project | go mod init git.acme.com/pay/api |
| 临时学习 | 短写也行,但建议规范 | go mod init example.com/test/demo |
❌ 不推荐:
go mod init myproject # 太短,易冲突
go mod init main # 无意义
go mod init . # 当前目录名不是标准路径
replace 指令(解决"某些包拉不下来"):
// go.mod
require golang.org/x/crypto v0.0.0-20190313024323-a1f597ede03a
replace (
golang.org/x/crypto v0.0.0-20190313024323-a1f597ede03a => github.com/golang/crypto v0.0.0-20190313024323-a1f597ede03a
)
4.7 Go 多版本管理(备查)
| 工具 | 特点 | 适用 |
|---|---|---|
| gvm(推荐) | Bash 实现,多版本并存,支持源码/二进制安装 | 本项目使用的方案,见 I_Go笔记 |
g | Go 写的,跨平台(macOS/Linux/Windows) | 习惯用 Go 工具链的开发者 |
| asdf | 通用多语言版本管理(不仅 Go) | 同时管 Python/Node/Ruby 等多版本 |
| 系统包管理器 | apt install golang-go | 仅需一个稳定版本 |
取舍:gvm + 项目级
go.mod go 1.23.4是最稳的组合:本地用 gvm 装/切 Go 版本,go.mod 锁住项目用的版本,团队成员即便本机 Go 不同也能编译一致。
5. 错误处理(error)
5.1 error 接口
type error interface {
Error() string
}
任何实现了 Error() string 的类型都是 error。
5.2 创建 error
// 1. errors.New
return 0, errors.New("division by zero")
// 2. fmt.Errorf
return 0, fmt.Errorf("parse port failed: %d", port)
// 3. 自定义类型
type MyError struct {
Code int
Msg string
}
func (e *MyError) Error() string {
return fmt.Sprintf("code=%d msg=%s", e.Code, e.Msg)
}
5.3 错误包装(Go 1.13+)
// wrap
if err != nil {
return fmt.Errorf("read config: %w", err)
}
// unwrap
err := errors.Unwrap(wrappedErr)
// 判断是否是某个特定 error
if errors.Is(err, os.ErrNotExist) { ... }
// 类型断言
var pathErr *os.PathError
if errors.As(err, &pathErr) { ... }
5.4 错误处理模式
// 1. 直接返回(最常见)
result, err := doSomething()
if err != nil {
return err
}
// 2. 加上下文
result, err := doSomething()
if err != nil {
return fmt.Errorf("doSomething at step %d: %w", step, err)
}
// 3. 哨兵 error(sentinel)
var ErrNotFound = errors.New("not found")
if err == ErrNotFound { ... } // 直接比
if errors.Is(err, ErrNotFound) { ... } // 推荐:兼容 wrap
// 4. 自定义 error 类型
if myErr, ok := err.(*MyError); ok {
if myErr.Code == 404 { ... }
}
5.5 错误 vs panic
| error | panic | |
|---|---|---|
| 含义 | 可预期的失败 | 不该发生的程序错误 |
| 处理 | 调用方判断 | recover() 或崩溃 |
| 频率 | 高频 | 极低频 |
| 典型场景 | 文件不存在、网络断 | 数组越界、map nil 写、配置缺失 |
6. 常用标准库速查
6.1 fmt
fmt.Println(a, b, c) // 自动加空格,末尾换行
fmt.Printf("%s=%d\n", k, v) // 格式化
fmt.Errorf("wrap: %w", err) // 创建 error
fmt.Sprintf("hi %s", name) // 不打印,返回 string
6.2 strings
strings.Contains(s, "x") // 包含
strings.HasPrefix(s, "x") // 前缀
strings.ToUpper(s) / ToLower(s) // 大小写
strings.Split(s, ",") // 分割为 []string
strings.Join(slice, ",") // 拼接
strings.Replace(s, "a", "b", n) // 替换 n 次
strings.TrimSpace(s) // 去前后空白
strings.Trim(s, cutset) // 去指定字符
strings.Index(s, "x") // 位置(找不到返回 -1)
6.3 strconv(数字 ↔ 字符串)
strconv.Itoa(42) // int → string
strconv.Atoi("42") // string → int (返回 error)
strconv.FormatInt(255, 16) // int → string, 指定进制
strconv.ParseInt("ff", 16, 64) // string → int64
strconv.FormatFloat(3.14, 'f', 2, 64) // float → string,保留 2 位
strconv.FormatBool(true) // bool → string
6.4 time
now := time.Now()
now.Format("2006-01-02 15:04:05") // 格式化(参考时间是固定的)
t, _ := time.Parse("2006-01-02", "2026-06-14")
d := 2*time.Hour + 30*time.Minute // Duration
time.Sleep(500*time.Millisecond)
time.Since(start) // time.Duration
格式化的"参考时间"是固定字符串
Mon Jan 2 15:04:05 MST 2006,对应1, 2, 3, 4, 5, 6, 7几个数字,方便记忆。
6.5 errors
errors.New("msg") // 简单 error
errors.Is(err, target) // 链式比较(兼容 wrap)
errors.As(err, &target) // 链式类型断言
errors.Unwrap(err) // 拿包装的底层 error
6.6 os / io
os.Open("file") // 读模式
os.Create("file") // 写模式(覆盖)
os.ReadFile("file") // 一次读全文
os.WriteFile("file", data, 0644) // 一次写
os.Getenv("HOME") // 读环境变量
io.ReadAll(r) // 读到底
6.7 encoding/json
type User struct {
Name string `json:"name"`
Age int `json:"age,omitempty"` // omitempty 零值忽略
}
u := User{Name: "x", Age: 25}
b, _ := json.Marshal(u) // → []byte
json.Unmarshal(b, &u) // → struct
// 通用
var m map[string]any
json.Unmarshal(b, &m)
6.8 context
ctx, cancel := context.WithCancel(context.Background())
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
go func() {
select {
case <-ctx.Done():
return // 取消或超时
case <-time.After(10 * time.Second):
cancel() // 主动取消
}
}()
7. 常见坑
| 坑 | 说明 |
|---|---|
循环里 defer 资源关闭 | defer 栈累积,耗尽 fd;要在循环里用 IIFE 限定 |
| 包级变量循环依赖 | 编译错误;用函数 / 延迟初始化解决 |
init() 顺序 | 同包按文件名;跨包按 import 依赖 |
errors.Is vs == | 包了 wrap 的 error 用 == 比会失败,要用 errors.Is |
| 时区 | time.Now() 是本地时区;跨时区用 time.UTC 或 time.LoadLocation |
json:"name" 必须小写 | struct tag 里写大写 JSON:"name" 没作用 |
忽略 error | f, _ := os.Open(...) 编译能过,运行时空指针 panic |
_ 导入不写方法 | 编译期不报错;运行期缺驱动 panic |
8. 工程化建议
- 目录布局:
myapp/├── cmd/ # main 入口(一个二进制一个目录)├── internal/ # 私有代码(不导出给外部)│ ├── service/│ └── repo/├── pkg/ # 导出给外部的库├── api/ # protobuf / OpenAPI 定义├── configs/ # 配置文件├── go.mod└── go.sum
- commit 前跑
go vet ./...和gofmt -l . - CI 必须跑
go test ./...和go mod tidy校验 - 版本控制:
go.mod+go.sum必须提交(保证依赖可复现)