@go/config

Maintainer Statement: 本项目完全由 AI 维护。任何改动均遵循代码质量与性能的最佳实践。

🎯 设计哲学

@go/config 旨在为应用提供一种零配置感的配置加载体验。其核心目标是：

• 零摩擦入口：To[T] 支持一键加载配置对象；Load 支持注入式加载。
• 多源融合：自动合并基础配置、环境特定配置（env.json/yaml）以及系统环境变量。
• 语义映射：通过下划线分隔的环境变量（如 DB_HOST）自动智能穿透映射到结构体嵌套字段（{"db":{"host":...}}）。
• 极致敏捷：支持 JSON/YAML 格式，并内置 Duration 等增强类型，解决原生 Go 在配置解析中的痛点。

📦 安装

go get apigo.cc/go/config

💡 快速开始

import "apigo.cc/go/config"

type MyConfig struct {
    Port int
    DB   struct {
        Host string
    }
}

// 1. 万能加载 (To 一键获取配置对象)
conf := config.To[MyConfig]("app") // 加载 app.json 或 app.yml

// 2. 传统注入 (Load 注入到现有指针)
var settings MyConfig
config.Load(&settings, "app")

🛠 API 指南

核心 API

1. 通用加载 (Frictionless)

   • To[T any](name string) T —— 万能加载入口。自动在当前目录、执行文件目录及用户主目录搜索 name.json/yml。失败时返回类型零值。
   • Load(target any, name string) error —— 注入加载。将配置内容注入到 target 指针。

2. 加载机制与优先级

   • 基础文件: 搜索并加载 name.json 或 name.yml。
   • 环境补充: 若存在 env.json 或 env.yml，则加载并覆盖基础文件内容。
   • 环境变量覆盖: 自动扫描系统环境变量，按 _ 分隔符映射到结构体字段（不区分大小写）。
     • 示例: APP_PORT=8080 -> {"app": {"port": 8080}}

3. 增强类型

   • Duration —— 支持字符串解析的 time.Duration 包装类（如 "5s", "1h"），解决标准库 time.Duration 在 JSON/YAML 反序列化中的限制。

🧪 验证状态

测试全部通过，支持复杂嵌套结构与环境变量重载。

详见：TEST.md