protovalidate
v0.9.0
protovalidateは、ユーザー定義の検証ルールに基づいて実行時に Protobuf メッセージを検証するように設計された一連のライブラリです。 Google の Common Expression Language (CEL) を利用して、カスタム検証ルールを定義および評価するための柔軟かつ効率的な基盤を提供します。 protovalidateの主な目的は、開発者が生成されたコードを必要とせずにネットワーク全体でデータの一貫性と整合性を確保できるようにすることです。
注記
protovalidate protoc-gen-validate の精神的な後継者です。コード生成は必要なく、カスタム制約をサポートします。
新規および既存のプロジェクトは、 protoc-gen-validateの代わりにprotovalidate使用するように移行することをお勧めします。
protoc-gen-validateの制限と、 protovalidateより良くするためにどのように設計したかについて詳しく知りたい場合は、ブログ投稿をお読みください。
このリポジトリは、 protovalidateプロジェクトの中核です。これには以下が含まれます:
protovalidate効果的に適用する方法protoc-gen-validateから段階的に移行protovalidateを使用した.protoファイルの例protovalidate実装の受け入れテスト用protovalidateのランタイム実装は、独自のリポジトリにあります。
protovalidate-go (ベータ版)protovalidate-cc (ベータ版)protovalidate-java (ベータ版)protovalidate-python (ベータリリース)protovalidate-ts (近日公開予定)別の言語のサポートを追加することに興味がありますか?貢献ガイドラインをご覧ください。
Protobuf メッセージ内で制約を定義するには、 buf/validate/validate.proto .protoファイルにインポートします。
syntax = "proto3" ;
package my.package ;
import "buf/validate/validate.proto" ;bufを使って構築するbuf.build/bufbuild/protovalidateへの依存関係をモジュールのbuf.yamlに追加します。
version : v1
# <snip>
deps :
- buf.build/bufbuild/protovalidate
# <snip> buf.yaml変更した後は、忘れずにbuf mod update実行して、依存関係が最新であることを確認してください。
protocでビルドするproto/protovalidateディレクトリの内容を指すインポート パス ( -Iフラグ) をprotocの呼び出しに追加します。
protoc
-I ./vendor/protovalidate/proto/protovalidate
# <snip>検証制約は、 buf.validate Protobuf パッケージを使用して強制できます。ルールは.protoファイルで直接指定されます。
いくつかの例を考えてみましょう。
スカラー フィールドの検証:基本的なUserメッセージの場合、ユーザー名の最小長などの制約を強制できます。
syntax = "proto3" ;
import "buf/validate/validate.proto" ;
message User {
// User's name, must be at least 1 character long.
string name = 1 [ (buf.validate .field ) .string .min_len = 1 ];
}マップ フィールドの検証:品目数量のマップを含むProductメッセージの場合、すべての数量が正であることを確認できます。
syntax = "proto3" ;
import "buf/validate/validate.proto" ;
message Product {
// Map of item quantities, all quantities must be positive.
map < string , int32 > item_quantities = 1 [ (buf.validate .field ) .map.values.int32 .gt = 0 ];
} Well-known type (WKT) 検証: Userメッセージに対して、 created_atタイムスタンプが過去であることを保証する制約を追加できます。
syntax = "proto3" ;
import "google/protobuf/timestamp.proto" ;
import "buf/validate/validate.proto" ;
message User {
// User's creation date must be in the past.
google.protobuf.Timestamp created_at = 1 [ (buf.validate .field ) .timestamp .lt_now = true ];
}より高度な制約またはカスタム制約の場合、 protovalidateフィールド全体の情報を組み込むことができる CEL 式が可能です。
フィールドレベルの式:文字列として送信される製品のprice 「$」や「£」などの通貨記号が含まれるように強制できます。価格が正であり、通貨記号が有効であることを確認したいと考えています。
syntax = "proto3" ;
import "buf/validate/validate.proto" ;
message Product {
string price = 1 [ (buf.validate .field ).cel = {
id : "product.price" ,
message : "Price must be positive and include a valid currency symbol ($ or £)" ,
expression : "(this.startsWith('$') || this.startsWith('£')) && double(this.substring(1)) > 0"
}];
}メッセージ レベルの式: Transactionメッセージの場合、メッセージ レベルの CEL 式を使用して、 delivery_date常にpurchase_dateより後になるようにすることができます。
syntax = "proto3" ;
import "google/protobuf/timestamp.proto" ;
import "buf/validate/validate.proto" ;
message Transaction {
google.protobuf.Timestamp purchase_date = 1 ;
google.protobuf.Timestamp delivery_date = 2 ;
option (buf.validate .message ).cel = {
id : "transaction.delivery_date" ,
message : "Delivery date must be after purchase date" ,
expression : "this.delivery_date > this.purchase_date"
};
}式でのエラー メッセージの生成: CEL 式で直接カスタム エラー メッセージを生成できます。この例では、 ageが 18 歳未満の場合、CEL 式はエラー メッセージ文字列として評価されます。
syntax = "proto3" ;
import "buf/validate/validate.proto" ;
message User {
int32 age = 1 [ (buf.validate .field ).cel = {
id : "user.age" ,
expression : "this < 18 ? 'User must be at least 18 years old': ''"
}];
}標準制約とカスタム CEL 制約の両方の例については、 examples確認してください。
メッセージに制約の注釈が付けられたら、サポートされている言語ライブラリのいずれかを使用して検証します。追加のコード生成は必要ありません。
protovalidateさまざまなデータ型に標準およびカスタムの制約を適用し、検証違反が発生した場合に詳細なエラー情報を提供することにより、Protobuf メッセージを検証するための堅牢なフレームワークを提供します。すべてのコンポーネントの詳細な概要、サポートされている制約、およびそれらを効果的に使用する方法については、包括的なドキュメントを参照してください。主要なコンポーネントには次のものが含まれます。
標準制約: protovalidateすべてのフィールド タイプの幅広い標準制約と、Protobuf Well-Known-Type の特別な機能をサポートします。これらの制約を Protobuf メッセージに適用して、メッセージが特定の一般的な条件を確実に満たすようにすることができます。
カスタム制約: Google の Common Expression Language (CEL) を使用すると、 protovalidate使用して複雑なカスタム制約を作成し、フィールド レベルとメッセージ レベルの両方で標準制約ではカバーされない独自の検証シナリオを処理できます。
エラー処理: 違反が発生すると、 protovalidate詳細なエラー情報を提供し、原因を迅速に特定して問題を修正するのに役立ちます。
protovalidateはprotoc-gen-validateの精神的な後継者であり、カスタム コード生成を必要とせずに元のプラグインに存在するすべての同じ機能と、CEL で複雑な制約を記述する新しい機能を提供します。
protovalidateの制約はprotoc-gen-validateの制約を非常に厳密にエミュレートし、開発者が簡単に移行できるようにします。 protoc-gen-validateからprotovalidateに移行するには、提供されている移行ツールを使用して.protoファイルを段階的にアップグレードします。
Apache 2 ライセンスに基づいて提供されます。
