1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// pkg/errcode/common.go
package code

// 定义常用通用错误码
// 这些变量是全局的、不可变的“标准辞令”
var (
    Success         = NewError(0, "成功")
    ServerError     = NewError(10000000, "服务内部错误")
    InvalidParams   = NewError(10000001, "参数错误")
    NotFound        = NewError(10000002, "资源不存在")
    Unauthorized    = NewError(10000003, "鉴权失败")
    TooManyRequests = NewError(10000004, "请求过于频繁")
)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

// pkg/code/error.go
package code

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
)

// Error 定义了标准错误结构。
// 它是我们与客户端沟通的“外交辞令”的统一格式。
type Error struct {
	Code    int      `json:"code"`
	Msg     string   `json:"msg"`
	Details []string `json:"details,omitempty"` // omitempty: 如果 details 为空, JSON序列化时会忽略此字段
}

// codes 是一个全局的错误码注册表，确保唯一性。
var codes = map[int]string{}

// NewError 创建一个新的错误码实例，并将其注册到全局表中。
// 这是我们错误码的“户籍管理员”，在应用启动时调用，如果错误码重复会 panic。
func NewError(code int, msg string) *Error {
	if _, ok := codes[code]; ok {
		panic(fmt.Sprintf("错误码 %d 已经存在，请更换一个", code))
	}
	codes[code] = msg
	return &Error{Code: code, Msg: msg}
}

// Error 实现了标准库的 error 接口，让 *Error 可以像普通 error 一样使用。
func (e *Error) Error() string {
	return fmt.Sprintf("错误码：%d, 错误信息：%s", e.Code, e.Msg)
}

// WithDetails 返回一个带有详细信息的新 Error 对象副本。
// 采用“复印机”模式，保证全局错误变量的不可变性。
func (e *Error) WithDetails(details ...string) *Error {
	// 创建副本，而不是修改原始的全局变量
	newError := *e
	newError.Details = append(newError.Details, details...)
	return &newError
}

// WithMessagef 返回一个带有格式化消息的新 Error 对象副本。
func (e *Error) WithMessagef(format string, args ...interface{}) *Error {
	newError := *e
	newError.Msg = fmt.Sprintf(format, args...)
	return &newError
}

// StatusCode 将内部错误码转换为标准的 HTTP 状态码。
// 扮演“翻译官”的角色。
func (e *Error) StatusCode() int {
	switch e.Code {
	case Success.Code:
		return http.StatusOK
	case ServerError.Code:
		return http.StatusInternalServerError
	case InvalidParams.Code:
		return http.StatusBadRequest
	case Unauthorized.Code:
		return http.StatusUnauthorized
	case NotFound.Code:
		return http.StatusNotFound
	case TooManyRequests.Code:
		return http.StatusTooManyRequests
	default:
		// 对于未明确定义的业务错误码，返回 500 是一个相对安全的选择
		return http.StatusInternalServerError
	}
}

// ToJSON 是一个工具函数，将 Error 对象转换为 JSON 字节切片。
func (e *Error) ToJSON() []byte {
	b, err := json.Marshal(e)
	if err != nil {
		// 在一个简单的结构体上序列化几乎不可能失败，
		// 但在生产环境中，记录这个意外的错误是一个好习惯。
		log.Printf("序列化错误码到JSON时出错: %v", err)
		return nil
	}
	return b
}

1

go get github.com/spf13/viper

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# config/dev.yaml - 我们应用的“控制面板”布局

# 服务相关的旋钮
server:
  port: 8081          # HTTP 监听端口
  read_timeout: 60    # 读取超时（秒）
  write_timeout: 60   # 写入超时（秒）

# 应用相关的开关
app:
  default_page_size: 20
  max_page_size: 100
  log_save_path: storage/logs
  log_file_name: app
  log_file_ext: .log

# 数据库连接线
db:
  dsn: "root:123456@tcp(127.0.0.1:3306)/db_user?charset=utf8mb4&parseTime=True&loc=Local"

# 本地化/国际化设置
locale: "zh"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// config/types.go
package config

// mgrConfig 是我们“控制面板”在程序内部的完整映射。
// `mapstructure` 标签是 Viper 用来识别和映射 YAML 字段的关键。
type mgrConfig struct {
	Server serverConfig `mapstructure:"server"`
	App    appConfig    `mapstructure:"app"`
	DB     DBConfig     `mapstructure:"db"`
}

type serverConfig struct {
	Port         int `mapstructure:"port"`
	ReadTimeout  int `mapstructure:"read_timeout"`
	WriteTimeout int `mapstructure:"write_timeout"`
}

type appConfig struct {
	DefaultPageSize int    `mapstructure:"default_page_size"`
	MaxPageSize     int    `mapstructure:"max_page_size"`
	LogSavePath     string `mapstructure:"log_save_path"`
	LogFileName     string `mapstructure:"log_file_name"`
	LogFileExt      string `mapstructure:"log_file_ext"`
}

type DBConfig struct {
	DSN string `mapstructure:"dsn"`
}

1
2
3
4
5
6

// config/config.go
package config

// MgrConfig 是一个全局的配置实例，程序的任何地方都可以通过它来读取配置。
// 它就像一个公开的“中央仪表盘”。
var MgrConfig = &mgrConfig{}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

// ioc/config.go
package ioc

import (
	"log"

	"einscat.com/user-mgr/config"

	"github.com/fsnotify/fsnotify"
	"github.com/spf13/viper"
)

// InitConfig 负责在应用启动时加载和解析配置文件。
func InitConfig() {
	// 优先从环境变量中读取配置路径，提供灵活性
	viper.SetDefault("CONFIG_PATH", "config/dev.yaml")
	viper.AutomaticEnv()
	configPath := viper.GetString("CONFIG_PATH")

	v := viper.New()
	v.SetConfigFile(configPath)
	v.SetConfigType("yaml") // 明确配置文件类型

	// 1. 首次读取配置
	if err := v.ReadInConfig(); err != nil {
		panic(fmt.Errorf("致命错误: 无法读取配置文件: %s", err))
	}

	// 2. 将配置解析到全局结构体中
	if err := v.Unmarshal(config.MgrConfig); err != nil {
		panic(fmt.Errorf("致命错误: 无法解析配置: %s", err))
	}
	
	log.Printf("配置加载成功, Port: %d", config.MgrConfig.Server.Port)

	// 3. 设置并启动配置热更新监控
	go watchConfig(v)
}

// watchConfig 封装了热更新的逻辑
func watchConfig(v *viper.Viper) {
    v.WatchConfig()
	v.OnConfigChange(func(e fsnotify.Event) {
		log.Printf("检测到配置文件变动: %s", e.Name)
		
        // 重新读取和解析
		if err := v.ReadInConfig(); err != nil {
			log.Printf("热更新失败: 无法重新读取配置, %v", err)
			return // 读取失败，保留旧配置
		}
		if err := v.Unmarshal(config.MgrConfig); err != nil {
			log.Printf("热更新失败: 无法重新解析配置, %v", err)
			return // 解析失败，保留旧配置
		}
		
		log.Printf("配置已成功热更新! 新的 Port: %d", config.MgrConfig.Server.Port)
	})
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

// main.go (保持不变)
package main

import (
	"fmt"
	"net/http"

	"einscat.com/user-mgr/config"
	"einscat.com/user-mgr/ioc"

	"github.com/gin-gonic/gin"
)

func main() {
	// 在应用启动时，首先加载所有配置
	ioc.InitConfig()

	r := gin.Default()
	r.GET("/ping", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{
			"message": "pong from user-mgr!",
		})
	})
	
	// 从我们加载好的全局配置中读取端口号
	port := config.MgrConfig.Server.Port
	r.Run(fmt.Sprintf(":%d", port))
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

package config

// 引入viper配置模块后在字段中引入 mapstructure 标签
type Mgr struct {
	Server serverConfig `mapstructure:"server" json:"server"`
	App    appConfig    `mapstructure:"app" json:"app"`
	DB     DBConfig     `mapstructure:"db" json:"db"`
}

type serverConfig struct {
	Port         int    `mapstructure:"port" json:"port"`
	ReadTimeout  int    `mapstructure:"read_timeout" json:"read_timeout"`
	WriteTimeout int    `mapstructure:"write_timeout" json:"write_timeout"`
	Locale       string `mapstructure:"locale" json:"locale"`
}

type appConfig struct {
	DefaultPageSize int    `mapstructure:"default_page_size" json:"default_page_size"`
	MaxPageSize     int    `mapstructure:"max_page_size" json:"max_page_size"`
	LogSavePath     string `mapstructure:"log_save_path" json:"log_save_path"`
	LogFileName     string `mapstructure:"log_file_name" json:"log_file_name"`
	LogFileExt      string `mapstructure:"log_file_ext" json:"log_file_ext"`
}

type DBConfig struct {
	DSN string `mapstructure:"dsn" json:"dsn"`
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80

package ioc

import (
	"fmt"
	"log"
	"sync/atomic"

	"einscat.com/user-mgr/config"

	"github.com/fsnotify/fsnotify"
	"github.com/spf13/viper"
)

// ConfigManager 负责管理应用的配置，包括加载和热更新
type ConfigManager struct {
	// 使用 atomic.Pointer 来安全地持有和交换配置指针
	p atomic.Pointer[config.Mgr]
}

// NewConfigManager 创建一个新的配置管理器实例
func NewConfigManager(configPath string) (*ConfigManager, error) {
	// 1. 加载初始配置
	initialConfig, err := loadConfig(configPath)
	if err != nil {
		return nil, err
	}

	cm := &ConfigManager{}
	cm.p.Store(initialConfig) // 存储初始配置

	log.Println("配置初始化成功")

	// 2. 启动一个 goroutine 来监控配置文件变动
	go cm.watch(configPath)

	return cm, nil
}

// Get 返回当前最新的配置
func (cm *ConfigManager) Get() *config.Mgr {
	return cm.p.Load()
}

// watch 监控配置文件，并在变动时热更新
func (cm *ConfigManager) watch(configPath string) {
	v := viper.New()
	v.SetConfigFile(configPath)

	v.WatchConfig()
	v.OnConfigChange(func(e fsnotify.Event) {
		log.Printf("检测到配置文件变动: %s", e.Name)

		newConfig, err := loadConfig(configPath)
		if err != nil {
			log.Printf("热更新失败: 无法加载新配置, %v", err)
			return // 加载失败，继续使用旧配置
		}

		// 原子地替换指针，所有调用 Get() 的地方都会立即获得新配置
		cm.p.Store(newConfig)
		log.Println("配置已成功热更新!")
	})
}

// loadConfig 是一个辅助函数，用于从指定路径加载配置
func loadConfig(configPath string) (*config.Mgr, error) {
	v := viper.New()
	v.SetConfigFile(configPath)
	v.SetConfigType("yaml")

	if err := v.ReadInConfig(); err != nil {
		return nil, fmt.Errorf("无法读取配置文件: %w", err)
	}

	var cfg config.Mgr
	if err := v.Unmarshal(&cfg); err != nil {
		return nil, fmt.Errorf("无法解析配置: %w", err)
	}
	return &cfg, nil
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

// main.go (最终组装)
package main

import (
	"log"
	// ... 其他导入
	"einscat.com/user-mgr/ioc"
)

func main() {
	// 1. 初始化配置管理器
	// 配置路径可以从环境变量或命令行参数获取，这里简化为硬编码
	configPath := "config/dev.yaml"
	cfgManager, err := ioc.NewConfigManager(configPath)
	if err != nil {
		log.Fatalf("启动失败: 初始化配置管理器时出错: %v", err)
	}

	// 2. 初始化数据库连接
	// 通过 cfgManager.Get() 获取当前配置，并把 DB 部分注入到 InitDB 中
	db, err := ioc.InitDB(cfgManager.Get().DB)
	if err != nil {
		log.Fatalf("启动失败: 初始化数据库时出错: %v", err)
	}
	
	// 3. 初始化日志 (同理)
	// logger := ioc.InitLogger(cfgManager.Get().App)
	
	// 4. 初始化业务服务，注入它需要的依赖 (例如 db)
	// userRepository := repository.NewUserRepository(db)
	// userService := service.NewUserService(userRepository)

	// 5. 初始化 Gin 引擎和路由，注入服务
	// ...

	// 在 Gin 的 Handler 中，如何使用最新的配置？
	// r := gin.Default()
	// r.GET("/some-api", func(c *gin.Context) {
	//     // 每次请求时，都从 Manager 获取最新的配置
	//     latestConfig := cfgManager.Get()
	//     pageSize := latestConfig.App.DefaultPageSize
	//     // ... 使用最新的 pageSize
	// })

	log.Printf("服务即将启动于端口: %d", cfgManager.Get().Server.Port)
	// http.ListenAndServe(fmt.Sprintf(":%d", cfgManager.Get().Server.Port), r)
}

1
2

go get -u go.uber.org/zap
go get -u gopkg.in/natefinch/lumberjack.v2

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

// ioc/logger.go
package ioc

import (
  "os"

  "einscat.com/user-mgr/config" // 假设我们 DI 了配置
  "go.uber.org/zap"
  "go.uber.org/zap/zapcore"
  "gopkg.in/natefinch/lumberjack.v2"
)

// 全局 Logger 实例
// 在 DI 模式下，我们会将它注入到需要的地方
var Logger *zap.Logger

// InitLogger 根据传入的 AppConfig 初始化“黑匣子”
// 它不再操作全局变量，而是返回一个配置好的 Logger 实例
func InitLogger(cfg config.AppConfig) (*zap.Logger, error) {
	// 1. 设置日志写入器 (Writer)，使用 Lumberjack 进行归档
	writer := getLogWriter(cfg)

	// 2. 设置日志编码器 (Encoder)，决定日志的格式
	encoder := getEncoder()

	// 3. 设置日志级别 (可以从配置中读取，这里简化为 Debug)
	logLevel := zapcore.DebugLevel

	// 4. 创建核心 (Core)，组合了写入器、编码器和级别
	core := zapcore.NewCore(encoder, writer, logLevel)

	// 5. 创建 Logger 实例
	// zap.AddCaller() 会自动添加调用者的文件和行号信息
	logger := zap.New(core, zap.AddCaller())

	return logger, nil
}

// getEncoder 负责设置日志的编码格式
func getEncoder() zapcore.Encoder {
	// 使用 zap 预置的 JSON 编码器配置
	encoderConfig := zap.NewProductionEncoderConfig()
	// 自定义时间格式
	encoderConfig.EncodeTime = zapcore.ISO8601TimeEncoder
	// 日志级别使用大写
	encoderConfig.EncodeLevel = zapcore.CapitalLevelEncoder

	return zapcore.NewJSONEncoder(encoderConfig)
}

// getLogWriter 负责设置日志的写入位置和归档策略
func getLogWriter(cfg config.AppConfig) zapcore.WriteSyncer {
  // 使用 Lumberjack 进行日志归档
  lumberjackLogger := &lumberjack.Logger{
    Filename:   cfg.LogSavePath + "/" + cfg.LogFileName + cfg.LogFileExt,
    MaxSize:    100,  // 单个日志文件的最大大小 (MB)
    MaxBackups: 5,    // 最多保留的旧日志文件数
    MaxAge:     30,   // 旧日志文件的最大保留天数
    Compress:   false, // 是否压缩旧日志文件
  }

  // 同时输出到控制台和文件
  return zapcore.NewMultiWriteSyncer(
    zapcore.AddSync(os.Stdout),
    zapcore.AddSync(lumberjackLogger),
  )
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

// main.go
// main.go (使用 zap 全局 logger 的最终版本)
package main

import (
	"fmt"
	"log"
	"net/http"

	"einscat.com/user-mgr/config"
	"einscat.com/user-mgr/ioc" // 我们只依赖 ioc 来做初始化
	"go.uber.org/zap"          // 引入 zap
)

func main() {
	// 1. 初始化配置管理器
	configPath := "config/dev.yaml"
	cfgManager, err := ioc.NewConfigManager(configPath)
	if err != nil {
		log.Fatalf("启动失败: 初始化配置管理器时出错: %v", err)
	}

	// 2. 初始化日志模块
	// 我们从配置管理器中获取 App 相关的配置，并注入给日志初始化函数
	logger, err := ioc.InitLogger(cfgManager.Get().App)
	if err != nil {
		log.Fatalf("启动失败: 初始化日志模块时出错: %v", err)
	}
	
	// 3. 【核心】将我们创建的 logger 实例替换为 zap 的全局 logger
	zap.ReplaceGlobals(logger)
	
	// 4. 现在，可以在应用的任何地方通过 zap.L() 或 zap.S() 使用了
	zap.L().Info("服务启动中...",
		zap.Int("port", cfgManager.Get().Server.Port),
		zap.String("locale", cfgManager.Get().Locale),
	)
	
	// 5. 初始化 Gin 引擎和路由
	r := gin.Default()
	r.GET("/ping", func(c *gin.Context) {
		// 在 handler 中使用 zap 的全局 logger
		// 使用 zap.L() 记录结构化、强类型的日志
		zap.L().Debug("收到一个 ping 请求", zap.String("client_ip", c.ClientIP()))
		
		// 或者使用 zap.S() 记录更自由格式的日志
		zap.S().Infof("客户端IP为: %s", c.ClientIP())

		c.JSON(http.StatusOK, gin.H{
			"message": "pong from user-mgr!",
		})
	})
	
	// 从配置管理器获取最新端口号
	port := cfgManager.Get().Server.Port
	zap.S().Infof("HTTP 服务即将监听于端口: %d", port)
	r.Run(fmt.Sprintf(":%d", port))
}

1
2

{"level":"INFO","ts":"2025-09-16T12:00:00.000Z","caller":"main.go:25","msg":"服务启动中...","port":8081,"locale":"zh"}
{"level":"DEBUG","ts":"2025-09-16T12:00:05.123Z","caller":"main.go:32","msg":"收到一个 ping 请求","client_ip":"::1"}

1
2

go get -u gorm.io/gorm
go get -u gorm.io/driver/mysql

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

package ioc

import (
  "log"
  "os"
  "time"

  "einscat.com/user-mgr/config"
  
  "gorm.io/driver/mysql"
  "gorm.io/gorm"
  "gorm.io/gorm/logger"
  "gorm.io/gorm/schema"
)

func InitDB(cfg config.DBConfig) *gorm.DB {
  // 设置全局的 logger，这个 logger 在执行每个 SQL 的时候会打印每一行 SQL
  newLogger := logger.New(
    log.New(os.Stdout, "\r\n", log.LstdFlags),
    logger.Config{
      SlowThreshold: time.Second, // 慢 SQL 阈值
      LogLevel:      logger.Info, // 日志级别
      Colorful:      true,        // 禁用彩色打印
    },
  )

  dsn := cfg.DSN
  db, err := gorm.Open(mysql.Open(dsn), &gorm.Config{
    NamingStrategy: schema.NamingStrategy{
      SingularTable: true, // 设置是否自动在表尾处添加s，true不添加
    },
    Logger: newLogger,
  })
  if err != nil {
    panic("连接数据库失败!!!")
  }

  return db
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

func main() {
	// 1. 初始化配置管理器
	// 配置路径可以从环境变量或命令行参数获取，这里简化为硬编码
	configPath := "config/dev.yaml"
	cfgManager, err := ioc.NewConfigManager(configPath)
	if err != nil {
		log.Fatalf("启动失败: 初始化配置管理器时出错: %v", err)
	}

	// 2. 初始化日志模块，并将实例存放到全局变量中
	// 我们从配置管理器中获取 App 相关的配置，并注入给日志初始化函数
	logger, err := ioc.InitLogger(cfgManager.Get().App)
	if err != nil {
		log.Fatalf("启动失败: 初始化日志模块时出错: %v", err)
	}
	// 3. 【核心】将我们创建的 logger 实例替换为 zap 的全局 logger
	zap.ReplaceGlobals(logger)

	// 4. 现在，可以在应用的任何地方通过 zap.L() 或 zap.S() 使用了
	zap.L().Info("服务启动中...",
		zap.Int("port", cfgManager.Get().Server.Port),
		zap.String("locale", cfgManager.Get().Server.Locale),
	)

	// 通过 cfgManager.Get() 获取当前配置，并把 DB 部分注入到 InitDB 中
  _, err = ioc.InitDB(cfgManager.Get().DB)
  if err != nil {
    log.Fatalf("启动失败: 初始化数据库时出错: %v", err)
  }

	r := gin.Default()
	r.GET("/ping", func(c *gin.Context) {
		c.JSON(http.StatusOK, gin.H{
			"message": "pong from user-mgr!",
		})
	})

	// 从配置管理器获取最新端口号
	port := cfgManager.Get().Server.Port
	r.Run(fmt.Sprintf(":%d", port))
}