Documentation
¶
Overview ¶
Package config 是 fw 专用的配置库.
数据源仅两种: YAML 配置文件(默认读取 config 目录下的 config.yaml, 只接受 .yaml 后缀) 与 环境变量. 支持三种加载形态:
- 显式 key: c.LoadWithKey("server", &opt) / c.LoadWithKey("server.port", &port), key 可以是顶层 section, 也可以是点号路径, target 可以是任意可寻址的值 (结构体指针, 父结构体的某个字段, 甚至普通变量);
- tag 驱动: c.LoadByTags(&opt) 按 struct 字段上的 inject:"<section>" tag 注入;
- 全量: c.Load(&opt) 等价 LoadWithKey("", &opt).
开启 AutoReload 后, 每个轮询周期只对内容发生变化的顶层 section 重新解码并 写回其关联的内存配置, 其余 section 的内存对象零扰动, 回调也只收到变化的 key. 检测到需要重载时会在标准输出打印 "config: reload detected, changed sections: [...]", 列出本次发生变化的顶层 section(Silent 模式下不输出).
Index ¶
- func ENV() string
- func Load(target any) error
- func LoadWithKey(key string, target any) error
- type Config
- func (c *Config) Close()
- func (c *Config) GetEnvironment() string
- func (c *Config) LastReloadedKeys() int
- func (c *Config) Load(target any) error
- func (c *Config) LoadByTags(target any) error
- func (c *Config) LoadWithKey(key string, target any) error
- func (c *Config) Reload() ([]string, error)
- func (c *Config) StartAutoReload(interval time.Duration)
- type Option
- type Section
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func LoadWithKey ¶ added in v2.1.0
LoadWithKey 使用缺省文件 config/config.yaml 加载指定 key 的 section.
Types ¶
type Config ¶
type Config struct {
*Option
// contains filtered or unexported fields
}
Config 持有配置来源与所有已注册目标, 线程安全.
func (*Config) GetEnvironment ¶ added in v2.1.0
GetEnvironment 返回当前环境.
func (*Config) LastReloadedKeys ¶ added in v2.1.0
LastReloadedKeys 返回最近一次重载周期中被重写的全局 key 数量(未开启重载时恒为 0). 主要用于测试与观测增量重载的实际影响面.
func (*Config) LoadByTags ¶ added in v2.1.0
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
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
Reload 立即执行一次增量重载, 返回本次发生变化的顶层 section 列表(可能为空). 与轮询共用同一套逻辑, 供外部按需触发与测试使用.
func (*Config) StartAutoReload ¶ added in v2.1.0
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 any)
// FS 可选的文件系统, 便于 embed.FS / 测试场景, 缺省使用 os.
FS fs.FS
}
Option 配置库选项.
type Section ¶
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 ¶
NewSection 由普通 map 构造 Section, key 统一归一化为小写去空白形式. 传入 nil 时返回空 Section(非 nil), 方便调用方直接取值.
func (Section) Get ¶
Get 返回 key 对应的值的字符串形式, 缺失或为 nil 时返回 "". key 与 Section 内的 key 都按小写去空白比较, 因此 "api-key" / "API-Key" 等价.
func (*Section) UnmarshalYAML ¶
UnmarshalYAML 让 Section 可被 yaml.v3 直接解码, 并在解码后经 NewSection 归一化 key. 缺少本实现时 yaml 按 map 原样解码, key 会保留配置文件里的大小写, 导致 Get("api-key") 取不到 YAML 中写作 API-Key 的项. 注意 null 节点不会进入本方法 (yaml.v3 会提前短路), 此时 Section 保持零值 nil, 而 Get/Has 对 nil 依然安全.