config

package
v2.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 23, 2026 License: MIT Imports: 17 Imported by: 0

README

fw/config

fw 专用配置库: 数据源仅 YAML 配置文件 与 环境变量, 替代 github.com/linxlib/config。

特性

  • 默认读取 config/config.yaml(相对工作目录), 仅接受 .yaml 后缀, 显式传 .yml/.json 直接报错;
  • 三种加载形态, target 可以是结构体、结构体的某个字段、甚至普通变量:
    • LoadWithKey("server", &opt) — 顶层 section;
    • LoadWithKey("server.port", &port) — 点号路径, 直接注入到任意变量;
    • LoadByTags(&opt) — 按字段上的 inject:"<section>" tag 批量注入(与 fw/inject 的 tag 语义一致, 支持 - 跳过);
  • 环境变量优先于 yaml: 显式 env:"XXX" tag, 或按 ENVPrefix(缺省 FW) 派生 FW_<SECTION>_<FIELD>;
  • 自动重载按 section 内容 hash 增量更新: 只有被修改的顶层 section 对应的内存配置会被重写, 回调只收到变化的 key; 文件未变化时零解码开销; 单个目标重载失败时回滚其旧值。

用法

import "github.com/linxlib/fw/config"

type ServerOpt struct {
    Host    string `yaml:"host" default:"0.0.0.0"`
    Port    int    `yaml:"port" default:"8080"`
    Timeout int    `yaml:"timeout" default:"30"`
}

func main() {
    c := config.New(&config.Option{
        AutoReload:         true,
        AutoReloadInterval: time.Second,
        AutoReloadCallback: func(key string, cfg interface{}) {
            // 只有 key 对应的 section 被修改时才会收到回调
        },
    }) // 缺省 Files = ["config/config.yaml"], ENVPrefix = "FW"

    var opt ServerOpt
    _ = c.LoadWithKey("server", &opt) // section 注入到结构体

    var port int
    _ = c.LoadWithKey("server.port", &port) // 点号路径注入普通变量

    c.Close() // 停止轮询
}

环境变量覆盖(优先级从高到低):

  1. 字段显式 env:"XXX" tag;
  2. <ENVPrefix>_<SECTION>_<FIELD> 派生(如 FW_SERVER_PORT, ENVPrefix 为 - 时跳过);
  3. <SECTION>_<FIELD> 无前缀派生。

内嵌结构体带 anonymous:"true" tag 时, 其字段的环境变量路径不包含结构体名。

tag 说明

tag 说明
yaml:"xxx" yaml 字段名
default:"xxx" 零值时填充的默认值(yaml 字面量)
required:"true" 缺失时报错
env:"XXX" 显式环境变量名
inject:"server" LoadByTags 时从 section server 注入; - 跳过
anonymous:"true" 内嵌结构体不进入 env 变量名路径

文件叠加

Files 按列表顺序叠加(后读的覆盖先读的)。若存在 config/config.<env>.yaml(环境取 Option.Environment → CONFIG_ENV → go test 为 test → 否则 development), 会叠加在 config/config.yaml 之后。

自动重载

开启 AutoReload 后, 由文件监听(平台相关)或每 AutoReloadInterval 的轮询触发检测:

  1. 文件 modtime 未变 → 直接跳过;
  2. 解析 yaml, 计算各顶层 section 的规范化 sha256, 与上次快照对比;
  3. 只对 变化/新增/删除 的 section 重新解码, 写回其已注册目标(全量目标 "" 随任一 section 变化刷新);
  4. 单个目标失败回滚其旧值, 其余目标不受影响; 成功后更新快照并在锁外触发 AutoReloadCallback(变化的 key, target);
  5. 检测到需要重载时在标准输出打印 config: reload detected, changed sections: [...], 列出本次发生变化的顶层 section(Silent: true 时不打印; 无变化时不打印)。

变更检测机制(平台相关):

  • Linux: 用 inotify 监听配置目录, 文件被写/创建/移动时即时触发增量重载, 无需等待轮询周期; 事件经 watchCh 合并突发(已有待处理信号时丢弃, reloadTick 幂等), inotify 不可用或无目录时静默回退轮询.
  • 非 Linux(含 Windows / macOS): 无 inotify, 完全依赖每 AutoReloadInterval 的轮询兜底, 行为与引入监听机制前一致.

也可手动触发: changed, err := c.Reload() 返回本次发生变化的 section 列表。

也可在 New 之后按需开启(幂等): c.StartAutoReload(time.Second), AutoReloadCallback 需在调用前设置; fw 引擎对应 e.EnableConfigReload(interval)。

Documentation

Overview

Package config 是 fw 专用的配置库.

数据源仅两种: YAML 配置文件(默认读取 config 目录下的 config.yaml, 只接受 .yaml 后缀) 与 环境变量. 支持三种加载形态:

  1. 显式 key: c.LoadWithKey("server", &opt) / c.LoadWithKey("server.port", &port), key 可以是顶层 section, 也可以是点号路径, target 可以是任意可寻址的值 (结构体指针, 父结构体的某个字段, 甚至普通变量);
  2. tag 驱动: c.LoadByTags(&opt) 按 struct 字段上的 inject:"<section>" tag 注入;
  3. 全量: c.Load(&opt) 等价 LoadWithKey("", &opt).

开启 AutoReload 后, 每个轮询周期只对内容发生变化的顶层 section 重新解码并 写回其关联的内存配置, 其余 section 的内存对象零扰动, 回调也只收到变化的 key. 检测到需要重载时会在标准输出打印 "config: reload detected, changed sections: [...]", 列出本次发生变化的顶层 section(Silent 模式下不输出).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func ENV added in v2.1.0

func ENV() string

ENV 返回当前运行环境(等价 New(nil).GetEnvironment()).

func Load

func Load(target any) error

Load 使用缺省文件 config/config.yaml 全量加载.

func LoadWithKey added in v2.1.0

func LoadWithKey(key string, target any) error

LoadWithKey 使用缺省文件 config/config.yaml 加载指定 key 的 section.

Types

type Config

type Config struct {
	*Option
	// contains filtered or unexported fields
}

Config 持有配置来源与所有已注册目标, 线程安全.

func New added in v2.1.0

func New(opts *Option) *Config

New 初始化一个 Config.

func (*Config) Close added in v2.1.0

func (c *Config) Close()

Close 停止自动重载轮询. 可重复调用.

func (*Config) GetEnvironment added in v2.1.0

func (c *Config) GetEnvironment() string

GetEnvironment 返回当前环境.

func (*Config) LastReloadedKeys added in v2.1.0

func (c *Config) LastReloadedKeys() int

LastReloadedKeys 返回最近一次重载周期中被重写的全局 key 数量(未开启重载时恒为 0). 主要用于测试与观测增量重载的实际影响面.

func (*Config) Load added in v2.1.0

func (c *Config) Load(target any) error

Load 等价 LoadWithKey("", target).

func (*Config) LoadByTags added in v2.1.0

func (c *Config) LoadByTags(target any) error

LoadByTags 按 target(struct 指针) 字段上的 inject tag 注入配置:

  • inject:"server" : 从顶层 section server 注入该字段;
  • inject:"server.port" : 点号路径注入;
  • inject:"" : 用字段名作为 section key;
  • inject:"-" / "_" : 跳过该字段.

每个被注入的字段都会按 (key, 字段地址) 登记, 自动重载时随对应 section 更新; 字段为指针类型且当前为 nil 时会先分配实例.

func (*Config) LoadWithKey added in v2.1.0

func (c *Config) LoadWithKey(key string, target any) error

LoadWithKey 将 YAML 中 key 指定的 section 解码到 target, 并登记 target 以便自动重载.

key 的取值:

  • "": 整个 YAML 映射解码到 target(全量);
  • "server": 顶层 section;
  • "server.port": 点号路径, 叶子值解码到 target, target 可以是任意可寻址类型.

target 必须是指针, 且指向可寻址的值(结构体、结构体字段或普通变量均可). YAML 缺失对应 section 时保持 target 现有值(含 default tag 填充的值)不变.

func (*Config) Reload added in v2.1.0

func (c *Config) Reload() ([]string, error)

Reload 立即执行一次增量重载, 返回本次发生变化的顶层 section 列表(可能为空). 与轮询共用同一套逻辑, 供外部按需触发与测试使用.

func (*Config) StartAutoReload added in v2.1.0

func (c *Config) StartAutoReload(interval time.Duration)

StartAutoReload 在运行时开启自动重载(幂等, 可重复调用).

适用于 New 时未开启 AutoReload、之后又需要热重载的场景: 已注册的目标会随对应 顶层 section 的变化被增量重写. interval <= 0 时按 1s 处理; 若轮询已启动则重复 调用不改变既有节奏. AutoReloadCallback 需在调用本方法之前设置.

type Option added in v2.1.0

type Option struct {
	// Files 配置文件列表, 按列表顺序叠加加载(后读的文件覆盖先读的).
	// 缺省为 ["config/config.yaml"]. 仅接受 .yaml 后缀, 显式传入 .yml/.json 会报错.
	Files []string
	// Environment 运行环境, 为空时依次取 CONFIG_ENV, go test 场景为 test, 否则 development.
	// 若存在 config/config.<env>.yaml 会叠加在其后的 config/config.yaml 之上.
	Environment string
	// ENVPrefix 环境变量前缀, 缺省 "FW". 字段无 env tag 时按 FW_<KEYPATH>_<FIELD> 派生候选变量名.
	ENVPrefix string
	Debug     bool
	Verbose   bool
	Silent    bool
	// AutoReload 开启按 AutoReloadInterval 的轮询增量重载.
	AutoReload bool
	// AutoReloadInterval 轮询间隔, 缺省 1s.
	AutoReloadInterval time.Duration
	// AutoReloadCallback 在某个 key 对应的内存配置被更新后, 针对每个受影响的
	// (key, target) 调用一次; key 只会是本次实际发生变化的顶层 section.
	AutoReloadCallback func(key string, config interface{})
	// FS 可选的文件系统, 便于 embed.FS / 测试场景, 缺省使用 os.
	FS fs.FS
}

Option 配置库选项.

type Section

type Section map[string]any

Section 是一份无 schema 的键值配置段(map[string]any), 提供大小写不敏感的取值.

适用于按名字注入的中间件/插件配置: 配置文件中没有对应段时它是一个空 Section, Get 返回零值, 调用方无需判空.

// config/app.yaml
// middlewares:
//   authorization:
//     api-key: "secret"

type AuthorizationMiddleware struct {
    Config *config.Section `inject:""`
}

func (m *AuthorizationMiddleware) Handle(...) error {
    if m.Config.Get("api-key") == "" { ... }
}

func NewSection

func NewSection(m map[string]any) Section

NewSection 由普通 map 构造 Section, key 统一归一化为小写去空白形式. 传入 nil 时返回空 Section(非 nil), 方便调用方直接取值.

func (Section) Get

func (s Section) Get(key string) string

Get 返回 key 对应的值的字符串形式, 缺失或为 nil 时返回 "". key 与 Section 内的 key 都按小写去空白比较, 因此 "api-key" / "API-Key" 等价.

func (Section) Has

func (s Section) Has(key string) bool

Has 判断 key 是否存在(同样大小写不敏感).

func (*Section) UnmarshalYAML

func (s *Section) UnmarshalYAML(value *yaml.Node) error

UnmarshalYAML 让 Section 可被 yaml.v3 直接解码, 并在解码后经 NewSection 归一化 key. 缺少本实现时 yaml 按 map 原样解码, key 会保留配置文件里的大小写, 导致 Get("api-key") 取不到 YAML 中写作 API-Key 的项. 注意 null 节点不会进入本方法 (yaml.v3 会提前短路), 此时 Section 保持零值 nil, 而 Get/Has 对 nil 依然安全.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL