Agent Skills
› NeverSight/learn-skills.dev
› go-viper
go-viper
GitHub用于编写、调试和解释基于 github.com/spf13/viper 的 Go 配置代码。支持配置加载、结构体映射、文件/环境变量/命令行参数优先级处理及 Cobra 集成，提供符合最佳实践的清洁初始化方案。
Trigger Scenarios
需要加载 Viper 配置
定义配置结构体
处理文件、环境变量和命令行参数的优先级
集成 Cobra 或 pflag
将配置反序列化到结构体
设置环境变量键替换器
构建应用程序配置引导流程
Install
npx skills add NeverSight/learn-skills.dev --skill go-viper -g -y
SKILL.md
Frontmatter
{
"name": "go-viper",
"source": "local",
"license": "MIT",
"description": "Write, debug, and explain Go configuration code using github.com\/spf13\/viper. Use this skill whenever the user wants Viper-based config loading, config structs, file plus env plus flag precedence, Cobra or pflag integration, unmarshaling config into structs, env key replacers, or a clean application config bootstrap that follows Viper's README behavior."
}
Use this skill to produce a clean Viper setup that reads configuration from file, flags, and environment with Viper's normal precedence:
- explicit
Set - flags
- environment variables
- config file
- remote key/value store
- defaults
Core approach
- Prefer
viper.New()over the package global; build one configured instance and pass it where needed. - Define a typed
Configstruct and unmarshal into it after all defaults, file paths, env bindings, and flag bindings are configured. - Keep configuration bootstrap in one place such as
internal/configorpkg/configwith aLoad(...)function. - Treat the config file as optional only when the app design allows it; otherwise return a clear error.
- Bind flags and env explicitly for important keys, and use
AutomaticEnv()plus an env key replacer for the general case.
Clean Viper bootstrap
When writing a Viper-based loader, follow this order:
- Create an instance with
v := viper.New(). - Set config file name, type if needed, and search paths.
- Set defaults with
SetDefault. - Configure env loading with
SetEnvPrefix,SetEnvKeyReplacer,AutomaticEnv, andBindEnvfor special keys. - Define and parse
pflagor Cobra flags, then bind them withBindPFlagorBindPFlags. - Call
ReadInConfig(). - Handle
viper.ConfigFileNotFoundErrorseparately from parse errors when the file is optional. - Call
Unmarshal(&cfg)into a typed struct. - Validate the resulting struct if the app has required fields or constraints.
Implementation rules
- Use
mapstructuretags on struct fields when file keys differ from Go field names. - For nested keys that should map to env vars, use
strings.NewReplacer(".", "_", "-", "_")withSetEnvKeyReplacer. - Remember that env vars are case-sensitive and are read when accessed, not cached at bind time.
- Remember that Viper does not deep-merge complex values; later sources replace the whole value.
- Add all config paths before
ReadInConfig()and beforeWatchConfig(). - If the user uses Cobra, bind command flags directly from the command's flag set.
- If the user wants testable code, return both the typed config and the configured
*viper.Viperonly when the caller truly needs both; otherwise return just the typed config.
Output expectations
- Give a small, production-leaning config package, not scattered snippets.
- Show how file, env, and flags work together in one example.
- Make precedence explicit in the explanation.
- Mention the exact env var names and flag names generated or bound.
References
- Read
references/clean-config-pattern.mdfor the recommended package shape, loader order, validation strategy, testing guidance, and common pitfalls. - Read
references/file-env-flag-precedence.mdwhen the task is specifically about how file, env, and flags interact or why one source wins over another. - Read
examples/clean_setup.gofor a compact end-to-end loader example.
Version History
- e0220ca Current 2026-07-05 22:10
