config

Documentation

Index

• func InitConfigure(config interface{}, options ...ConfigureLoaderOption) error
• func LoadFromViper(v *viper.Viper, config interface{}) error
• func LoadViperConfig[T any](cmd *cobra.Command, opts Options[T], specs []FlagSpec) (*T, error)
• func NewRoot[T any](opts Options[T]) *cobra.Command
• func RegisterConfigFlags(cmd *cobra.Command, specs []FlagSpec) error
• func ValidateNode(object interface{}) error
• type ConfigureLoader
  • func NewConfigureLoader(options ...ConfigureLoaderOption) (*ConfigureLoader, error)
  • func (l *ConfigureLoader) Watch(callback func(fsnotify.Event))
  • func (l *ConfigureLoader) WatchRemoteConfig(ctx context.Context, callback func(e fsnotify.Event))
• type ConfigureLoaderOption
  • func WithCommand(cmd *cobra.Command, specs []FlagSpec) ConfigureLoaderOption
  • func WithConfigFS(filesystem fs.FS, path string) ConfigureLoaderOption
  • func WithConfigFile(path string, ignoreNotFound bool) ConfigureLoaderOption
  • func WithEnvPrefix(prefix string, replaces ...*strings.Replacer) ConfigureLoaderOption
  • func WithRemoteProvider(provider, endpoint, path string) ConfigureLoaderOption
  • func WithRemoteURL(rawURL string) ConfigureLoaderOption
• type FlagProvider
• type FlagSpec
  • func GetConfigFlagSpecs[T any]() []FlagSpec
  • func GetConfigFlagSpecsWithPrefix[T any](parentPrefix string) []FlagSpec
• type Options

Functions

func InitConfigure

func InitConfigure(config interface{}, options ...ConfigureLoaderOption) error

func LoadFromViper

func LoadFromViper(v *viper.Viper, config interface{}) error

LoadFromViper 将 Viper 中的配置反序列化到目标对象，并执行结构体验证。

func LoadViperConfig

func LoadViperConfig[T any](cmd *cobra.Command, opts Options[T], specs []FlagSpec) (*T, error)

LoadViperConfig 根据已解析的 Cobra 命令构造配置加载选项，加载并校验最终的 T。

默认配置文件不存在时允许继续启动，以便依赖远程配置、环境变量或 CLI；如果用户显式传入 --config，则文件不存在也视为输入错误。--remote 可与本地文件同时使用，远程配置优先级低于 本地文件；远程读取失败时只有已成功读取的本地文件可以作为兜底。

func NewRoot

func NewRoot[T any](opts Options[T]) *cobra.Command

NewRoot 创建一个集成 Cobra、Viper 与模块化配置对象的根命令。

构建阶段会完成以下工作：

• 根据 Options 确定命令名称和帮助信息；
• 注册 --config/-c；
• 注册 --remote；
• 扫描 T 中实现 FlagProvider 的配置项，并注册对应的 persistent flags；
• 调用 BindFlags，让业务补充自己的命令行参数。

Execute 进入 RunE 后才会读取配置。配置值由配置文件、环境变量和 Cobra flags 交给统一的 ConfigureLoader 合并，然后反序列化并校验为 *T。对于同一个配置键， 显式规范参数优先于 alias，最终优先级为 Cobra 参数、环境变量、本地文件、远程 KV、默认值。

func RegisterConfigFlags

func RegisterConfigFlags(cmd *cobra.Command, specs []FlagSpec) error

RegisterConfigFlags 将配置聚合对象声明的 FlagSpec 注册为 Cobra persistent flags。 FlagSpec.Name 是规范参数名，Aliases 中的名称使用相同类型、默认值和帮助信息。

func ValidateNode

func ValidateNode(object interface{}) error

Types

type ConfigureLoader

type ConfigureLoader struct {
	// contains filtered or unexported fields
}

ConfigureLoader 负责聚合并加载多来源配置。

func NewConfigureLoader

func NewConfigureLoader(options ...ConfigureLoaderOption) (*ConfigureLoader, error)

NewConfigureLoader 创建一个新的配置加载器

func (*ConfigureLoader) Watch

func (l *ConfigureLoader) Watch(callback func(fsnotify.Event))

Watch 监听本地配置文件的变更。当文件发生变更时，调用提供的 callback 函数。 内部使用 viper 的 WatchConfig + OnConfigChange 实现文件系统级监听。

func (*ConfigureLoader) WatchRemoteConfig

func (l *ConfigureLoader) WatchRemoteConfig(ctx context.Context, callback func(e fsnotify.Event))

WatchRemoteConfig 定期轮询远程配置中心（etcd/consul/firestore）， 当检测到变更时触发 callback。调用方负责通过 ctx 控制轮询生命周期。

type ConfigureLoaderOption

type ConfigureLoaderOption func(*ConfigureLoader) error

ConfigureLoaderOption 定义配置选项的函数类型

func WithCommand

func WithCommand(cmd *cobra.Command, specs []FlagSpec) ConfigureLoaderOption

WithCommand 根据 FlagSpec 将自动注册的 Cobra flags 绑定到对应的 Viper 配置键。

每个 FlagSpec 先绑定规范参数，再检查 aliases。如果规范参数被显式设置，所有 aliases 都会被忽略；否则显式设置的 alias 会绑定到 spec.Name。多个 alias 同时设置时， Aliases 列表中最后一个已设置项生效，与原有绑定顺序保持一致。

func WithConfigFS

func WithConfigFS(filesystem fs.FS, path string) ConfigureLoaderOption

WithConfigFS 从 fs.FS 读取配置，适用于 go:embed 和测试内存文件系统。

func WithConfigFile

func WithConfigFile(path string, ignoreNotFound bool) ConfigureLoaderOption

WithConfigFile 设置需要精确读取的配置文件路径。 ignoreNotFound 为 true 时仅忽略文件不存在错误，格式、权限等其它错误仍会返回。

func WithEnvPrefix

func WithEnvPrefix(prefix string, replaces ...*strings.Replacer) ConfigureLoaderOption

WithEnvPrefix 设置环境变量前缀，例如 MYAPP_

func WithRemoteProvider

func WithRemoteProvider(provider, endpoint, path string) ConfigureLoaderOption

WithRemoteProvider 设置远程配置中心。 provider 是 Viper 支持的 provider 名称，例如 etcd3、consul 或 firestore； endpoint 是 provider 原生地址；path 是远程 KV key。远程内容格式优先从 path 扩展名推断，无法推断时默认使用 yaml。需要显式格式时应使用 WithRemoteURL。

func WithRemoteURL

func WithRemoteURL(rawURL string) ConfigureLoaderOption

WithRemoteURL 使用统一 URL 描述远程配置中心。 支持 etcd://host/key 和 consul://host/key；etcd 默认映射到 etcd v3。 URL 查询参数 format 可显式指定远程内容格式，未指定时依次使用 key 扩展名和 yaml。

type FlagProvider

type FlagProvider interface {
	Flags(prefix string) []FlagSpec
}

FlagProvider 由需要暴露命令行参数的配置对象实现。

type FlagSpec

type FlagSpec struct {
	Name      string
	Aliases   []string
	Shorthand string
	Default   any
	Usage     string
}

FlagSpec 描述一个可由命令行覆盖的配置项。

func GetConfigFlagSpecs

func GetConfigFlagSpecs[T any]() []FlagSpec

GetConfigFlagSpecs 返回配置聚合对象中所有模块声明的命令行元数据。

T 应当是业务组合配置结构体或其指针。函数只扫描 T 的第一层导出字段； 字段对应的配置类型实现 FlagProvider 时，才会参与命令行参数注册。 字段的 mapstructure tag 决定配置键前缀，例如 mapstructure:"http" 会生成 http.port。

func GetConfigFlagSpecsWithPrefix

func GetConfigFlagSpecsWithPrefix[T any](parentPrefix string) []FlagSpec

GetConfigFlagSpecsWithPrefix 返回配置聚合对象中所有模块声明的命令行元数据， 并在每个配置键前追加 parentPrefix。

该函数用于把一个业务 Config 继续组合到更高层配置对象中。例如 user.Config 实现 FlagProvider 时，可以在 Flags("user") 中调用本函数，最终生成 user.http.port、user.redis.host 等带业务模块前缀的配置键。

type Options

type Options[T any] struct {
	Use           string                          // Use 对应 cobra.Command.Use。为空时依次回退到 AppName 和当前可执行文件名。
	AppName       string                          // AppName 是应用名称，同时也是 Use 为空时的首选命令名。
	Short         string                          // Short 是 Cobra 帮助信息中的简短说明。
	Long          string                          // Long 是 Cobra 帮助信息中的详细说明。
	DefaultFile   string                          // DefaultFile 是 --config/-c 的默认值。默认文件不存在时允许继续使用其它配置来源。
	DefaultRemote string                          // DefaultRemote 是 --remote 的默认值，支持 etcd:// 和 consul:// URL。
	EnvPrefix     string                          // EnvPrefix 限定参与加载的环境变量前缀，例如 ORDER_HTTP_PORT 中的 ORDER。
	Args          cobra.PositionalArgs            // Args 是 Cobra 的位置参数校验函数；为空时不额外限制位置参数。
	BindFlags     func(*cobra.Command)            // BindFlags 在模块配置参数注册完成后调用，用于补充业务自定义的 Cobra 参数。
	Run           func(context.Context, *T) error // Run 在配置文件、环境变量和命令行参数合并并通过校验后执行。
}

Options 定义 Cobra 根命令的展示信息、配置来源和最终执行函数。

泛型参数 T 是业务侧组合后的完整配置类型。NewRoot 会扫描 T 的导出字段， 只为实现了 FlagProvider 的配置项注册命令行参数，并在执行 Run 前完成配置加载和校验。