结构体标签

ConfReader 构建器 API

config.NewConfReader("myapp")             // 创建读取器（配置名 = 文件名 + 环境变量前缀基础）
    .WithSearchDirs("/etc/conf", "./")    // 覆盖配置文件搜索目录（默认：home + 当前目录）
    .WithPrefix("MYAPP")                 // 环境变量前缀：MYAPP_DB_HOST
    .Read(&cfg)                          // 读取并填充结构体（返回错误）

监听实时配置变更：

reader := config.NewConfReader("myapp")
err := reader.Read(&cfg)

mutex := reader.Watch() // 在 Read() 之后调用；如果在之前调用会 panic

// 线程安全访问：
mutex.RLock()
val := cfg.SomeField
mutex.RUnlock()

配置文件

• 文件名：<configName>.yaml（或 .json、.toml、.hcl、.ini、.env、.properties）

• 搜索顺序：主目录，然后是当前目录（可通过 WithSearchDirs 覆盖）

• 字段名映射：camelCase → 小写驼峰式 YAML 键

  对应结构体字段 DB.DbName：

  db: dbName: "mydb"

环境变量

• 默认模式：FIELD_PATH，点号替换为 _，转为大写
  • App.Server.Port → APP_SERVER_PORT
• 带前缀：NewConfReader("x").WithPrefix("MYAPP") → MYAPP_APP_SERVER_PORT
• 使用 envvar 标签覆盖：Password string \envvar:"DB_PASS"``→ 从DB_PASS读取

命令行标志

• 默认模式：小写带点路径，前缀为 --
  • App.Server.Port → --app.server.port=8080
• 布尔标志：单独传递标志（无需值）：--verbose
• 使用 flag 标签覆盖：Debug bool \flag:"debug"``→\--debug
• 切片：重复标志：--slice a --slice b
• 字节切片：base64 编码：--bytes dGVzdA==

完整示例

package main

import (
    "fmt"
    "time"
    "github.com/num30/config"
)

type Config struct {
    GlobalConfig `mapstructure:",squash"` // squash：字段提升到顶级
    Debug        bool
    DB           DatabaseConfig
    DefaultVal   string   `default:"default value"`
    Tags         []string `default:"[\"a\",\"b\"]"`
}

type GlobalConfig struct {
    Verbose bool `flag:"verbose" usage:"enable verbose logging"`
}

type DatabaseConfig struct {
    Host     string        `default:"localhost" validate:"required"`
    Password string        `validate:"required" envvar:"DB_PASS"`
    DbName   string        `default:"mydb"`
    Username string        `default:"root"`
    Port     int           `default:"5432"`
    Timeout  time.Duration `default:"30s"`
}

func main() {
    var cfg Config
    err := config.NewConfReader("myapp").
        WithSearchDirs("/etc/myapp", "./").
        WithPrefix("MYAPP").
        Read(&cfg)
    if err != nil {
        panic(err)
    }
    fmt.Printf("%+v\n", cfg)
}

扁平化嵌入

在嵌入的结构体上使用 mapstructure:",squash"，以在配置文件和 env vars 中将其字段提升到父级：

type GlobalConfig struct { Verbose bool }

type AppConfig struct {
    GlobalConfig `mapstructure:",squash"` // 以 `verbose` 访问，而非 `globalConfig.verbose`
    Name string
}

配置文件：verbose: true（而非 globalConfig.verbose: true） 环境变量：VERBOSE=true（而非 GLOBAL_CONFIG_VERBOSE=true）

支持的 Go 类型

所有基本类型都支持作为配置字段：bool、int/int8/int16/int32/int64、uint/uint8/uint16/uint32/uint64、float32/float64、string、[]string、[]byte（标志/env 中为 base64）、time.Duration

验证

在结构体字段上使用 go-playground/validator 标签：

type Config struct {
    Host  string `validate:"required"`
    Port  int    `validate:"min=1,max=65535"`
    Email string `validate:"required,email"`
}

如果约束被违反，Read() 会返回验证错误。完整标签列表请参阅 validator 文档。

内置配置结构体（lib 包）

import "github.com/num30/config/lib"

type Config struct {
    DB lib.PostgresqlDb // 提供 Host, Password, DbName, Username, Port, SslEnabled 及合理的默认值
}

// 获取连接字符串：
connStr := cfg.DB.GetConnString()
// → "host=localhost user=postgres password=pass database= port=5432 sslmode=disable"

lib.PostgresqlDb 默认值：Host:"localhost"、Password:"pass"、Username:"postgres"、Port:5432、SslEnabled:false

切片

type Config struct {
    Slice []string
}

错误处理

Read() 返回以下错误：

• 配置结构体为 nil 或非指针
• 配置文件解析失败 ("failed to unmarshal struct")
• 默认值设置失败 ("failed to set default values")
• 验证失败 ("validation error: Key: '...' Error:...")

如果在 Read() 之前调用 Watch() 会 panic。

其他参考

• references/api.md — 完整 API 参考
• references/examples.md — 实际使用示例

每周安装数

1

仓库

aaronflorey/agent-skills

首次出现

1 天前

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

amp1

cline1

opencode1

cursor1

kimi-cli1

codex1

Struct Tags

ConfReader Builder API

config.NewConfReader("myapp")             // create reader (config name = file name + env prefix base)
    .WithSearchDirs("/etc/conf", "./")    // override config file search dirs (default: home + current dir)
    .WithPrefix("MYAPP")                 // prefix for env vars: MYAPP_DB_HOST
    .Read(&cfg)                          // read and populate struct (returns error)

Watch for live config changes:

reader := config.NewConfReader("myapp")
err := reader.Read(&cfg)

mutex := reader.Watch() // call AFTER Read(); panics if called before

// thread-safe access:
mutex.RLock()
val := cfg.SomeField
mutex.RUnlock()

Config File

• File name: <configName>.yaml (or .json, .toml, .hcl, .ini, .env, .properties)

• Search order: home directory, then current directory (override with WithSearchDirs)

• Field name mapping: camelCase → lower camelCase YAML key

  For struct field DB.DbName:

  db: dbName: "mydb"

Environment Variables

• Default pattern: FIELD_PATH with dots replaced by _, uppercased
  • App.Server.Port → APP_SERVER_PORT
• With prefix: NewConfReader("x").WithPrefix("MYAPP") → MYAPP_APP_SERVER_PORT
• Override with envvar tag: Password string \envvar:"DB_PASS"``→ reads fromDB_PASS

Command-Line Flags

• Default pattern: lowercase dotted path with -- prefix
  • App.Server.Port → --app.server.port=8080
• Boolean flags: pass flag alone (no value needed): --verbose
• Override with flag tag: Debug bool \flag:"debug"``→\--debug
• Slices: repeat the flag: --slice a --slice b
• Byte slices: base64-encoded: --bytes dGVzdA==

Complete Example

package main

import (
    "fmt"
    "time"
    "github.com/num30/config"
)

type Config struct {
    GlobalConfig `mapstructure:",squash"` // squash: fields promoted to top level
    Debug        bool
    DB           DatabaseConfig
    DefaultVal   string   `default:"default value"`
    Tags         []string `default:"[\"a\",\"b\"]"`
}

type GlobalConfig struct {
    Verbose bool `flag:"verbose" usage:"enable verbose logging"`
}

type DatabaseConfig struct {
    Host     string        `default:"localhost" validate:"required"`
    Password string        `validate:"required" envvar:"DB_PASS"`
    DbName   string        `default:"mydb"`
    Username string        `default:"root"`
    Port     int           `default:"5432"`
    Timeout  time.Duration `default:"30s"`
}

func main() {
    var cfg Config
    err := config.NewConfReader("myapp").
        WithSearchDirs("/etc/myapp", "./").
        WithPrefix("MYAPP").
        Read(&cfg)
    if err != nil {
        panic(err)
    }
    fmt.Printf("%+v\n", cfg)
}

Squash Embedding

Use mapstructure:",squash" on an embedded struct to promote its fields to the parent level in config files and env vars:

type GlobalConfig struct { Verbose bool }

type AppConfig struct {
    GlobalConfig `mapstructure:",squash"` // access as `verbose`, not `globalConfig.verbose`
    Name string
}

Config file: verbose: true (not globalConfig.verbose: true) Env var: VERBOSE=true (not GLOBAL_CONFIG_VERBOSE=true)

Supported Go Types

All primitive types are supported as config fields: bool, int/int8/int16/int32/int64, uint/uint8/uint16/uint32/uint64, float32/float64, string, []string, []byte (base64 in flags/env), time.Duration

Validation

Uses go-playground/validator tags on struct fields:

type Config struct {
    Host  string `validate:"required"`
    Port  int    `validate:"min=1,max=65535"`
    Email string `validate:"required,email"`
}

Read() returns a validation error if constraints are violated. See validator docs for full tag list.

Built-in Config Structs (lib package)

import "github.com/num30/config/lib"

type Config struct {
    DB lib.PostgresqlDb // provides Host, Password, DbName, Username, Port, SslEnabled with sane defaults
}

// Get connection string:
connStr := cfg.DB.GetConnString()
// → "host=localhost user=postgres password=pass database= port=5432 sslmode=disable"

lib.PostgresqlDb defaults: Host:"localhost", Password:"pass", Username:"postgres", Port:5432, SslEnabled:false

Slices

type Config struct {
    Slice []string
}

Error Handling

Read() returns errors for:

• Nil or non-pointer config struct
• Config file parse failures ("failed to unmarshal struct")
• Default value failures ("failed to set default values")
• Validation failures ("validation error: Key: '...' Error:...")

Watch() panics if called before Read().

Additional References

• references/api.md — Full API reference
• references/examples.md — Real-world usage examples

Weekly Installs

1

Repository

aaronflorey/agent-skills

First Seen

1 day ago

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

amp1

cline1

opencode1

cursor1

kimi-cli1

codex1