在Go语言中，项目工程化的日志、配置、错误处理规范是保障项目可维护性、可观测性与健壮性的核心实践之一。本章将从三个方面进行详解：
一、日志规范
1. 日志的重要性
- • 问题排查的唯一“现场还原”
- • 性能瓶颈的定位手段
- • 安全审计的依据
2. 日志库推荐
- • 标准库
log：适合简单应用 - • 社区常用库：
- •
uber-go/zap：高性能，结构化日志（强烈推荐） - •
sirupsen/logrus：API 友好，易上手
3. zap日志初始化示例
import "go.uber.org/zap" var Logger *zap.Logger func InitLogger() { var err error Logger, err = zap.NewProduction() // 生产级配置 if err != nil { panic(err) } }
4. 日志级别推荐使用
- •
Debug: 调试信息 - •
Info: 关键运行信息，如启动、配置、输入参数等 - •
Warn: 潜在问题，如配置异常、响应慢 - •
Error: 明确错误，需排查 - •
Fatal: 致命错误，程序将退出
5. 使用结构化日志推荐
Logger.Info("user login success", zap.String("username", username), zap.Int("user_id", userID), )
二、配置规范
1. 配置分离的必要性
- • 保证代码不依赖具体运行环境
- • 配置可以热更新或动态下发
2. 常见配置方式
| 类型 | 示例 | 说明 |
| JSON | config.json |
可读性强 |
| YAML | config.yaml |
层级清晰，易维护 |
| 环境变量 | os.Getenv("ENV") |
容器部署推荐 |
| TOML | 用于更复杂配置，如数据库等 | 文档友好 |
3. viper 读取配置示例
import "github.com/spf13/viper" func InitConfig() { viper.SetConfigName("config") viper.SetConfigType("yaml") viper.AddConfigPath(".") if err := viper.ReadInConfig(); err != nil { panic(fmt.Errorf("fatal config error: %w", err)) } }
配置样例 config.yaml：
app: port: 8080 env: dev db: dsn: "root:pass@tcp(127.0.0.1:3306)/demo"
4. 支持多环境配置
通过环境变量加载不同配置文件：
env := os.Getenv("APP_ENV") // dev / prod viper.SetConfigName("config." + env)
三、错误处理规范
1. Go 的错误处理哲学
Go 不鼓励异常（try-catch），采用 显式返回 error，更清晰、稳定。
2. 标准写法
result, err := doSomething() if err != nil { log.Error("doSomething failed", zap.Error(err)) return err }
3. 自定义错误类型
type BizError struct { Code int Message string } func (e BizError) Error() string { return fmt.Sprintf("Code: %d, Msg: %s", e.Code, e.Message) }
4. 错误封装与堆栈追踪
推荐使用 pkg/errors 或 Go 1.13+ 原生 errors 包：
import "errors" func WrapError() error { err := do() return fmt.Errorf("业务处理失败: %w", err) }
调用链尾部使用 errors.Unwrap(err) 或 errors.Is/As 判断原始错误类型。
5. 错误分层处理建议
| 层 | 错误类型 | 建议 |
| Handler | 参数、用户态错误 | 返回给前端，记录 info |
| Service | 业务逻辑错误 | 返回调用方，记录 warn |
| Repo/DAO | 数据库错误、IO 错误 | 封装后返回，记录 error |
| Main入口 | 崩溃、配置错误 | panic or fatal log |
四、实践统一封装建议
1. 错误响应体封装（HTTP）
type APIError struct { Code int `json:"code"` Message string `json:"message"` }
2. 自定义全局日志器/配置/错误包
project/ ├── pkg/ │ ├── logger/ │ ├── config/ │ └── errors/
pkg/logger/logger.go:
var Logger *zap.Logger func Init(logPath string) { // 初始化日志 }
五、总结
| 模块 | 工程化建议 |
| 日志 | 使用 zap，结构化输出，统一封装，支持级别/文件分割等 |
| 配置 | 使用 viper/yaml，支持环境变量，模块分离 |
| 错误 | 明确分层处理，业务错误自定义结构体，推荐使用 fmt.Errorf + %w 方式 |
