Documentation
¶
Overview ¶
Package config provides environment normalization utilities for gorp framework. Standardizes environment names: dev/test/prod.
配置包提供 gorp 框架的环境名规范化工具。 统一环境名约定：dev/test/prod。
Package config provides multi-key configuration lookup utilities. Supports fallback across multiple config keys, useful for backward compatibility.
配置包提供多键配置查找工具。 支持在多个配置键之间回退查找，适用于向后兼容场景。
Package config provides configuration service for gorp framework. Supports multiple config sources: local files, environment variables, remote config. Implements layered loading: base files + env overlay + env directory + env vars.
配置服务包，提供 gorp 框架的配置能力。 支持多种配置源：本地文件、环境变量、远程配置。 实现分层加载：基础文件 + 环境覆盖文件 + 环境目录 + 环境变量。
Package config provides configuration service implementation for gorp framework. Implements Config contract with viper-based layered loading. Supports YAML, environment variables, env(KEY) placeholders, and config source extension.
配置服务包，提供 gorp 框架的配置服务实现。 基于 viper 实现分层加载的 Config 契约。 支持 YAML、环境变量、env(KEY) 占位符和配置源扩展。
Index ¶
- Constants
- func GetAny(cfg datacontract.Config, keys ...string) (any, bool)
- func GetBoolAny(cfg datacontract.Config, keys ...string) (bool, bool)
- func GetFloatAny(cfg datacontract.Config, keys ...string) float64
- func GetIntAny(cfg datacontract.Config, keys ...string) int
- func GetStringAny(cfg datacontract.Config, keys ...string) string
- func GetStringMapAny(cfg datacontract.Config, keys ...string) map[string]string
- func GetStringSliceAny(cfg datacontract.Config, keys ...string) []string
- func LoadLocalConfigToViper(v *viper.Viper, env, root string) error
- func NormalizeEnv(env string) string
- type Provider
- type Service
- func (s *Service) Env() string
- func (s *Service) Get(key string) any
- func (s *Service) GetBool(key string) bool
- func (s *Service) GetFloat(key string) float64
- func (s *Service) GetInt(key string) int
- func (s *Service) GetString(key string) string
- func (s *Service) Load(env string) error
- func (s *Service) Reload(ctx context.Context) error
- func (s *Service) Unmarshal(key string, out any) error
- func (s *Service) Watch(ctx context.Context, key string) (datacontract.ConfigWatcher, error)
Constants ¶
const ( EnvDev = "dev" EnvTest = "test" EnvProd = "prod" )
Variables ¶
This section is empty.
Functions ¶
func GetAny ¶
func GetAny(cfg datacontract.Config, keys ...string) (any, bool)
GetAny returns the first existing configuration value from multiple keys. Iterates through keys in order, returns first non-nil value. Core logic: Validate config, iterate keys, return first match.
GetAny 从多个键中返回第一个存在的配置值。 按顺序遍历键，返回第一个非 nil 的值。 核心逻辑：验证配置对象、遍历键、返回首个匹配。
func GetBoolAny ¶
func GetBoolAny(cfg datacontract.Config, keys ...string) (bool, bool)
GetBoolAny returns the first parseable boolean configuration and existence flag. Supports bool, string, int, int64, float64 types. Core logic: Iterate keys, parse to bool, return value and existence.
GetBoolAny 返回第一个可解析布尔配置及是否存在标志。 支持 bool、string、int、int64、float64 类型。 核心逻辑：遍历键、解析为布尔值、返回值和存在标志。
func GetFloatAny ¶
func GetFloatAny(cfg datacontract.Config, keys ...string) float64
GetFloatAny returns the first parseable float configuration from multiple keys. Handles float64, float32, int, int64, string types. Core logic: Iterate keys, parse to float, return first valid.
GetFloatAny 从多个键中返回第一个可解析浮点配置。 处理 float64、float32、int、int64、string 类型。 核心逻辑：遍历键、解析为浮点数、返回首个有效值。
func GetIntAny ¶
func GetIntAny(cfg datacontract.Config, keys ...string) int
GetIntAny returns the first parseable integer configuration from multiple keys. Handles int, int64, float64, string types. Core logic: Iterate keys, parse to int, return first valid.
GetIntAny 从多个键中返回第一个可解析整数配置。 处理 int、int64、float64、string 类型。 核心逻辑：遍历键、解析为整数、返回首个有效值。
func GetStringAny ¶
func GetStringAny(cfg datacontract.Config, keys ...string) string
GetStringAny returns the first non-empty string configuration from multiple keys. Handles string conversion for various types. Core logic: Iterate keys, trim whitespace, return first non-empty.
GetStringAny 从多个键中返回第一个非空字符串配置。 处理各种类型的字符串转换。 核心逻辑：遍历键、去除空白、返回首个非空值。
func GetStringMapAny ¶
func GetStringMapAny(cfg datacontract.Config, keys ...string) map[string]string
GetStringMapAny returns the first string map configuration from multiple keys. Handles map[string]string, map[string]any with proper conversion. Core logic: Iterate keys, convert to map[string]string, return first found.
GetStringMapAny 从多个键中返回第一个字符串 map 配置。 处理 map[string]string、map[string]any 类型并进行适当转换。 核心逻辑：遍历键、转换为 map[string]string、返回首个找到的。
func GetStringSliceAny ¶
func GetStringSliceAny(cfg datacontract.Config, keys ...string) []string
GetStringSliceAny returns the first string slice configuration from multiple keys. Handles []string, []any, string types with proper conversion. Core logic: Iterate keys, convert to []string, return first non-empty.
GetStringSliceAny 从多个键中返回第一个字符串切片配置。 处理 []string、[]any、string 类型并进行适当转换。 核心逻辑：遍历键、转换为 []string、返回首个非空。
func LoadLocalConfigToViper ¶
LoadLocalConfigToViper loads local config files to specified viper instance. Shared by Config provider and ConfigSource.local provider. Core logic: Discover base files, merge env overlay, apply env substitution.
LoadLocalConfigToViper 将本地配置文件加载到指定 viper 实例。 由 Config provider 和 ConfigSource.local provider 共用。 核心逻辑：发现基础文件、合并环境覆盖、应用环境变量替换。
func NormalizeEnv ¶
NormalizeEnv normalizes environment name to framework standard. Accepts dev/test/prod and empty string (defaults to dev). Core logic: Trim whitespace, lowercase, map empty to dev.
NormalizeEnv 将环境名规范化为框架统一标准。 接受 dev/test/prod 和空字符串（默认为 dev）。 核心逻辑：去除空白、小写化、空值映射到 dev。
Types ¶
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider registers the configuration service contract. Reads config from "config.yaml" by default, with layered overlay support. Core logic: Bind Service instance, load config in Boot phase.
Provider 注册配置服务契约。 默认从 "config.yaml" 读取配置，支持分层覆盖。 核心逻辑：绑定 Service 实例、在 Boot 阶段加载配置。
func NewProvider ¶
func NewProvider() *Provider
NewProvider creates a new config provider with initialized service instance.
NewProvider 创建新的配置 provider，初始化服务实例。
func (*Provider) Boot ¶
func (p *Provider) Boot(runtimecontract.Container) error
Boot loads configuration content based on APP_ENV environment variable. Core logic: Normalize env, load layered config files, apply env vars.
Boot 根据 APP_ENV 环境变量装载配置内容。 核心逻辑：规范化环境名、加载分层配置文件、应用环境变量。
func (*Provider) DependsOn ¶
DependsOn returns the keys this provider depends on. Config provider has no dependencies - it's a root provider.
DependsOn 返回该 provider 依赖的 key。 Config provider 无依赖，是根 provider。
func (*Provider) IsDefer ¶
IsDefer indicates config provider should not defer loading. Config must be loaded before other providers that depend on it.
IsDefer 表示配置 provider 不应延迟加载。 配置必须在其他依赖它的 provider 之前加载。
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service is the default config service implementation based on viper. Supports YAML, layered overlay, environment variable override, and env(KEY) placeholder replacement. Supports config source extension (local files/remote config). Core logic: Hold viper instance, delegate Get/Unmarshal operations.
Service 是基于 viper 的默认配置服务实现。 支持 YAML、分层覆盖、环境变量覆盖与 env(KEY) 占位符替换。 支持配置源扩展（本地文件/远程配置）。 核心逻辑：持有 viper 实例、委托 Get/Unmarshal 操作。
func NewService ¶
func NewService() *Service
func NewServiceWithSource ¶
func NewServiceWithSource(source datacontract.ConfigSource) *Service
NewServiceWithSource 创建带配置源的 Service。
中文说明： - 支持远程配置源（Consul KV / etcd）； - 本地文件优先，远程配置覆盖。
func (*Service) Load ¶
Load loads configuration in a fixed order for deterministic results. Order: local files + config source + environment variables. Core logic: Normalize env, load base files, merge env overlay, apply env vars.
Load 按固定顺序加载配置，确保确定性结果。 顺序：本地文件 + 配置源 + 环境变量。 核心逻辑：规范化环境名、加载基础文件、合并环境覆盖、应用环境变量。
func (*Service) Reload ¶
Reload forces reload of configuration from all sources. Core logic: Reload from remote source first, then reload local files. The remote config I/O is performed outside the lock to avoid blocking other readers. The remote config is then applied inside the lock using LoadOrStore pattern to prevent TOCTOU races where another goroutine could replace s.v between the I/O and the merge.
Reload 强制重新加载配置。 核心逻辑：先从远程源重新加载，然后重新加载本地文件。 远程配置 I/O 在锁外执行以避免阻塞其他读取者。 远程配置随后在锁内通过 copy-on-write 模式合并， 防止 I/O 和合并之间其他 goroutine 替换 s.v 导致的 TOCTOU 竞态。
func (*Service) Watch ¶
func (s *Service) Watch(ctx context.Context, key string) (datacontract.ConfigWatcher, error)
Watch watches configuration changes if config source supports it. For local file source, use a lightweight polling watcher to detect changes and reload config. Core logic: Delegate to config source when present; otherwise poll local files and emit key changes.
Watch 监听配置变化（如果配置源支持）。 对于本地文件源，使用轻量轮询监听配置文件变化并自动重载。 核心逻辑：存在配置源时委托给配置源，否则轮询本地文件并发出 key 变更回调。
Source Files