Documentation
¶
Index ¶
- func Expand(ctx context.Context, v any, providers ...Provider) error
- func ExpandOptionsApply(ctx context.Context, v any, opts ExpandOptions) error
- func ExpandString(ctx context.Context, s string, providers ...Provider) (string, error)
- func ExpandStringOptions(ctx context.Context, s string, opts ExpandOptions) (string, error)
- func FileFromEnv(fallback string) string
- func Load(path string, dst any) error
- func LoadDotEnv(paths ...string) error
- func OverloadDotEnv(paths ...string) error
- func RegisterFactory(scheme string, fn FactoryFunc)
- type ConfigCenter
- type ExpandOptions
- type FactoryFunc
- type Loader
- type Provider
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Expand ¶ added in v0.6.3
Expand walks v (struct / map / slice / pointer) and expands placeholders in all string fields. Non-string values are left unchanged. Unexported struct fields are skipped.
func ExpandOptionsApply ¶ added in v0.6.3
func ExpandOptionsApply(ctx context.Context, v any, opts ExpandOptions) error
ExpandOptionsApply is Expand with explicit options.
func ExpandString ¶ added in v0.6.3
ExpandString replaces all ${scheme:ref} / ${scheme:ref:-default} placeholders in s. When providers is empty, EnvProvider and FileProvider are used.
func ExpandStringOptions ¶ added in v0.6.3
ExpandStringOptions is ExpandString with explicit options.
func FileFromEnv ¶ added in v0.7.0
FileFromEnv 从 CONFIG_FILE 环境变量获取配置文件路径， 未设置时返回 fallback。适合容器化部署统一注入配置路径。
path := conf.FileFromEnv("config/app.yaml")
func Load ¶ added in v0.7.0
Load 是面向业务代码的一站式配置加载快捷方式：
- path 为空 → 跳过（返回 nil）
- 文件不存在 → 跳过（返回 nil）
- 文件存在 → New + WithSecrets + Unmarshal
典型用法：
var cfg AppConfig
if err := conf.Load(conf.FileFromEnv("config/app.yaml"), &cfg); err != nil {
log.Fatal(err)
}
func LoadDotEnv ¶ added in v0.6.3
LoadDotEnv 加载 .env 文件中的变量到进程环境（不覆盖已存在的环境变量）。 未指定路径时默认加载工作目录下的 .env 文件。 加载后 ${env:VAR} 占位符和 os.Getenv 均可访问这些变量。
conf.LoadDotEnv() // 加载 .env
conf.LoadDotEnv(".env", ".env.local") // 按顺序加载，后者优先
func OverloadDotEnv ¶ added in v0.6.3
OverloadDotEnv 与 LoadDotEnv 类似，但会覆盖已存在的同名环境变量。 适用于本地开发时 .env.local 需要强制覆盖容器/系统级变量的场景。
func RegisterFactory ¶
func RegisterFactory(scheme string, fn FactoryFunc)
RegisterFactory 注册一个 scheme 对应的 ConfigCenter 工厂。 在各 infra 子包的 init() 中调用，重复注册同一 scheme 会 panic。
Types ¶
type ConfigCenter ¶
type ConfigCenter interface {
// Get 获取配置内容
Get(ctx context.Context, key string) (string, error)
// Watch 监听 key 变更，变更时以新值回调 onChange。
// ctx 取消或调用返回的 cancel 均可停止监听。
Watch(ctx context.Context, key string, onChange func(key, value string)) (context.CancelFunc, error)
}
ConfigCenter 统一配置中心接口，nacos/etcd/polaris 均实现此接口。 key 的含义由实现决定：nacos=dataID，etcd=完整路径，polaris=文件名。
type ExpandOptions ¶ added in v0.6.3
type ExpandOptions struct {
Providers []Provider
// Strict when true (default) returns error if a placeholder cannot be resolved
// and has no default. When false, unresolved placeholders are left as-is.
Strict bool
}
ExpandOptions controls placeholder expansion.
type FactoryFunc ¶
type FactoryFunc func(u *url.URL) (ConfigCenter, error)
FactoryFunc 从解析好的 URL 构造一个 ConfigCenter。 scheme 由各 infra 包在 init() 中注册。
type Loader ¶
Loader 统一配置加载接口。 Unmarshal 将当前配置反序列化到 dst（热加载后再次调用可拿到新值）。 Watch 在每次配置变更时异步调用 fn，ctx 取消后停止监听。
func New ¶
New 根据 rawURL 构造 Loader。
- 无 scheme 或 scheme == "file"：读取本地文件，支持 fsnotify 热加载。
- 其他 scheme（etcd / nacos / consul / polaris …）： 需提前 import 对应 infra 子包（触发 init 注册工厂）， URL 格式由各工厂决定，key 取自 URL Path（去掉前导 /）。
远程示例：
conf.New("etcd://127.0.0.1:2379/myapp/config.yaml")
conf.New("nacos://127.0.0.1:8848/myapp.yaml?namespace=dev&group=DEFAULT_GROUP")
conf.New("consul://127.0.0.1:8500/myapp/config.yaml")
密钥与配置分离：YAML 中写占位符，再用 WithSecrets 包装 Loader：
loader, _ := conf.New("config.yaml")
loader = conf.WithSecrets(loader) // ${env:NAME} / ${file:/path}
loader.Unmarshal(&cfg)
func WithSecrets ¶ added in v0.6.3
WithSecrets returns a Loader that expands ${scheme:ref} placeholders in all string fields after each Unmarshal. Default providers are EnvProvider and FileProvider when providers is empty.
Example config:
database:
password: "${env:DB_PASSWORD}"
tls:
key: "${file:/var/run/secrets/tls.key}"
token: "${secret:api_token}" # requires a Provider with Scheme "secret"
func WithSecretsOptions ¶ added in v0.6.3
func WithSecretsOptions(inner Loader, opts ExpandOptions) Loader
WithSecretsOptions is WithSecrets with explicit ExpandOptions.
type Provider ¶ added in v0.6.3
type Provider interface {
Scheme() string
// Get returns the secret value for key (already stripped of scheme prefix).
// key is the part after "scheme:" and before optional ":-default".
Get(ctx context.Context, key string) (string, error)
}
Provider resolves a secret reference for one scheme (env, file, vault, …).
func DotEnvProvider ¶ added in v0.6.3
DotEnvProvider 返回一个 Provider，从 .env 文件解析键值对来解析 ${dotenv:VAR} 占位符，不污染进程环境。 未指定路径时默认读取 .env。
loader = conf.WithSecrets(loader, conf.EnvProvider(), conf.DotEnvProvider())
func EnvProvider ¶ added in v0.6.3
func EnvProvider() Provider
EnvProvider resolves ${env:NAME} and ${env:NAME:-default} from process environment.
func FileProvider ¶ added in v0.6.3
func FileProvider() Provider
FileProvider resolves ${file:/path/to/secret} by reading the file contents (trimmed).
Source Files