kanna

kanna / validator

kanna-validator

v0.0.29 Go 1.27 pkg.go.dev

CI codecov Go Reference License: MIT Release English

kanna-validator は、構造体の validate タグから Validate メソッドを生成します。生成されるのは素の if 文で、リフレクションは使いません。破られたルールは、フィールドの JSON 名をキーにしたエラーコードで報告します。

kanna コードジェネレータファミリーの 1 つです。encoding/json/v2 を使うため、Go 1.27 以上が必要です。

インストール

go get -tool github.com/go-kanna/validator/cmd/kanna-validator

生成コードは、このモジュールのルートにある小さなランタイム github.com/go-kanna/validator を呼び出します。上のコマンドで依存に追加されます。

使い方

構造体に //kanna:validate を付け、go-playground/validator を使うときと同じようにルールを書きます:

package user

//go:generate go tool kanna-validator

//kanna:validate
type CreateUserRequest struct {
	Name     string   `json:"name"     validate:"required,max=50"`
	Age      int      `json:"age"      validate:"gte=18,lte=130"`
	Role     string   `json:"role"     validate:"required,oneof=admin member guest"`
	Tags     []string `json:"tags"     validate:"max=5,dive,max=20"`
	Address  Address  `json:"address"  validate:"required"`
	Password string   `json:"password" validate:"required,min=12"`
	Confirm  string   `json:"confirm"  validate:"eqfield=Password"`
}

//kanna:validate
type Address struct {
	Zip string `json:"zip" validate:"required,pattern=^\\d{3}-\\d{4}$"`
}

go generate ./... を実行すると、同じディレクトリに validator_gen.go が書き出されます:

// Code generated by kanna-validator. DO NOT EDIT.

func (x CreateUserRequest) Validate() error {
	var errs validator.Errors

	if x.Name == "" {
		errs.Add(validator.Field("name"), validator.Blank())
	} else {
		if utf8.RuneCountInString(x.Name) > 50 {
			errs.Add(validator.Field("name"), validator.TooLong(50))
		}
	}

	if x.Age < 18 {
		errs.Add(validator.Field("age"), validator.GreaterThanOrEqualTo(18))
	}
	// ...

	for i := range x.Tags {
		if utf8.RuneCountInString(x.Tags[i]) > 20 {
			errs.Add(validator.Field("tags").Index(i), validator.TooLong(20))
		}
	}

	if x.Address == (Address{}) {
		errs.Add(validator.Field("address"), validator.Blank())
	} else {
		errs.Nest(validator.Field("address"), x.Address.Validate())
	}
	// ...

	return errs.Err()
}

どのルールも、読めて、デバッガで止めることもできる if 文です。タグを変更すると生成コードも変わるので、ルールの変更はレビューに現れます。

kanna のジェネレータを 2 つ以上使うなら、必要な順に動かす go tool kanna gen で実行してください。

存在しないルールやフィールドに合わないルールは、それに当たる最初のリクエストを止めるのではなく、生成を止めます:

$ go generate ./...
./request.go:5:2: error: unknown rule "requried" (field Name)
  did you mean "required"?
./request.go:6:2: error: rule "email" cannot apply to int (field Age)
./request.go:7:2: error: rule "max" cannot apply to uint8 (field Level)
  max measures strings, slices, and maps; compare a number with lte
./request.go:8:2: error: invalid pattern: error parsing regexp: missing closing ]: `[0-9` (field Zip)
./request.go:10:2: error: eqfield=Pasword: no such field (field Confirm)
  did you mean "Password"?

スペルミスのあるディレクティブには警告が出ます。空行で構造体から離れていて、その doc コメントになっていないディレクティブにも警告が出ます。警告がなければ、構造体に Validate がないまま、何も知らされないことになります:

./request.go:3:1: warning: "//kanna:validte" is not recognized as a directive
  did you mean "//kanna:validate"?
./request.go:9:1: warning: //kanna:validate is not attached to a declaration, so nothing reads it
  write it right above what it marks, with no blank line between

ルール

タグは go-playground/validator のもの、コードとパラメータは Rails の ActiveModel::Validations のものです。

タグ 対象 コード パラメータ
required ゼロ値を持つものすべて blank
min, max, len 文字列(文字数で数える) too_short, too_long, wrong_length count
min, max, len スライス、マップ(要素の数で数える) too_few, too_many, wrong_count count
gt, gte, lt, lte, eq, ne 数値 greater_than, greater_than_or_equal_to, less_than, ..., other_than count
oneof=a b 'c d' 文字列、整数 inclusion
eqfield=Field 同じ型のフィールド、またはそのポインタ confirmation attribute: 相手のフィールドの JSON 名
pattern=regexp 文字列 invalid
email, url, uuid 文字列 email, url, uuid(go-kanna/value のもの)
rule=Type, rule=pkg.Type Type が保持するもの ルール自身のコード ルール自身のパラメータ
omitempty ゼロ値を持つものすべて ゼロ値には、後に続くルールを適用しない
dive スライス、配列、マップ 後に続くルールを各要素に適用する。マップでは各値に適用する

Rails はコレクションの長さも文字列と同じコードで報告しますが、スライスとマップの長さには別のコードを出すので、メッセージで文字数ではなく要素の数を示せます。文字数は、go-playground と同じく rune で数えます。e と結合用のアクセントで書いた é は 2、家族の絵文字 👨‍👩‍👧 は 5 です。pattern= は、Go の regexp.MatchString や JSON Schema の pattern と同じく、文字列のどこかに一致すれば通します。pattern=\d{3} は "a123b" を通すので、全体に一致させるには ^ と $ を書きます。

go-playground との違い:

  • フィールドが破ったルールは、最初の 1 つだけでなくすべて報告されます。例外は required を満たさない値で、blank だけが報告されます。他に破っているルールがあっても、値がないことを繰り返し伝えるだけだからです。
  • required は「ゼロ値ではない」という意味です。ゼロ値とは ""、0、false、nil のことで、IsZero() を持つ型ではそのメソッドで判定します。nil でない空のスライスは値があるものとして扱われます。長さは min=1 で制限してください。0 を送ることと何も送らないことは区別されません。そのため、0 や、ルールがゼロ値を受け入れる値オブジェクトのゼロ値を、値がない状態とは別の値として扱う場合は、フィールドをポインタにしてください。そうすると required は nil だけを報告します。
  • nil ポインタには required 以外のどのルールも適用されません。max=20 を付けた *string は nil を受け入れますが、required,max=20 を付けたものは受け入れません。eqfield がポインタのフィールドを名指すと、ポインタに書いたルールと同じく、指す先と比べます。nil のポインタはどの値とも等しくありません。別の *string と一致を求める *string は、自分があって相手がないときに報告されます。
  • 浮動小数点数の NaN は、適用されるすべての比較に違反します。gte=0 でも lte=100 でも報告されます。生成コードは !(x >= 0) のように条件を否定した形でチェックします。x < 0 では NaN を通してしまうからです。ne=0 も NaN を報告します。NaN はどの数とも違うからです。
  • pattern= はカンマも含めてタグの残り全体を受け取るので、最後に書きます。後ろに ,max=20 のようなルールが続いていると、正規表現の一部になることを警告します。タグの値は Go の文字列リテラルなので、バックスラッシュは \\ と書きます。アンクォートできないタグは、黙って読み飛ばされるのではなく生成を止めます。Go が読まない validate のキー(Validate:"required"、空白のある validate: "required"、1 つのタグの 2 つ目の validate のキー)も、生成を止めます。
  • validate:"-" は生成を止めます。validate タグのないフィールドは、もともと検査されないからです。ただし、Validate を持つ型は、いつも検査します。
  • min、max、len は長さだけを制限します。数値は gte、lte、eq で比べ、数値に min=18 と書くとその旨を示して生成を止めます。文字列に gte を書くと止まるのと同じく、1 つのルールが 1 つの意味だけを持つようにするためです。
  • time.Duration は、gte=1s や oneof=0 500ms のように time.ParseDuration が読む形の時間と比べます。ナノ秒の数で書くと生成を止めます。count は Go が表示する形の文字列で、gte=90s なら "1m30s" です。メッセージでも、encoding/json と encoding/json/v2 のどちらでも同じになります。
  • omitempty は、同じ階層のルールの中で最初に書きます。後ろのルールにゼロ値を通すからです。ほかのルールの並びは自由ですが、後ろのルールを要素ごとに適用する dive と、タグの残りを取る pattern= は別です。ポインタとインターフェースに書くと、何もしないので生成を止めます。nil のポインタやインターフェースは、もともと required 以外のルールを飛ばすからです。go-playground では、そのために omitempty が要ります。同じ階層で後ろにルールがないときも、生成を止めます。ただし、ゼロ値に型の Validate や配列の要素の検査を飛ばさせるときは別です。string に omitempty だけを書くことや、スライスやマップの dive の前に書くこと(ゼロ値には要素がない)は、何もしないからです。
  • omitempty は required の裏返しで、ゼロ値だけを通します。空でも nil でないスライスやマップはゼロ値ではないので、omitempty,min=1 は []string{} を報告します。go-playground と同じです。encoding/json/v2 でいえば、空の値を省く omitempty ではなく、omitzero にあたります。
  • 名前のない構造体(Meta struct{ ... } や []struct{ ... })のフィールドにタグを書くと、生成を止めます。Validate は名前のある型にしか作れないので、そのタグは検査されないからです。構造体に名前を付け、//kanna:validate を付けてください。_ という名前のフィールドのタグも、生成を止めます。そのフィールドは誰も読めないからです。タグのない _ のフィールドは、型が自分を検査するものであっても、何もせずに飛ばします。
  • 1 つの階層で同じ範囲のルールを 2 回書くこと(max=5,max=10)と、一緒に満たす値のない 2 つのルール(gte=10,lte=5、gt=1,lte=1、gte=18,eq=7)は、生成を止めます。go-playground はどれも検査するので、そのフィールドは何を入れても通らないからです。
  • 型だけで結果が決まるルールは、生成を止めます。どの値も通るもの(min=0、uint の gte=0、uint8 の lte=255)は何も検査せず、どの値も通らないもの(uint8 の gt=255)は、そのフィールドが何を持っても失敗するからです。端は整数の型のもので、int と uint は 64 ビットとみなします。浮動小数点数には端がありません。無限大を持てるからです。time.Duration は負にもなるので、gte=0s は意味のあるルールです。
  • kanna-value の enum の oneof には、その定数の値を書きます。別のパッケージの enum では、そのパッケージが公開している定数の値です。確実に読み込めるのはそこまでだからです。どの定数でもない値(定数の打ち間違いなど)は、フィールドがその値を持てないので、生成を止めます。enum の Validate は oneof が通した値にだけ呼ぶので、oneof が拒否した値の inclusion は 1 回だけ報告します。
  • oneof の値は空白で区切り、空白を含む値は oneof='light blue' red のように単一引用符で囲みます。go-playground と同じ読み方です。'red や it's のように、値全体を囲んでいない引用符は生成を止めます。go-playground はその引用符を消し、書いたものとは別の値を検査するからです。値には単一引用符も、ルールを区切るカンマも含められません。
  • url が通すのは、ホスト名のある絶対 URL、つまりリクエストが届くアドレスです。go-playground がスキームのある URI として通す mailto:a@example.com、javascript:alert(1)、file:///etc/passwd を報告します。go-playground がやはり通す https://:80、65535 を超えるポート、空白(https://example.com/a b)も報告します。どちらもスキームは確かめません。javascript://example.com/%0Aalert(1) はどちらも通すので、URL をリンクに書く前にスキームを確かめてください。ルールは go-kanna/value のもので、go.mod が require するバージョンのものが動きます。v0.0.18 は、ポートだけでホスト名のない URL、65535 を超えるポート、空白をまだ通します。
  • email は、Go の net/mail が読む形(RFC 5322)の、飾りのないアドレスの構文を確かめます。ドメインが存在しうるかは見ません。a@b、a@localhost、a@[127.0.0.1]、a@-b.com は通ります。go-playground は独自の正規表現でこれらを拒否します。メールが届くかどうかは、そのアドレスに送ってみないと分かりません。net/mail が書き直す形のアドレスは拒否します。引用符つきのローカル部("a b"@example.com)は go-playground が通す形ですが、値をいつも書いたとおりの形で保つためです。

rule=Type は、Type のルールをフィールドの値に適用します。dive の後では各要素に適用します。Type には 2 種類あります。1 つ目は kanna-value の値オブジェクトで、kanna-value が与える形から判別され、コンストラクタ NewType(T) (Type, error) が値にルールを守らせます。2 つ目は kanna-value の enum で、コンストラクタ NewType(string) (Type, error) は定数だけを受け入れます。自分のルールは、構造体の validate メソッドに書きます(ネストとフックを参照)。構造体のあいだで共有する関数を、そこから呼ぶこともできます。修飾なしの Type は、その構造体のパッケージの型を指します。pkg.Type のパッケージは、Go がコードの pkg.Type を読むのと同じく、構造体のファイルがそのパッケージを import している名前で決まります。Go は使っていない名前つきの import を拒むので、タグでしか使わないパッケージは _ で import します。そのパッケージは、パッケージ自身の名前で呼びます。ほかを探すことはしないので、ファイルが import していないパッケージはエラーになります。エラーには、何を import すればよいかが示されます。生成コードは、コンストラクタが返したものを、ルールが与えたコードとパラメータとともにそのフィールドに記録します。

ネストとフック

Validate() error を持つ型、またはこれから持つ型のフィールドは、そのメソッドでバリデーションされます。別の //kanna:validate の構造体、kanna-value が Validate を書く //kanna:enum の付いた string 型、自前でバリデーションを書いた型、インターフェースがこれに当たります。エラーはそのフィールドの下にネストされます。address.zip、items[2].sku、マップなら labels.primary のようになります。マップのキーは encoding/json が書き出すとおりに綴り、String メソッドは使いません。そのような型のスライス、配列、マップは、dive がなくても要素ごとにバリデーションされます。マップはキーの順に、構造体のように順序のないキーなら綴った名前の順に回すので、エラーの並びはいつも同じです。埋め込んだポインタやインターフェースを経由して Validate を持つ型は、フィールドの nil ポインタがスキップされるのと同じように、それらが nil でないときだけバリデーションされます。別のパッケージが公開していないために nil を確認できないときは、生成を止めます。JSON 名のない埋め込み構造体のエラーは、encoding/json がそのフィールドを平坦化するのと同じように、埋め込んでいる構造体の階層に置かれます。json:"-" を付けた埋め込みは、encoding/json が平坦化せずに外すので、ほかの json:"-" のフィールドと同じく、Go の名前の下に置かれます。

2 つのフィールドにまたがるルールのように、タグでは表現できないルールは validate メソッドに書きます。生成された Validate は、すべてのタグをチェックした後でこのメソッドを呼び出します:

func (x CreateUserRequest) validate(errs *validator.Errors) {
	if x.Role == "admin" && x.Age < 21 {
		errs.Add(validator.Field("age"), validator.Fail("too_young_for_admin"))
	}
}

パスは validator.Path です。validator.Field("address", "zip") は、フィールドを JSON 名で辿るパスを作ります。その先は Path のメソッドで書きます。Index は要素に、Key はマップの値に、Field はその下のフィールドに進みます。items[2].sku なら validator.Field("items").Index(2).Field("sku") です。Key は、validator.Field("labels").Key(k) のようにマップのキーをそのまま受け取り、encoding/json がキーを名付けるのと同じ形の文字列にします。構造体全体に関するエラーは、Rails と同じく validator.Base("base")の下に置きます。Add に、ほかの Validate が返したものなどの Errors を渡すと、Nest と同じく、その 1 つずつをパスの下に移します。

kanna-validator は、生成するときに、フックがエラーを置くパスを検査します。対象は、渡された Errors の Add と Nest の第 1 引数のうち、定数を渡した validator.Field、validator.Base、validator.Path{} で始まり、Index、Key、定数を渡した Field で続くものです。パスは、フィールドをそのエラーが置かれる名前で辿り、どこで終わっても、base で終わってもかまいません。何も指さないパスがあれば、生成を止めます:

user.go:42:11: error: "aeg" is not a path of CreateUserRequest: CreateUserRequest has no field "aeg"
  did you mean "age"?

validator.Field に渡す名前は 1 つずつが 1 つのフィールドなので、validator.Field("address.zip") は address.zip という名前のフィールドを指し、validator.Field("address", "zip") と書くようヒントを出します。kanna-validator が Validate を書かない型と、インターフェースの先は、何を報告するかはその Validate 次第なので見ません。そのような型を JSON 名なしで埋め込んでいれば、その階層ではどの名前も通します。Add(validator.Path{}) も生成を止めます。構造体全体のエラーは validator.Base に置くからです。Nest(validator.Path{}) は、埋め込み構造体と同じく、ネストしたものを構造体の階層に置くので通します。パスの位置に文字列の定数を書く(Add("id", …))と生成を止め、validator.Field("id")、"address.zip" なら validator.Field("address", "zip")、"base" なら validator.Base と書くようヒントを出します。スライス、マップ、関数、またはそれを含む配列や構造体のように比較できない型のキーを Key に渡す呼び出しも、実行時に panic するので生成を止めます。validator.Field(name) のように実行時にしか分からない名前で組み立てるパスと、変数に入れたパスから続けるパスは検査しません。

エラー

Validate は validator.Errors か nil を返します。これは Rails が errors.details をエンコードするのと同じ形式にエンコードされ、フィールドは最初にルールが破られた順に並びます:

{
  "name": [{"error": "blank"}],
  "tags[1]": [{"error": "too_long", "count": 20}],
  "confirm": [{"error": "confirmation", "attribute": "password"}]
}

それぞれの FieldError は、パスを上のキーである Field と、Segments の両方で持ちます。Segments は、フィールド(validator.FieldSegment)とマップのキー(validator.KeySegment)と添字(validator.IndexSegment)を見分けます。キーはリクエストが送ってきたものそのままで、labels.first_note はフィールドと同じ形に綴られます。Segments を使えば、フィールドを名指すメッセージは、キーではなくパスの最後のフィールドの名前を使えます。FieldNames は、フィールドのセグメントの名前だけを []string で並べるので、go-kanna/i18n のようなパッケージは、validator を import せずに、interface を通してフィールドを名付けられます。

フィールドのキーは、トランスポートが何であっても、json タグが与える名前か、タグがなければ Go の名前です。gRPC ハンドラの裏側にある、json タグのないユースケースの入力は TodoID と報告します。proto で宣言された名前で報告するには、フィールドに json:"id" タグを付けてください。protoc-gen-go が生成するメッセージには、proto のフィールド名を持つ json タグが最初から付いています。

拒否された値がエラーに含まれることは決してありません。エラーはログに残るものであり、値は個人情報かもしれないからです。

リクエストのデコード

validator.DecodeJSON は、リクエストボディをデコードしてバリデーションし、問題をすべてまとめて報告します:

r.Body = http.MaxBytesReader(w, r.Body, 1<<20)
var req user.CreateUserRequest
if err := validator.DecodeJSON(r.Body, &req); err != nil {
	if errs, ok := errors.AsType[validator.Errors](err); ok {
		writeJSON(w, http.StatusUnprocessableEntity, map[string]any{"errors": errs})
		return
	}
	// A *validator.DecodeError: JSON that cannot be read at all.
	writeJSON(w, http.StatusBadRequest, map[string]any{"error": err})
	return
}

kanna-value の値オブジェクトのように、デコード中に型が値を拒否するフィールドがあっても、デコードは止まりません。拒否はそのフィールドのパスに報告され、残りの部分のタグで見つかったエラーと一緒に並びます。json.Unmarshal にはこれができません。最初の拒否で止まり、どのフィールドで起きたかも示しません。DecodeJSON は encoding/json/v2 を通してデコードします。encoding/json/v2 は名前の大文字と小文字を区別して照合し、重複した名前を拒否します。

構造体にフィールドのない名前は、encoding/json と encoding/json/v2 の既定と同じく読み飛ばします。サーバーがまだ読まないものをクライアントが送ってもよいようにするためです。綴りを誤った名前ではそのフィールドが設定されないままになり、required があればそれを報告します。{"titl":"x"} は title: blank と報告されます。DecodeJSON は r を大きさの制限なく終わりまで読みます。リクエストの本文は、渡す前に http.MaxBytesReader で制限してください。

デコード先は、//kanna:validate を付けた構造体のように、自分を検証できる型でなければなりません。ルールのない構造体でも、付ければ検証できる型になります。付け忘れた構造体は、検証されずに通るのではなく、コンパイルが通りません。

ルールを破ったのではなく、そもそも読めないリクエストは、*validator.DecodeError で失敗します。読めなかった場所の JSON ポインタと、次の理由のどれかを持ちます。

理由 リクエストが
syntax JSON でない、または途中で切れている
trailing JSON の値の後にまだ続く
duplicate_name オブジェクトで名前を繰り返している
value Go の型が受け取らない値を持つ(範囲を超える数など)
read 読めなかった(http.MaxBytesReader が打ち切ったときなど)

JSON では {"pointer":"/age","reason":"value"} になり、メッセージは validator: cannot decode JSON at "/age": value です。ルールのエラーと同じく、どちらにも値も、値を入れるはずだった Go の型も含まれないので、どちらもそのままリクエストへの応答に使えます。両方を含む encoding/json/v2 のエラーは、errors.As で取り出せます。大きすぎる本文の *http.MaxBytesError も同じで、413 で応答したいハンドラはそれを見ます。

kanna-value との連携

kanna-value は、値がどこを通っても、つまり作られるときも、デコードされるときも、データベースからスキャンされるときも、ルールを守らせる値オブジェクトを生成します。タグの email、url、uuid は、そのパッケージ rule にある同じルールを呼び出し、同じコードを報告します。そのため、タグでチェックした形式も型が保持する形式も、API レスポンスでは同じように見えます。

//kanna:value
type Email struct{ s string }

func (Email) validate(s string) error { return rule.Email(s) }

//kanna:validate
type SignUp struct {
	Email   Email  `json:"email"   validate:"required"`      // the type holds the format; the tag, that it is there
	Website string `json:"website" validate:"omitempty,url"` // the tag checks the format of a plain string
}

kanna-value の enum は、生成された UnmarshalText と Validate が定数だけを受け入れる string 型です。定数を oneof で並べ直す必要はなく、同じコード inclusion を報告します:

//kanna:validate
type ListOrders struct {
	Status *model.OrderStatus `json:"status"` // nil when omitted; "shiped" is reported as inclusion
}

rule= は、値オブジェクトのルールを、そのコンストラクタを通して普通のフィールドに適用します。gRPC メッセージのように JSON 以外から組み立てられるリクエストでは、*time.Time を受け取り、model.CompletedAt と同じようにチェックできます:

import (
	"time"

	_ "example.com/app/model"
)

//kanna:validate
type UpdateTask struct {
	CompletedAt *time.Time `json:"completed_at" validate:"rule=model.CompletedAt"` // nil skips it
}
	if x.CompletedAt != nil {
		if _, err := model.NewCompletedAt(*x.CompletedAt); err != nil {
			errs.Add(validator.Field("completed_at"), err)
		}
	}

同じように、rule=model.OrderStatus と書けば、普通の string を enum の定数に対してチェックできます。

go-kanna/value は独立したモジュールです。これらのタグを使うときは go get github.com/go-kanna/value を、その型を使うときは go get -tool github.com/go-kanna/value/cmd/kanna-value を実行してください。生成されたファイルがこのモジュールを必要としているのに go.mod が require していない場合は、後からビルドが失敗するのではなく、警告が出ます:

./validator_gen.go: warning: imports github.com/go-kanna/value/rule, which go.mod does not require; run go mod tidy

Lint

wrapcheck は、手書きの Validate 内の return errs.Err() を、別パッケージからのラップされていないエラーとして報告します。Err は集めたものを返すだけで、その下にラップすべき原因はないので、wrapcheck が無視するシグネチャに追加してください:

linters:
  settings:
    wrapcheck:
      extra-ignore-sigs:
        - validator.Errors).Err(

フラグ

kanna-validator [flags] [packages]
フラグ 意味
-tags <list> カンマ区切りのビルドタグ
-check 書き出す代わりに、出力が最新であることを検証する。不要な出力が残っていないことも含む。KANNA_CHECK=1 でも同じ
-v 書き出した、削除した、変更しなかったファイルを一覧表示する
-deps 実行が読み書きするものを、kanna コマンドのために JSON で表示して終了する
-version バージョンを表示する

パッケージのデフォルトはカレントディレクトリのパッケージなので、//go:generate go tool kanna-validator に引数は不要です。成功した実行は、警告以外何も出力しません。警告の 1 つは実行そのものについてのものです。対象のパッケージに //kanna:validate を付けた構造体が 1 つもない場合、残っている //go:generate の行は無害なので実行は成功しますが、その行も消すつもりだった可能性が高いので、そのことを知らせます:

$ go generate ./...
warning: no struct is marked //kanna:validate in example.com/app/user

Validate は、初回の実行で書き出される前から呼び出していても構いません。kanna-validator は読み込んだパッケージを、これから書き出す内容を組み込んだ状態でもう一度型チェックし、コンパイルが通らない間は何も書き出しません。メソッドがないために隠れていた間違い、たとえば Validate の戻り値を合わない場所に渡すことも、このとき報告されます。

すべての構造体から //kanna:validate がなくなったパッケージの validator_gen.go は、実行時に読み込んだパッケージのコードがその Validate をまだ呼び出していない限り、削除されます。同じ名前でも生成コードのヘッダがないファイルには決して触れません。ファイルを削除する go generate は open ...: no such file or directory で終わります。これは go generate 自身のエラーで、ジェネレータを実行する前にパッケージのファイルを列挙しているためです。ファイルは意図どおり削除されています(golang/go#36068)。

サンプル

example は、ハンドラと同じようにサインアップのリクエストをデコードし、それぞれが受け取るレスポンスを表示します。リクエストは、有効なもの、すべてが一度に間違っているもの、空のもの、フックが拒否するもの、不正な形式の JSON です。CI はこれを再生成し、出力が変わる場合は失敗します。

パフォーマンス

bench は、使い方 のものと同じようなリクエストを、生成された Validate と go-playground/validator でバリデーションします。どちらも同じタグを読みます。go-playground にない pattern= の代わりには len=8 を使います。go-playground は、必須の構造体がゼロ値でないことを求め、フィールドを JSON 名で示すように設定して、kanna-validator と同じ内容を報告させています。両者が同じフィールドを不正と判定しなければ、テストが失敗します。

リクエスト バリデータ ns/op B/op allocs/op
有効 kanna-validator 19 0 0
有効 go-playground/validator v10.30.5 553 432 18
7 フィールドが不正 kanna-validator 468 1816 25
7 フィールドが不正 go-playground/validator v10.30.5 995 2210 51

Apple M5 Pro 上の Go 1.27.3 で 10 回実行した中央値です。生成された Validate は、有効なリクエストを go-playground の約 30 倍の速さでチェックします。不正なリクエストは約 2 倍の速さで、バイト数を 18%、アロケーション回数を 51% 減らしてチェックします。有効なリクエストのコストは if の分だけで、アロケーションはありません。不正なリクエストのコストは報告するエラーの分で、エラーはそれぞれコードとパラメータとパスとともに作られます。

make bench                       # run it once
make bench BENCHFLAGS=-count=10  # often enough for benchstat

開発

make test       # unit tests
make lint       # golangci-lint
make example    # regenerate the example, then build and run it
make bench      # regenerate the benchmark, then run it

ライセンス

MIT