protovalidate
v0.9.0
protovalidate ist eine Reihe von Bibliotheken zur Validierung von Protobuf-Nachrichten zur Laufzeit basierend auf benutzerdefinierten Validierungsregeln. Basierend auf der Common Expression Language (CEL) von Google bietet es eine flexible und effiziente Grundlage für die Definition und Auswertung benutzerdefinierter Validierungsregeln. Das Hauptziel von protovalidate besteht darin, Entwicklern dabei zu helfen, die Datenkonsistenz und -integrität im gesamten Netzwerk sicherzustellen, ohne dass generierter Code erforderlich ist.
Notiz
protovalidate ist der spirituelle Nachfolger von Protoc-Gen-Validate. Es erfordert keine Codegenerierung und unterstützt benutzerdefinierte Einschränkungen.
Wir empfehlen, dass neue und bestehende Projekte auf die Verwendung von protovalidate anstelle von protoc-gen-validate umsteigen.
Lesen Sie unseren Blogbeitrag, wenn Sie mehr über die Einschränkungen von protoc-gen-validate und darüber erfahren möchten, wie wir protovalidate verbessert haben.
Dieses Repository ist der Kern des protovalidate -Projekts. Es enthält:
protovalidate effektiv anprotoc-gen-validate.proto Dateien mit protovalidateprotovalidate Laufzeitimplementierungen von protovalidate finden Sie in ihren eigenen Repositorys:
protovalidate-go (Beta-Version)protovalidate-cc (Betaversion)protovalidate-java (Betaversion)protovalidate-python (Betaversion)protovalidate-ts (in Kürze erhältlich)Möchten Sie Unterstützung für eine andere Sprache hinzufügen? Schauen Sie sich unsere Beitragsrichtlinien an.
Um Einschränkungen in Ihren Protobuf-Nachrichten zu definieren, importieren Sie buf/validate/validate.proto in Ihre .proto Dateien:
syntax = "proto3" ;
package my.package ;
import "buf/validate/validate.proto" ;buf Fügen Sie eine Abhängigkeit von buf.build/bufbuild/protovalidate zur buf.yaml Ihres Moduls hinzu:
version : v1
# <snip>
deps :
- buf.build/bufbuild/protovalidate
# <snip> Vergessen Sie nach der Änderung Ihrer buf.yaml nicht, buf mod update auszuführen, um sicherzustellen, dass Ihre Abhängigkeiten auf dem neuesten Stand sind.
protoc Fügen Sie Ihrem Aufruf von protoc einen Importpfad (Flag -I ) hinzu, der auf den Inhalt des Verzeichnisses proto/protovalidate verweist:
protoc
-I ./vendor/protovalidate/proto/protovalidate
# <snip> Validierungseinschränkungen können mit dem Protobuf-Paket buf.validate erzwungen werden. Die Regeln werden direkt in den .proto Dateien angegeben.
Betrachten wir einige Beispiele:
Skalare Feldvalidierung: Für eine einfache User können wir Einschränkungen wie eine Mindestlänge für den Benutzernamen erzwingen.
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 ];
} Validierung des Kartenfelds: Bei einer Product mit einer Karte der Artikelmengen können wir sicherstellen, dass alle Mengen positiv sind.
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 ];
} Validierung des bekannten Typs (WKT): Für die User können wir eine Einschränkung hinzufügen, um sicherzustellen, dass der Zeitstempel created_at in der Vergangenheit liegt.
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 ];
} Für erweiterte oder benutzerdefinierte Einschränkungen ermöglicht protovalidate CEL-Ausdrücke, die feldübergreifende Informationen integrieren können.
Ausdrücke auf Feldebene: Wir können erzwingen, dass der price eines Produkts, der als Zeichenfolge gesendet wird, ein Währungssymbol wie „$“ oder „£“ enthält. Wir möchten sicherstellen, dass der Preis positiv und das Währungssymbol gültig ist.
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"
}];
} Ausdrücke auf Nachrichtenebene: Für eine Transaction können wir einen CEL-Ausdruck auf Nachrichtenebene verwenden, um sicherzustellen, dass das delivery_date immer nach dem purchase_date liegt.
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"
};
} Erzeugen einer Fehlermeldung im Ausdruck: Wir können benutzerdefinierte Fehlermeldungen direkt in den CEL-Ausdrücken erzeugen. Wenn in diesem Beispiel das age unter 18 Jahren liegt, wird der CEL-Ausdruck als Fehlermeldungszeichenfolge ausgewertet.
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': ''"
}];
} Sehen Sie sich examples für Beispiele sowohl zu Standardeinschränkungen als auch zu benutzerdefinierten CEL-Einschränkungen an.
Sobald die Nachrichten mit Einschränkungen versehen sind, verwenden Sie zur Validierung eine der unterstützten Sprachbibliotheken. keine zusätzliche Codegenerierung notwendig.
protovalidate bietet ein robustes Framework für die Validierung von Protobuf-Nachrichten, indem es Standard- und benutzerdefinierte Einschränkungen für verschiedene Datentypen durchsetzt und detaillierte Fehlerinformationen bereitstellt, wenn Validierungsverstöße auftreten. Eine detaillierte Übersicht über alle Komponenten, die unterstützten Einschränkungen und deren effektive Nutzung finden Sie in unserer umfassenden Dokumentation. Zu den Schlüsselkomponenten gehören:
Standardeinschränkungen : protovalidate unterstützt eine breite Palette von Standardeinschränkungen für alle Feldtypen sowie spezielle Funktionen für die Protobuf Well-Known-Types. Sie können diese Einschränkungen auf Ihre Protobuf-Nachrichten anwenden, um sicherzustellen, dass sie bestimmte allgemeine Bedingungen erfüllen.
Benutzerdefinierte Einschränkungen : Mit der Common Expression Language (CEL) von Google können Sie protovalidate komplexe, benutzerdefinierte Einschränkungen erstellen, um einzigartige Validierungsszenarien zu bewältigen, die nicht durch die Standardeinschränkungen sowohl auf Feld- als auch auf Nachrichtenebene abgedeckt werden.
Fehlerbehandlung : Wenn ein Verstoß auftritt, stellt protovalidate detaillierte Fehlerinformationen bereit, damit Sie die Ursache schnell identifizieren und ein Problem beheben können.
protovalidate ist der spirituelle Nachfolger von protoc-gen-validate und bietet die gleiche Funktionalität wie das ursprüngliche Plugin, ohne dass eine benutzerdefinierte Codegenerierung erforderlich ist, sowie die neue Fähigkeit, komplexe Einschränkungen in CEL zu beschreiben.
Die Einschränkungen von protovalidate sind denen in protoc-gen-validate sehr ähnlich, um Entwicklern einen einfachen Übergang zu ermöglichen. Um von protoc-gen-validate zu protovalidate zu migrieren, verwenden Sie das bereitgestellte Migrationstool, um Ihre .proto Dateien schrittweise zu aktualisieren.
Wird unter der Apache 2-Lizenz angeboten.
