kanna-config は、設定の構造体を、フラグ、環境変数、ファイルから読み、kanna-validator の validate タグで確かめる関数を生成します。各設定の名前は、構造体とフィールドの名前で決まります。生成されるのは、各設定を strconv で読み、各ルールを確かめる素の Go で、リフレクションは使いません。誤りは、設定した場所での名前(環境変数、ファイルのキー、フラグ)で報告します。
kanna コードジェネレータファミリーの 1 つです。go-kanna/validator のランタイムと同じく、Go 1.27 以上が必要です。
インストール
go get -tool github.com/go-kanna/config/cmd/kanna-config生成コードが import するのは、このモジュールの source パッケージ、go-kanna/validator のランタイム、読む kanna-value の型のコンストラクタです。ランタイムまでは、上のコマンドで依存に追加されます。YAML と TOML のファイルは、それぞれ別のモジュールが読みます。それを読むプログラムだけが require します:
go get github.com/go-kanna/config/yaml # or github.com/go-kanna/config/toml使い方
設定の構造体に //kanna:config を付けます:
package config
//go:generate go tool kanna-config
//kanna:config
type Database struct {
AdminURL string
WriterURL string `validate:"required"`
PoolMaxConns int32 `default:"10" validate:"gte=1"`
DialTimeout time.Duration `default:"5s"`
}go generate ./... を実行すると、隣に config_gen.go が書き出されます。構造体のフラグを定義する DefineDatabaseFlags と、構造体を読む LoadDatabase です:
// Code generated by kanna-config. DO NOT EDIT.
func LoadDatabase(src source.Source) (Database, error) {
var (
x Database
errs validator.Errors
)
// ...
x.PoolMaxConns = 10
pathPoolMaxConns := validator.Field("DATABASE_POOL_MAX_CONNS")
if v, ok, err := src.Lookup(source.Key{Env: "DATABASE_POOL_MAX_CONNS", File: []string{"database", "pool_max_conns"}, Flag: "database-pool-max-conns"}); err != nil {
errs.Add(v.Path, err)
} else if ok {
pathPoolMaxConns = v.Path
if n, err := strconv.ParseInt(v.Text, 0, 32); err != nil {
errs.Add(pathPoolMaxConns, validator.FailWith("invalid", map[string]any{"type": "int32"}))
} else {
x.PoolMaxConns = int32(n)
}
}
// ...
if len(errs) > 0 {
return Database{}, errs
}
if x.WriterURL == "" {
errs.Add(pathWriterURL, validator.Blank())
}
if x.PoolMaxConns < 1 {
errs.Add(pathPoolMaxConns, validator.GreaterThanOrEqualTo[int32](1))
}
if len(errs) > 0 {
return Database{}, errs
}
return x, nil
}設定がどこにあるかは、プログラムが渡します:
fs := flag.NewFlagSet("api", flag.ExitOnError)
config.DefineDatabaseFlags(fs)
_ = fs.Parse(os.Args[1:])
src, err := source.Open(source.Sources{
Flags: fs,
Files: []source.File{{Path: "config/production.yaml", Decode: yaml.Decode}},
})
if err != nil {
return err
}
db, err := config.LoadDatabase(src)DATABASE_WRITER_URL を設定し忘れ、ファイルに pool_max_conns: 0 と書いて起動すると、LoadDatabase は、それぞれを設定した名前で誤りを返します:
validator: DATABASE_WRITER_URL: blank; database.pool_max_conns: greater_than_or_equal_to (count=1)
Database.AdminURL は DATABASE_ADMIN_URL から読まれ、kanna-orm describe が -database-url を渡されないときに読む DATABASE_URL とは別の変数です。管理用の接続で describe するときは、この変数をフラグで渡します:
go tool kanna-orm describe -database-url "$DATABASE_ADMIN_URL" ./...名前
各フィールドが 1 つの設定で、語の並びで名前が決まります。構造体の語、続いてフィールドの語です。語の分け方は、kanna-orm がフィールドから列の名前を作るのと同じです。出どころごとに、その語を自分の書き方で綴ります:
| フィールド | 環境変数 | ファイル | フラグ |
|---|---|---|---|
Database.WriterURL |
DATABASE_WRITER_URL |
セクション database の writer_url
|
-database-writer-url |
Database.PoolMaxConns |
DATABASE_POOL_MAX_CONNS |
セクション database の pool_max_conns
|
-database-pool-max-conns |
API.Port |
API_PORT |
セクション api の port
|
-api-port |
構造体の語で、構造体ごとに設定を分けられます。2 つの構造体のフィールドで、名前がすべて一致するものは 1 つの設定を読みます。共有を意図することもあるので、止めません。たとえば、postgres.Config と redis.Config のように名前が同じ構造体は、どちらも CONFIG_HOST を読み、両方のフラグを 1 つの FlagSet に定義すると、-config-host は 1 回だけ定義されます。同じパッケージの 2 つの構造体のフィールドで、名前が一部だけ一致するものは、生成を止めます。Database.WriterURL と DatabaseWriter.URL は、DATABASE_WRITER_URL と -database-writer-url を共有しますが、ファイルのキーは別々です。App.Log と AppLog.File(APP_LOG_FILE)のように、あるフィールドの変数がほかの構造体のフィールドの変数のファイルを名指すときも、生成を止めます。kanna-config が比べるのは 1 つのパッケージの構造体どうしで、別のパッケージの構造体とは比べません。
名前は外部の名前で、デプロイの側が設定するものです。構造体の語がそれと違うときは、prefix= に snake case で書きます。たとえば、OAuth という名前の構造体は o_auth に分かれ、Config という名前の構造体の語 config は、何の設定かを表しません:
//kanna:config prefix=oauth
type OAuth struct {
ClientID string `validate:"required"` // OAUTH_CLIENT_ID, oauth.client_id, -oauth-client-id
}フィールドの語も、同じく config:"…" で書きます。OAuthToken というフィールドなら config:"oauth_token" です。Cloud Run の PORT のように実行環境が名付ける変数は、env:"…" に丸ごと書きます。接頭語は付かず、変わるのは環境変数だけです。規約で決まるのと同じ語を書いても構いません。Go の名前を変えても、設定の名前を保てます。
env:"…" の名前は、小文字(http_proxy)も含めて書いたとおりに読みます。ただし、空の名前と、= か NUL を含む名前はどの変数も持てないので、生成を止めます。json タグと同じく、名前は最初のカンマまでです。kanna-config にオプションはないので、カンマの後ろにオプションがあれば生成を止めます。1 つの構造体の 2 つのフィールドが同じ設定を読むときと、Password と PasswordFile のように、あるフィールドの変数がほかのフィールドの変数のファイルを名指すときも、生成を止めます。
出どころ
設定は、フラグ、環境変数、ファイル(後ろのものから)の順に探し、最初にテキストを持っていた出どころが値を決めます。空のテキストは、未設定と同じく何も決めません。DATABASE_POOL_MAX_CONNS= と空で export した環境変数は、設定しなかったのと同じです。
.env ファイルは読みません。環境変数はプロセスが持つものなので、.env を使うなら、source.Open の前に godotenv などで読み込むか、シェルや実行環境に export させてください。
環境変数には、値の代わりに、値を持つファイルのパスを渡せます。Kubernetes が Secret をマウントする形です。DATABASE_PASSWORD_FILE は、そのファイルの中身から末尾の改行を 1 つ除いたものを DATABASE_PASSWORD の値にします。両方を設定すると、誤りとして読むのを止めます。
フラグは flag パッケージのもので、DefineXFlags がプログラムのパースする FlagSet に定義します。source.Open の前にパースしてください。まだパースしていない FlagSet は source.Open が誤りにします。使うのは設定されたフラグだけです。bool のフラグは -database-debug のように単独で書けます。
-h が出すフラグの説明は、フィールドの doc コメントの 1 文目(go/doc が切り出すもの)に、環境変数の名前を続けたものです。doc コメントがなければ、Server.Level (SERVER_LEVEL) のように構造体とフィールドの名前になります。doc コメントのバッククォートは外します。flag パッケージは、バッククォートで囲んだ語をフラグの型の欄に出すからです。型の欄は、flag.Var で定義したほかのフラグと同じく value です。
-server-port value
Port is the port the server listens on. (PORT) (default 8080)
ファイル
ファイルは source.File の Decode が読みます。source.JSON、github.com/go-kanna/config/yaml の yaml.Decode、github.com/go-kanna/config/toml の toml.Decode です。kanna-config はファイルを探さず、環境も見分けません。ファイルはプログラムが勝つ順(後ろのものが前のものに勝つ)に名指し、ないファイルは誤りです。
構造体ごとにファイルのセクションがあり、その各フィールドがセクションのキーです。1 つのファイルに、すべての構造体の設定を書けます:
database:
writer_url: postgres://writer@db/app
pool_max_conns: 20
api:
port: 8080ファイルの値は、環境変数と同じくそのテキストとして読みます。20 と "20" は同じに読み、YAML の 0123 は 0123 というテキストで届きます。整数の設定は Go と同じく 8 進数の 83 として読み、文字列の設定はそのまま読みます。値の場所にあるセクションやリストは誤りです。null は未設定で、null のセクションの下の設定も未設定です(YAML でキーをすべてコメントアウトしたセクションなど)。
構造体のセクションの中の、どのフィールドも読まないキーは、そのキーの名前の下の誤りになります(database.pool_max_con: is no setting of the section database)。値は含めません。キーを打ち間違えても、既定値のまま黙って動かないようにするためです。フィールドのキーと大文字小文字だけが違うキー(database.Writer_URL)は、どれのことかを示します。名前が大文字小文字だけ違う最上位のセクション(Database)も同じです(did you mean database?)。どの構造体のものでもない最上位のセクション(databse など)は見ません。同じファイルに、ほかの構造体を読むプログラムの設定があってもよいからです。照らすキーは、そのセクションを読む、同じパッケージのすべての構造体のものです。ほかのパッケージの構造体は知らないので、パッケージの違う 2 つの構造体がセクションを共有し、フィールドが違うなら、片方に prefix= を書きます。
TOML のライブラリは数・日付・時刻のテキストを渡さないので、その値から書き戻します。数は 10 進数で、0x1F は 31、1_000 は 1000 と読みます。浮動小数は小数点つきで、1.0 は 1.0(整数の設定では誤り)、1.20 は 1.2 と読みます。日付と時刻は RFC 3339 の形で、書いていないタイムゾーンは付けず、1979-05-27 は 1979-05-27、1979-05-27 07:32:00Z は 1979-05-27T07:32:00Z と読みます。書いたとおりに読みたい値は、引用符で囲みます。
読めないファイルは、read config/production.yaml: line 2, column 13 is not valid YAML のように、どこが誤りかで報告します。読むライブラリが出すメッセージは、そこに書いた秘密を引用しうるので見せません。YAML のファイルに書ける文書は 1 つで、--- のあとの 2 つ目の文書は、その位置で誤りにします。source.JSON は encoding/json/v2 で読むので、JSON のオブジェクトに同じ名前を 2 回書くと、2 つ目の位置で誤りにします。自分で書く Decode も、それ以上を言わないようにします。source.Open はその誤りをそのまま返すからです。
読まないフィールド
構造体のフィールドはすべて読みます。非公開のフィールド、埋め込んだフィールド、_ のフィールドは読めないので、生成を止めます。設定から与えないフィールドには config:"-" を付けます。LoadX のあとでシークレットマネージャから読むパスワードなどです:
type Database struct {
WriterURL string `validate:"required"`
Password string `config:"-"`
}LoadX はそのフィールドをゼロ値のままにし、そのルールも確かめません。あとでプログラムが値を入れるからです。//kanna:validate も付けた構造体なら、その Validate が確かめます。//kanna:validate のない構造体で、そのフィールドにルールを書くと、ルールが一度も実行されないので生成を止めます。config:"-" のフィールドに既定値を書いたときも、生成を止めます。
既定値
どこにも設定されていなければ、フィールドはゼロ値になるか、タグの default の値になります:
type Database struct {
PoolMaxConns int32 `default:"10"`
DialTimeout time.Duration `default:"5s"`
}文字列、bool、数、time.Duration、kanna-value の enum の既定値は、生成時に読み、Go の値(x.PoolMaxConns = 10、整数は書いたとおりの x.DirMode = 0755、x.DialTimeout = 5 * time.Second、enum の定数)として書き出します。NaN と +Inf は定数で表せないので math.NaN() と math.Inf(1) で書き、ルールは読むときに確かめます。読めなければ生成を止めます。そのうえで、値だけで、プログラムのコードを動かさず、ほかのフィールドなしに判定できるルール(required、長さ、比較、oneof、pattern)で確かめます。拒否されれば生成を止めます。設定しない限り、起動のたびに失敗するからです。rule=Type、eqfield、email、url、uuid、フックは読むときに確かめます。required や omitempty が型の IsZero メソッドに聞くフィールドも、そのルールをすべて読むときに確かめます。kanna-value の値オブジェクトと UnmarshalText を持つ型の既定値は、設定と同じく、どこにも設定されていないときに読みます。
default のない kanna-value の enum は、事実上必須です。どこにも設定されなければゼロ値のままで、enum の Validate が inclusion として拒否します。未設定を許すなら validate:"omitempty" を付けます。
読める型
フィールドの型に最初に当てはまったもので読みます:
| 型 | 読み方 |
|---|---|
time.Duration |
time.ParseDuration(30s、5m)。ナノ秒の数としては読まない |
| kanna-value の値オブジェクト | 持つ値を下のとおりに読み、コンストラクタに渡す |
| kanna-value の enum | コンストラクタ |
ポインタが UnmarshalText を持つ型 |
UnmarshalText(slog.Level、netip.Addr、time.Time) |
| 文字列か、それを基にした型 | テキストのまま |
| bool か、それを基にした型 | strconv.ParseBool |
| 整数か、それを基にした型 |
strconv.ParseInt か strconv.ParseUint(その大きさで)。Go のリテラルとして読むので、0755 は 8 進数で、0x1F、0o755、0b101、1_000 も読めます |
| 浮動小数点数か、それを基にした型 |
strconv.ParseFloat(その大きさで) |
整数は、flag パッケージの flag.Int と同じく、Go の整数リテラルの規則で読みます。環境変数、フラグ、ファイルのどれでも同じです。0x1F、0o755、0b101、1_000 も読めます。先頭が 0 なら 8 進数なので、0755 は 493 になり、08080 は誤りです。10 進数が先頭の 0 のせいで読めないときは、DATABASE_POOL_MAX_CONNS: invalid (octal=true, type=int32) のように、誤りに octal=true のパラメータが付きます。既定値が先頭の 0 のせいで読めないときは、その理由を示して生成を止めます。10 進数は、PORT=8080 のように先頭に 0 を付けずに書きます。
それ以外の型(ポインタ、スライス、マップ、構造体など)は、生成を止めます。カンマで区切ったリストなどは、UnmarshalText を持つ型を作って読みます。そのフィールドの dive は、要素を 1 つずつ確かめ、誤りを添字を付けた設定の名前(CORS_ALLOWED_ORIGINS[1])の下に置きます。入れ子の設定は、//kanna:config を付けた別の構造体にします。UnmarshalText を持つリストの型は、たとえば次のように書きます:
// Origins is read from a comma-separated list, such as CORS_ALLOWED_ORIGINS=https://a.example,https://b.example.
type Origins []string
func (o *Origins) UnmarshalText(text []byte) error {
*o = strings.Split(string(text), ",")
return nil
}
//kanna:config
type CORS struct {
AllowedOrigins Origins `validate:"required,dive,max=20"`
}dive が各 origin を確かめ、2 つ目が長すぎれば CORS_ALLOWED_ORIGINS[1]: too_long (count=20) と報告します。リスト自体に書いた min、max、len は要素の数を数え、文字列の too_short、too_long、wrong_length ではなく、too_few、too_many、wrong_count を報告します。
読めなかった誤りは、値ではなく、コードとパラメータで報告します。設定は秘密を持ちうるからです。読めない数、bool、期間は、型を付けた invalid です(DATABASE_POOL_MAX_CONNS: invalid (type=int32))。コンストラクタや UnmarshalText が返した誤りは、kanna-value のルールのようにコードを持てばそのまま返し、持たなければ型を付けた invalid にします。slog.Level の誤りは値を含むからです。コードがあっても値を含むことはあるので、コードとパラメータに何を入れるかは、その型を書いた人の責任です。type パラメータは、ログや構造化された誤りのためのもので、翻訳の文言で表示できるとは約束しません。実行時に読む既定値が読めなかったときは、既定値のテキストは付けず、default=true のパラメータを加えます(SERVER_LEVEL: invalid (default=true, type=slog.Level))。既定値が破ったルールの誤りには付けません。
検証
validate タグは kanna-validator と同じ意味で、LoadX が確かめます。//kanna:validate は要りません。構造体の validate(errs *validator.Errors) メソッド(kanna-validator のフック)は、タグのあとで呼びます。
LoadX は 2 段階で誤りを返します:
- すべての設定を読み、読めなかったものがあれば、その誤りを返します。このときはルールを確かめません。
- すべて読めたら、ルールとフックの誤りを返します。
読めなかった設定のフィールドは、読んだ値を持ちません。そのままルールを確かめると、フィールドをまたぐルールやフックが、欠けた値を見て誤りを報告しかねないからです。
誤りは、その設定をした場所での名前の下に置きます。環境変数、database.pool_max_conns、-database-pool-max-conns のいずれかで、どこにも設定されていなければ環境変数の名前です。パスの Segments では、環境変数とフラグは綴りによらず 1 つのフィールドの区切りで、ファイルの設定はセクションとキーの 2 つの区切りです(validator.Field("database", "pool_max_conns") と同じ)。フィールドの型自身の Validate が返す誤りは、その名前の下に残ります(DATABASE_PRIMARY.host)。フックは kanna-validator と同じく、フィールドを validator.Field と JSON の名前(なければ Go の名前)で名指します。kanna-config は、フックのパスを生成時に確かめ、フックが返した誤りを、Field でも Segments でも、フィールドの設定の名前の下に移します。パスのうち、フィールドの名前より後ろはそのまま残します。構造体全体の誤りは base のままです。
コード付きにするのは、読むときの誤りだけです。ルールが返した誤りは、kanna-validator と同じくそのまま返します。同じルールが LoadX と Validate で同じ誤りを返すようにするためです。誤りに値を含めないのは、ルールを書いた人の責任です。kanna-value の rule.Fail と validator.Fail は値を含めません。
required は kanna-validator と同じく値のルールです。ゼロ値を拒否し、明示した 0 や false も拒否します。ゼロでない既定値があれば、どこにも設定されていなくても通ります。変数が設定されているかを確かめる書き方はありません。文字列の既定値なら、LoadX では required は必ず満たされますが、//kanna:validate も付けた構造体の Validate では、手で組み立てた値も確かめます。
LoadX のために Validate は生成しません。ほかで呼びたいときは、//kanna:validate も付けます。そのときも LoadX は自分でルールを確かめるので、付けても LoadX は変わりません。
生成されるもの
//kanna:config を付けた構造体 X ごとに、config_gen.go に次の 2 つを書きます:
-
DefineXFlags(fs *flag.FlagSet):Xのフラグを、LoadXが読む名前と既定値で定義します。 -
LoadX(src source.Source) (X, error):Xを読んで確かめます。エラーは、あればvalidator.Errorsです。
同じ名前の関数を手で書いていると、生成を止めます。kanna-di は、X のパッケージにある LoadX を、source.Source から X を作るものとして見つけます。
LoadX のテストは、t.Setenv で変数を設定します。t.Parallel とは一緒に使えません。設定を使う側のテストは、構造体を直接作り、並列にできます。
caarlos0/env から移る
env:"…" に書いた名前は caarlos0/env と同じに読み、envDefault:"…" は default:"…" になります。ただし、読み方は違います。空の変数は未設定で、読める型は上のものだけで、required はゼロ値を拒否します。ほかのタグとオプションは、違いを示して生成を止めます:
| caarlos0/env | kanna-config |
|---|---|
envDefault:"…" |
default:"…" |
env:"X,required" |
変数が設定されているかは確かめません。validate:"required" は値がゼロでないことを求め、0 や false も拒否します |
env:"X,notEmpty" |
近いのは validate:"required" ですが、0 や false も拒否します |
envPrefix |
入れ子の構造体は読みません。//kanna:config を付けた別の構造体にし、接頭語は prefix= で書きます |
envSeparator、envKeyValSeparator
|
スライスとマップは読みません。UnmarshalText を持つ型を作ります |
env:"X,file" |
X_FILE がファイルを名指します。ほかの形で渡すパスは、LoadX のあとで config:"-" のフィールドに読みます |
env:"X,expand" |
LoadX のあとで os.ExpandEnv を呼びます |
env:"X,unset" |
LoadX のあとで os.Unsetenv を呼びます |
env:"X,init" |
ポインタは読まないので、要りません |
ほかにも違う点が 3 つあります。
-
envタグのないフィールドも、構造体とフィールドの名前で決まる名前で読み、フラグも作ります。読ませないフィールドにはconfig:"-"を付けます。 -
Options.Prefixにあたるものはありません。接頭語は構造体ごとにprefix=で決め、env:"…"で書いた変数には付きません。 -
.envファイルは読みません。godotenv で読んでいたプログラムは、これまでどおりsource.Openの前に自分で読み込みます。
フラグ
kanna-config [flags] [packages]| フラグ | 意味 |
|---|---|
-tags <list> |
カンマ区切りのビルドタグ |
-check |
書き出す代わりに、出力が最新であることを検証する。不要な出力が残っていないことも含む。KANNA_CHECK=1 でも同じ |
-v |
書き出した、削除した、変更しなかったファイルを一覧表示する |
-deps |
実行が読み書きするものを、kanna コマンドのために JSON で表示して終了する |
-version |
バージョンを表示する |
対象のパッケージは、指定しなければカレントディレクトリのパッケージなので、//go:generate go tool kanna-config に引数は不要です。成功した実行は、警告以外何も出力しません。警告の 1 つは実行そのものについてのものです。対象のパッケージに //kanna:config を付けた構造体が 1 つもなければ、残っている //go:generate の行は無害なので成功しますが、そのことを知らせます:
$ go generate ./...
warning: no struct is marked //kanna:config in example.com/app/config構造体の型でないもの(type Level string、型の別名、インターフェース、関数など)に付けたディレクティブは、読まれることがないのでエラーです。
サンプル
example は、サーバーの設定を、YAML のファイル、TOML のファイル、環境変数、フラグから読み、それぞれが与えるものと、読めない設定やルールに反する設定の誤りを表示します。CI はこれを再生成し、出力が変わる場合は失敗します。
開発
make test # unit tests, in the root module and in yaml and toml
make lint # golangci-lint
make example # regenerate the example, vet it, and run it