配置系统

5 months ago
8a12b76

配置系统

go-web 的配置系统由两层组成:

  1. Env 层 (gsr.EnvReader) —— 由 Viper 提供,负责读取 config.yaml 与环境变量。环境变量自动把 _ 替换为 .,例如 DATABASE_HOST 对应 database.host。
  2. Config 层 (gsr.Provider) —— 内存中的配置中心,启动时由所有 InitConfig 实现填充默认值(默认值通常通过 helper.GetEnv().GetString("...", "默认值") 从 Env 层读取)。

业务代码通过 Config 层 读取配置,而不是直接访问 Env。这样做的好处:

  • 默认值集中声明在各 autoload/*.go 文件中
  • 业务测试时可以直接 cfg.Set(key, value) 覆盖,无需操作环境变量
  • Viper 行为(自动类型转换、监听等)被封装在 Env 层

InitConfig 接口

type InitConfig interface {
    InitConfig() map[string]any
}

每个 autoload/*.go 文件返回一个 map[string]any,所有键值会在装配阶段合并进 Config 层。

config/config.go 列出了所有要加载的 InitConfig:

func (receiver Config) Get() []interfaces.InitConfig {
    return []interfaces.InitConfig{
        autoload.App{},
        autoload.Cache{},
        autoload.Http{},
        autoload.StaticFs{},
        autoload.Database{},
        autoload.Redis{},
        autoload.Migration{},
        autoload.Middleware{},
        autoload.Router{},
    }
}

默认配置键速查

下表列出所有 autoload/*.go 中声明的配置键、默认值与对应的环境变量。

应用 (autoload/app.go)

键 默认值 环境变量 说明
app.app_name go-web-app APP_APP_NAME 应用名,用于日志/进程标识
app.mode debug APP_MODE debug / release,影响 Gin 模式与日志格式

数据库 (autoload/database.go)

键 默认值 环境变量
database.driver mysql DATABASE_DRIVER
database.host 127.0.0.1 DATABASE_HOST
database.port 3306 DATABASE_PORT
database.dbname test DATABASE_DBNAME
database.username test DATABASE_USERNAME
database.password 123456 DATABASE_PASSWORD

可选驱动:mysql、postgresql、sqlite、memory。详见「Driver Manager」章节。

Redis (autoload/redis.go)

键 默认值 环境变量
redis.host localhost REDIS_HOST
redis.port 6379 REDIS_PORT
redis.password `` REDIS_PASSWORD
redis.db 0 REDIS_DB

缓存 (autoload/cache.go)

键 默认值 环境变量 可选值
cache.driver none CACHE_DRIVER memory / redis / none

HTTP (autoload/http.go)

键 默认值 说明
http.load_static false 是否挂载静态资源
http.static_mode embed embed 使用 go:embed FS;disk 使用本地目录
http.static_dir [] 当 static_mode=disk 时的本地目录列表

静态资源 FS (autoload/static_fs.go)

键 类型 来源
static.fs map[string]embed.FS 由 cmd.WithWebStaticFs / cmd.WithTemplateFs 在启动时注入

路由 (autoload/router.go)

键 类型
http.router func(router httpInterfaces.RouterInterface)

详见「路由」章节。

中间件 (autoload/middleware.go)

键 类型
http.middleware []httpInterfaces.MiddlewareFunc

数据库迁移 (autoload/migration.go)

键 默认值 环境变量
database.migration.dir migrations DATABASE_MIGRATION_DIR

在业务代码中读取配置

import "cnb.cool/mliev/open/go-web/pkg/helper"

cfg := helper.GetConfig()
appName := cfg.GetString("app.app_name", "fallback")
port := cfg.GetInt("database.port", 3306)
debug := cfg.GetBool("app.mode") == "debug"

helper.GetConfig() 返回 gsr.Provider,常用方法包括 GetString / GetInt / GetBool / GetFloat / Get / Set。

如果需要直接读取环境变量(例如某个不通过 Config 层管理的临时开关):

env := helper.GetEnv()
val := env.GetString("MY_CUSTOM_VAR", "default")

添加新配置键

  1. 在 config/autoload/ 创建新文件,实现 InitConfig 接口
  2. 在 config/config.go 的 Get() 列表中追加这个 InitConfig
  3. 在业务代码中通过 helper.GetConfig().GetString(...) 读取
// config/autoload/oss.go
package autoload

import "cnb.cool/mliev/open/go-web/pkg/helper"

type Oss struct{}

func (Oss) InitConfig() map[string]any {
    return map[string]any{
        "oss.endpoint":   helper.GetEnv().GetString("oss.endpoint", ""),
        "oss.access_key": helper.GetEnv().GetString("oss.access_key", ""),
        "oss.secret_key": helper.GetEnv().GetString("oss.secret_key", ""),
        "oss.bucket":     helper.GetEnv().GetString("oss.bucket", ""),
    }
}
// config/config.go(追加)
return []interfaces.InitConfig{
    // ...
    autoload.Oss{},
}

环境变量优先级

环境变量始终覆盖 config.yaml。优先级:

进程环境变量  >  config.yaml  >  InitConfig 中的硬编码默认值

这一规则使得在 Docker / Kubernetes 中通过环境变量注入配置成为最自然的方式——无需修改任何 yaml 文件或代码。