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

在Go语言中，项目工程化的日志、配置、错误处理规范是保障项目可维护性、可观测性与健壮性的核心实践之一。本章将从三个方面进行详解：

一、日志规范

1. 日志的重要性

• 问题排查的唯一"现场还原"
• 性能瓶颈的定位手段
• 安全审计的依据

2. 日志库推荐

• 标准库 log：适合简单应用
• 社区常用库：
- • uber-go/zap：高性能，结构化日志（强烈推荐）
- • sirupsen/logrus：API 友好，易上手

3. zap日志初始化示例

go 复制代码

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. 使用结构化日志推荐

less 复制代码

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 读取配置示例

go 复制代码

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：

makefile 复制代码

app:
  port: 8080
  env: dev

db:
  dsn: "root:pass@tcp(127.0.0.1:3306)/demo"

4. 支持多环境配置

通过环境变量加载不同配置文件：

bash 复制代码

env := os.Getenv("APP_ENV") // dev / prod
viper.SetConfigName("config." + env)

三、错误处理规范

1. Go 的错误处理哲学

Go 不鼓励异常（try-catch），采用 显式返回 error，更清晰、稳定。

2. 标准写法

go 复制代码

result, err := doSomething()
if err != nil {
    log.Error("doSomething failed", zap.Error(err))
    return err
}

3. 自定义错误类型

go 复制代码

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 包：

go 复制代码

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）

go 复制代码

type APIError struct {
    Code    int    `json:"code"`
    Message string `json:"message"`
}

2. 自定义全局日志器/配置/错误包

arduino 复制代码

project/
├── pkg/
│   ├── logger/
│   ├── config/
│   └── errors/

pkg/logger/logger.go:

go 复制代码

var Logger *zap.Logger

func Init(logPath string) {
    // 初始化日志
}

五、总结

模块	工程化建议
日志	使用 zap，结构化输出，统一封装，支持级别/文件分割等
配置	使用 viper/yaml，支持环境变量，模块分离
错误	明确分层处理，业务错误自定义结构体，推荐使用 fmt.Errorf + %w 方式