用途
go-viper 技能用于编写、调试和解释使用 github.com/spf13/viper 的 Go 配置代码。当用户提到 Viper、viper、配置结构体（config structs）等时，可应用该技能。目标是产出一套整洁的 Viper 配置方案，能够从文件、命令行标志（flags）和环境变量读取配置，并遵循 Viper 的正常优先级顺序。
主要能力
- 生成生产倾向的配置包，而非零散代码片段。
- 在一个示例中展示文件、环境变量和标志如何协同工作。
- 在解释中明确说明优先级顺序。
- 说明生成或绑定的确切环境变量名和标志名。
- 提供参考文档：
references/clean-config-pattern.md（推荐的包结构、加载顺序、验证策略、测试指南和常见陷阱）、references/file-env-flag-precedence.md（文件、环境变量和标志如何交互，以及为何某个来源优先）、examples/clean_setup.go（紧凑的端到端加载示例）。
使用方式
核心方法
- 优先使用
viper.New()而非包级全局实例；构建一个已配置的实例并按需传递。 - 定义类型化的 Config 结构体，并在配置完所有默认值、文件路径、环境变量绑定和标志绑定后，反序列化到该结构体。
- 将配置引导集中在一个位置，例如
internal/config或pkg/config，并提供Load(...)函数。 - 仅当应用设计允许时，才将配置文件视为可选；否则返回明确的错误。
- 对重要键显式绑定标志和环境变量，一般情况使用
AutomaticEnv()加环境变量键替换器。
整洁的 Viper 引导顺序
编写基于 Viper 的加载器时，遵循以下顺序：
- 使用
v := viper.New()创建实例。 - 设置配置文件名、类型（如需要）和搜索路径。
- 使用
SetDefault设置默认值。 - 配置环境变量加载：
SetEnvPrefix、SetEnvKeyReplacer、AutomaticEnv，并对特殊键使用BindEnv。 - 定义并解析 pflag 或 Cobra 标志，然后使用
BindPFlag或BindPFlags绑定。 - 调用
ReadInConfig()。 - 当文件可选时，将
viper.ConfigFileNotFoundError与解析错误分开处理。 - 调用
Unmarshal(&cfg)到类型化结构体。 - 如果应用有必填字段或约束，验证结果结构体。
实现规则
- 当文件键与 Go 字段名不同时，在结构体字段上使用
mapstructure标签。 - 对于应映射到环境变量的嵌套键，使用
strings.NewReplacer(".", "_", "-", "_")配合SetEnvKeyReplacer。 - 环境变量区分大小写，且在访问时读取，而非在绑定时缓存。
- Viper 不会深度合并复杂值；后续来源会替换整个值。
- 在
ReadInConfig()和WatchConfig()之前添加所有配置路径。 - 如果用户使用 Cobra，直接从命令的标志集绑定命令标志。
- 如果用户希望代码可测试，仅当调用方确实需要时才同时返回类型化配置和已配置的
*viper.Viper；否则只返回类型化配置。
适用场景
- 需要为 Go 应用搭建从文件、环境变量和命令行标志读取配置的加载器。
- 需要调试 Viper 配置优先级问题。
- 需要解释 Viper 的配置读取行为。
- 使用 Cobra 或 pflag 的命令行应用需要绑定标志到配置。
限制
- 该技能聚焦于
github.com/spf13/viper库的使用，不涉及其他配置库。 - 具体收费、价格、平台支持等信息暂未提供。
- 官方文档内容暂未提供，以上内容基于技能描述和介绍整理。