跳到主要内容

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/rsa vs crypto/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 典型用途​

  1. 注册驱动:import _ "github.com/lib/pq" 触发 init() 注册 postgres 驱动
  2. 初始化全局配置:从文件读配置
  3. 校验包级变量:检查 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/projectgo 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笔记
gGo 写的,跨平台(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​

errorpanic
含义可预期的失败不该发生的程序错误
处理调用方判断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" 没作用
忽略 errorf, _ := os.Open(...) 编译能过,运行时空指针 panic
_ 导入不写方法编译期不报错;运行期缺驱动 panic

8. 工程化建议​

  1. 目录布局:
    myapp/
    ├── cmd/ # main 入口(一个二进制一个目录)
    ├── internal/ # 私有代码(不导出给外部)
    │ ├── service/
    │ └── repo/
    ├── pkg/ # 导出给外部的库
    ├── api/ # protobuf / OpenAPI 定义
    ├── configs/ # 配置文件
    ├── go.mod
    └── go.sum
  2. commit 前跑 go vet ./... 和 gofmt -l .
  3. CI 必须跑 go test ./... 和 go mod tidy 校验
  4. 版本控制:go.mod + go.sum 必须提交(保证依赖可复现)