Golang多后端配置加载与结构体映射插件库Confita的使用

Confita是一个从多个后端加载配置并将其存储在结构体中的库。

支持的后端

• 环境变量
• JSON文件
• Yaml文件
• Toml文件
• 命令行标志
• etcd
• Consul
• Vault
• Amazon SSM

安装

go get -u github.com/heetch/confita

使用

Confita扫描结构体中的config标签，并依次调用所有后端直到找到键。然后将值转换为字段的类型。

结构体布局

支持Go的基本类型：

type Config struct {
  Host        string        `config:"host"`
  Port        uint32        `config:"port"`
  Timeout     time.Duration `config:"timeout"`
}

默认情况下，所有字段都是可选的。使用required选项时，如果找不到键，Confita将返回错误。

type Config struct {
  Addr        string        `config:"addr,required"`
  Timeout     time.Duration `config:"timeout"`
}

也支持嵌套结构体：

type Config struct {
  Host        string        `config:"host"`
  Port        uint32        `config:"port"`
  Timeout time.Duration     `config:"timeout"`
  Database struct {
    URI string              `config:"database-uri,required"`
  }
}

如果字段是切片，Confita会自动按逗号分割配置值并用每个子值填充切片。

type Config struct {
  Endpoints []string `config:"endpoints"`
}

作为一种特殊情况，如果字段标记为"-"，则该字段总是被忽略。这在你想自己填充这个字段时很有用。

type Config struct {
  // Field is ignored by this package.
  Field float64 `config:"-"`

  // Confita scans any structure recursively, the "-" value prevents that.
  Client http.Client `config:"-"`
}

加载配置

创建加载器：

loader := confita.NewLoader()

默认情况下，Confita加载器从环境中加载所有键。加载器可以将其他配置的后端作为参数。

loader := confita.NewLoader(
  env.NewBackend(),
  file.NewBackend("/path/to/config.json"),
  file.NewBackend("/path/to/config.yaml"),
  flags.NewBackend(),
  etcd.NewBackend(etcdClientv3),
  consul.NewBackend(consulClient),
  vault.NewBackend(vaultClient),
)

加载配置：

err := loader.Load(context.Background(), &cfg)

由于使用多个远程后端时加载配置可能需要时间，可以使用上下文进行超时和取消：

ctx, cancel := context.WithTimeout(context.Background(), 5 * time.Second)
defer cancel()
err := loader.Load(ctx, &cfg)

默认值

如果找不到键，Confita不会更改相应的结构体字段。考虑到这一点，可以通过在将结构体传递给Confita之前填充结构体来实现默认值。

type Config struct {
  Host        string        `config:"host"`
  Port        uint32        `config:"port"`
  Timeout     time.Duration `config:"timeout"`
  Password    string        `config:"password,required"`
}

// default values
cfg := Config{
  Host: "127.0.0.1",
  Port: "5656",
  Timeout: 5 * time.Second,
}

err := confita.NewLoader().Load(context.Background(), &cfg)

后端选项

默认情况下，Confita依次查询每个后端，直到找到键。但是，为了避免一些无用的处理，可以指定backend选项来描述期望在哪个后端找到这个键。这在事先知道键的位置时特别有用。

type Config struct {
  Host        string        `config:"host,backend=env"`
  Port        uint32        `config:"port,required,backend=etcd"`
  Timeout     time.Duration `config:"timeout"`
}

命令行标志

flags后端允许从命令行加载单个配置键。默认值从结构体字段值中提取。

也支持short选项。

为了更新命令行上的使用信息，为给定字段提供description。

type Config struct {
  Host        string        `config:"host,short=h"`
  Port        uint32        `config:"port,short=p"`
  Timeout     time.Duration `config:"timeout,description=timeout (in seconds) for failure"`
}

./bin -h

Usage of ./bin:
  -host string
       (default "127.0.0.1")
  -h string
       (default "127.0.0.1")
  -port int
       (default 5656)
  -p int
       (default 5656)
  -timeout duration
       timeout (in seconds) for failure (default 10s)

完整示例

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/heetch/confita"
	"github.com/heetch/confita/backend/env"
	"github.com/heetch/confita/backend/file"
	"github.com/heetch/confita/backend/flags"
)

type Config struct {
	Host     string        `config:"host,short=h"`
	Port     uint32        `config:"port,short=p"`
	Timeout  time.Duration `config:"timeout,description=timeout (in seconds) for failure"`
	Database struct {
		URI string `config:"database-uri,required"`
	}
}

func main() {
	// 默认值
	cfg := Config{
		Host:    "127.0.0.1",
		Port:    5656,
		Timeout: 5 * time.Second,
	}

	// 创建加载器，使用环境变量、JSON文件和命令行标志
	loader := confita.NewLoader(
		env.NewBackend(),
		file.NewBackend("config.json"),
		flags.NewBackend(),
	)

	// 加载配置
	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
	defer cancel()
	err := loader.Load(ctx, &cfg)
	if err != nil {
		log.Fatal(err)
	}

	// 使用配置
	fmt.Printf("Host: %s\n", cfg.Host)
	fmt.Printf("Port: %d\n", cfg.Port)
	fmt.Printf("Timeout: %v\n", cfg.Timeout)
	fmt.Printf("Database URI: %s\n", cfg.Database.URI)
}

许可证

该库在MIT许可证下发布。