百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
Z

zerocfg

> 编程语言
开源

零成本、简洁的配置管理,避免了套用模板和重复操作。

200 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

零成本、简洁的配置管理,避免了套用模板和重复操作。

Zero Effort Configuration

I've always loved the elegance of Go's flag package - how clean and straightforward it is to define and use configuration options. While working on various Go projects, I found myself wanting that same simplicity but with support for YAML configs. I couldn't find anything that preserved this paradigm, so I built zerocfg.

  • ️ Simple and flexible API inspired by flag package
  • Boilerplate usage prohibited by design
  • Early detection of mistyped config keys
  • ✨ Multiple configuration sources with priority-based value resolution
  • ️‍♂️ Render running configuration with secret protection
  • Custom option types and providers are supported

Table of Contents

  • Installation
  • Quick Start
  • Usage
    • Options naming
    • Restrictions
    • Unknown values
    • Complex Types as string
  • Configuration Sources
    • Command-line Arguments
    • Environment Variables
    • YAML Source
  • Advanced Usage
    • Value Representation
    • Custom Options
    • Custom Providers

Installation

bash
go get -u github.com/chaindead/zerocfg

Quick Start

…

Usage

Options naming

  • Dots (.) are used as separators for hierarchical options.
  • Option subnames preferred separation is camelCase, underscore (_), and dash (-) styles.

Example:

go
zfg.Str("groupOptions.thisOption", "", "camelCase usage")
zfg.Str("group_options.this_option", "", "underscore usage")
zfg.Str("group-options.this-option", "", "dash usage")

Restrictions

  • Options are registered at import time. Dynamic (runtime) option registration is not supported

    go
    // internal/db/client.go
    package db
    
    import zfg "github.com/chaindead/zerocfg"
    
    // good: options registered at import
    var dbHost = zfg.Str("db.host", "localhost", "called on import")
    
    // bad: dynamic registration
    func AddOption() {
        zfg.Str("db.dynamic", "", "not supported")
    }
  • No key duplication is allowed. Each option key must be unique to ensure a single source of truth and avoid boilerplate

  • Simultaneous use of keys and sub-keys (e.g., map and map.value) are not allowed

Unknown values

If zfg.Parse encounters an unknown value (e.g. variable not registered as an option), it returns an error. This helps avoid boilerplate and ensures only declared options are used.

But you can ignore unknown values if desired.

go
err := zfg.Parse(
    env.New(),
    yaml.New(path),
)
if u, ok := zfg.IsUnknown(err); !ok {
    panic(err)
} else {
    // u is map  to slice of unknown keys
    fmt.Println(u)
}

env source does not trigger unknown options to avoid false positives.

Complex Types as string

  • Base values converted via fmt.Sprint("%v")
  • If a type has a String() method, it is used for string conversion (e.g., time.Duration).
  • Otherwise, JSON representation is used for complex types (e.g., slices, maps).

For converting any value to string, zfg.ToString is used internally.

go
var (
    _ = zfg.Dur("timeout", 5*time.Second, "duration via fmt.Stringer interface")
    _ = zfg.Floats64("floats", nil, "list via json")
)

func main() {
    _ = zfg.Parse()

    fmt.Printf(zfg.Show())
    // CMD: go run ./... --timeout 10s --floats '[1.1, 2.2, 3.3]'
    // OUTPUT:
    //   floats  = [1.1,2.2,3.3] (list via json)
    //   timeout = 10s           (duration via fmt.Stringer interface)
}

Configuration Sources

The configuration system follows a strict priority hierarchy:

  1. Command-line flags (always highest priority, enabled by default)
  2. Optional providers in order of addition (first added = higher priority)
  3. Default values (lowest priority)

For example, if you initialize configuration like this:

go
zfg.Parse(
    env.New(),      // Second highest priority (after cli flags)
    yaml.New(path), // Third highest priority
)

The final value resolution order will be:

  1. Command-line flags (if provided)
  2. Providers from arguments of zfg.Parse in same order as it is passed.
  3. Default values

Important notes:

  • Lower priority sources cannot override values from higher priority sources
  • All providers except flags are optional
  • Provider priority is determined by the order in Parse() function
  • Values not found in higher priority sources fall back to lower priority sources

Command-line Arguments

  • The flag source is enabled by default and always has the highest priority
  • You can define configuration options with aliases for convenient CLI usage
  • Values are passed as space-separated arguments (no = allowed)
  • Both single dash (-) and double dash (--) prefixes are supported for flags and their aliases

Example:

go
path := zfg.Str("config.path", "", "path to yaml conf file", zfg.Alias("c"))

You can run your application with:

go run ./... -c test.yaml
# or
go run ./... --config.path test.yaml

In both cases, the value test.yaml will be assigned to config.path.

Environment Variables

Environment variables are automatically transformed from the configuration key format:

Config Key Environment Variable Note
db.user DB_USER Basic transformation
app.api.key APP_API_KEY Multi-level path
camelCase.value CAMELCASE_VALUE CamelCase handling
api-key.secret APIKEY_SECRET Dashes removed
under_score.value UNDERSCORE_VALUE Underscores removed

The transformation rules:

  1. Remove special characters (except letters, digits, and dots)
  2. Replace dots with underscores
  3. Convert to uppercase

Example:

go
import (
    "fmt"
    zfg "github.com/chaindead/zerocfg"
    "github.com/chaindead/zerocfg/env"
)
var dbUser = zfg.Str("db.user", "", "database's username")

func main() {
    _ = zfg.Parse(
        env.New(),
    )
    fmt.Printf("DB user: %s", *dbUser)
}

When you run, dbUser will be set to admin.

bash
DB_USER=admin go run main.go
# OUTPUT: DB user: admin

YAML Source

  • Options use dotted paths to map to YAML keys, supporting hierarchical configuration.
  • All naming styles are supported and mapped to YAML keys as written.

Example YAML file:

yaml
group:
  option: "foo"

numbers:
  - 1
  - 2
  - 3

limits:
  max: 10
  min: 1

Example Go config:

go
zfg.Str("group.option", "", "hierarchical usage")
zfg.Ints("numbers", nil, "slice of server configs")
zfg.Map("limits", nil, "map of limits")

Advanced Usage

Value Representation

[!IMPORTANT] Read this section before implementing custom options or providers.

  • All supported option values must have a string representation
  • Conversion to string is performed using zfg.ToString
  • Types must implement Set(string); the string passed is produced by ToString and parsing must be compatible
  • Providers return map[string]string where values are produced by the conv function argument in the provider interface (internally zfg.ToString is used)

Custom Options

You can define your own option types by implementing the Value interface and registering them via Any function. Methods Set and String should be compatible.

go
// Custom type
type MyType struct{ V string }

func newValue(val MyType, p *MyType) zfg.Value {
    *p = val
    return p
}

func (m *MyType) Set(s string) error { m.V = s; return nil }
func (m *MyType) Type() string       { return "custom" }
func (m *MyType) String() string { return m.V }

func Custom(name string, defVal MyType, desc string, opts ...zfg.OptNode) *MyType {
     return zfg.Any(name, defVal, desc, newValue, opts...)
}

// Register custom option
var myOpt = Custom("custom.opt", MyType{"default"}, "custom option")

Custom Providers

You can add your own configuration sources by implementing the Provider interface.

  • If awaited[name] == true, the name is an option
  • If awaited[name] == false, the name is an alias
go
type MyProvider struct{}

func (p *MyProvider) Type() string { return "my" }
func (p *MyProvider) Provide(awaited map[string]bool, conv func(any) string) (map[string]string, map[string]string, error) {
    found := map[string]string{}
    unknown := map[string]string{}
    // ... fill found/unknown based on awaited ...
    return found, unknown, nil
}

// Usage
zfg.Parse(&MyProvider{})

Documentation

For detailed documentation and advanced usage examples, visit our Godoc page.

Star History

License

This project is licensed under the MIT License - see the LICENSE file for details.

Issues· 3 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Goconfigconfigurationenvironmentflag

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月18日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言