在构建开源 Go 库时，一个最常见的问题是：

配置应该如何设计？

库是否应该读取环境变量？是否应该解析命令行参数或文件？还是应该把一切都交给应用开发者？

简短的答案是：保持库的简洁与框架无关性。 让应用决定如何加载配置，而库本身只需专注于消费配置。

本文将介绍在为 Go 库设计配置时的最佳实践、常见模式以及需要避免的陷阱。

---

核心原则

1. 库 ≠ 应用

   • 不要隐式读取环境变量或命令行参数。
   • 不要在库中记录日志或调用 os.Exit，而是返回错误。

2. 零值可用 + 显式选项

   • 提供合理的默认值，让 New() 即使没有任何配置也能工作。
   • 通过一个小的 Config 结构体或函数式选项让用户覆盖配置。

3. 关注点分离

   • 应用 决定如何加载配置（env、YAML、Viper、Koanf 等）。
   • 库 只需消费配置。

4. 确定性的优先级

   • 默认值 < Config 结构体 < 函数式选项。
   • 清晰地记录这种优先级。

5. 前置验证

   • 在 New() 中验证配置。
   • 对缺失或非法字段返回有帮助的错误。

6. 上下文感知

   • 在操作中接受 context.Context。
   • 避免全局变量。

7. 最小化、稳定的 API

   • 新增配置字段时提供默认值，避免破坏兼容性。
   • 渐进式弃用旧字段。

---

示例：核心库配置

这是一个简单的、无依赖的实现方式：

package foo

import (
	"context"
	"time"
)

type Config struct {
	BaseURL    string
	APIKey     string
	Timeout    time.Duration
	MaxRetries int
	Logger     Logger // 可选
}

func (c *Config) fillDefaults() {
	if c.Timeout == 0 {
		c.Timeout = 10 * time.Second
	}
	if c.MaxRetries == 0 {
		c.MaxRetries = 3
	}
}

func (c *Config) validate() error {
	if c.APIKey == "" {
		return fmt.Errorf("missing APIKey")
	}
	return nil
}

type Option func(*Config)

func WithAPIKey(k string) Option        { return func(c *Config) { c.APIKey = k } }
func WithTimeout(d time.Duration) Option{ return func(c *Config) { c.Timeout = d } }

type Client struct {
	cfg Config
}

func New(opts ...Option) (*Client, error) {
	var cfg Config
	for _, opt := range opts {
		opt(&cfg)
	}
	cfg.fillDefaults()
	if err := cfg.validate(); err != nil {
		return nil, err
	}
	return &Client{cfg: cfg}, nil
}

func (c *Client) Do(ctx context.Context, in any) (any, error) {
	// 实现逻辑
	return nil, nil
}

这种设计使得 Client 使用起来非常简单：

client, _ := foo.New(foo.WithAPIKey("secret"))

---

可选的环境变量适配器

不要在库中内置环境变量逻辑，而是提供一个可选的辅助包：

foo/
  configenv/

package configenv

import (
	"os"
	"strconv"
	"time"

	"github.com/you/foo"
)

const prefix = "FOO_"

func Load() (foo.Config, error) {
	var c foo.Config
	c.APIKey = os.Getenv(prefix + "API_KEY")
	c.BaseURL = os.Getenv(prefix + "BASE_URL")

	if v := os.Getenv(prefix + "TIMEOUT"); v != "" {
		if d, err := time.ParseDuration(v); err == nil {
			c.Timeout = d
		}
	}
	if v := os.Getenv(prefix + "MAX_RETRIES"); v != "" {
		if n, err := strconv.Atoi(v); err == nil {
			c.MaxRetries = n
		}
	}
	return c, nil
}

这样应用可以自由选择：

• 使用 configenv.Load() 从环境变量加载配置
• 或者使用 Koanf/Viper/flags/YAML 等其他方式

库的核心保持简洁。

---

需要避免的做法

• 在 New() 中隐式调用 os.Getenv。
• 使用全局状态或单例。
• 对用户错误使用 panic。
• 在核心包中引入沉重的配置依赖。
• 隐藏的优先级或默认值。

---

文档检查清单

发布库时，文档中应包含：

• ✅ 使用默认值的快速上手示例（New() + 选项）
• ✅ Config 字段完整表格，说明默认值和必填项
• ✅ 环境变量适配器的使用方法及变量表
• ✅ Koanf/Viper/flag 等集成示例（仅作为代码片段，不做硬依赖）
• ✅ 安全注意事项（密钥处理、超时、重试等）
• ✅ 版本控制与破坏性变更策略

---

总结

• 保持核心库纯净：Config + 函数式选项。
• 不要在库中隐式读取环境变量或命令行参数。
• 提供可选的适配器（env、Viper、Koanf）作为独立包。
• 清晰记录默认值、优先级和验证规则。

遵循这些模式，你的 Go 库将会 可预测、灵活且易于集成 —— 而不会强制应用开发者按照某种方式来加载配置。