Go语言项目工程化 —— 日志、配置、错误处理规范

0 阅读3分钟

在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. 常见配置方式

类型示例说明
JSONconfig.json可读性强
YAMLconfig.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 方式