protovalidate
v0.9.0
protovalidate es una serie de bibliotecas diseñadas para validar mensajes de Protobuf en tiempo de ejecución según reglas de validación definidas por el usuario. Impulsado por el lenguaje de expresión común (CEL) de Google, proporciona una base flexible y eficiente para definir y evaluar reglas de validación personalizadas. El objetivo principal de protovalidate es ayudar a los desarrolladores a garantizar la coherencia e integridad de los datos en toda la red sin necesidad de generar código.
Nota
protovalidate es el sucesor espiritual de protoc-gen-validate. No requiere generación de código y admite restricciones personalizadas.
Recomendamos que los proyectos nuevos y existentes pasen al uso de protovalidate en lugar de protoc-gen-validate .
Lea nuestra publicación de blog si desea obtener más información sobre las limitaciones de protoc-gen-validate y cómo hemos diseñado protovalidate para que sea mejor.
Este repositorio es el núcleo del proyecto protovalidate . Contiene:
protovalidate de manera efectivaprotoc-gen-validate.proto de ejemplo usando protovalidateprotovalidate Las implementaciones en tiempo de ejecución de protovalidate se pueden encontrar en sus propios repositorios:
protovalidate-go (versión beta)protovalidate-cc (versión beta)protovalidate-java (versión beta)protovalidate-python (versión beta)protovalidate-ts (próximamente)¿Interesado en agregar soporte para otro idioma? Consulte nuestras Pautas de contribución.
Para definir restricciones dentro de sus mensajes de Protobuf, importe buf/validate/validate.proto en sus archivos .proto :
syntax = "proto3" ;
package my.package ;
import "buf/validate/validate.proto" ;buf Agregue una dependencia en buf.build/bufbuild/protovalidate al buf.yaml de su módulo:
version : v1
# <snip>
deps :
- buf.build/bufbuild/protovalidate
# <snip> Después de modificar su buf.yaml , no olvide ejecutar buf mod update para asegurarse de que sus dependencias estén actualizadas.
protoc Agregue una ruta de importación ( -I flag) que apunte al contenido del directorio proto/protovalidate a su invocación de protoc :
protoc
-I ./vendor/protovalidate/proto/protovalidate
# <snip> Las restricciones de validación se pueden aplicar utilizando el paquete buf.validate Protobuf. Las reglas se especifican directamente en los archivos .proto .
Consideremos algunos ejemplos:
Validación de campo escalar: para un mensaje User básico, podemos aplicar restricciones como una longitud mínima para el nombre del usuario.
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 ];
} Validación del campo del mapa: para un mensaje Product con un mapa de cantidades de artículos, podemos asegurarnos de que todas las cantidades sean positivas.
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 ];
} Validación de tipo conocido (WKT): para el mensaje User , podemos agregar una restricción para garantizar que la marca de tiempo created_at esté en el pasado.
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 ];
} Para restricciones más avanzadas o personalizadas, protovalidate permite expresiones CEL que pueden incorporar información en todos los campos.
Expresiones a nivel de campo: podemos exigir que price de un producto, enviado como una cadena, incluya un símbolo de moneda como "$" o "£". Queremos asegurarnos de que el precio sea positivo y el símbolo de la moneda sea válido.
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"
}];
} Expresiones a nivel de mensaje: para un mensaje Transaction , podemos usar una expresión CEL a nivel de mensaje para garantizar que la delivery_date sea siempre posterior a la 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"
};
} Producir un mensaje de error en la expresión: Podemos producir mensajes de error personalizados directamente en las expresiones CEL. En este ejemplo, si la age es menor de 18 años, la expresión CEL se evaluará como la cadena del mensaje de error.
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': ''"
}];
} Consulte examples para ver ejemplos tanto de restricciones estándar como de restricciones CEL personalizadas.
Una vez que los mensajes estén anotados con restricciones, use una de las bibliotecas de idiomas admitidas para validar; no es necesaria ninguna generación de código adicional.
protovalidate proporciona un marco sólido para validar mensajes de Protobuf al imponer restricciones estándar y personalizadas en varios tipos de datos y ofrecer información de error detallada cuando ocurren violaciones de validación. Para obtener una descripción detallada de todos sus componentes, las restricciones admitidas y cómo utilizarlas de forma eficaz, consulte nuestra documentación completa. Los componentes clave incluyen:
Restricciones estándar : protovalidate admite una amplia gama de restricciones estándar para todos los tipos de campos, así como funciones especiales para los tipos conocidos de Protobuf. Puede aplicar estas restricciones a sus mensajes de Protobuf para asegurarse de que cumplan ciertas condiciones comunes.
Restricciones personalizadas : con el lenguaje de expresión común (CEL) de Google, protovalidate le permite crear restricciones personalizadas y complejas para manejar escenarios de validación únicos que no están cubiertos por las restricciones estándar tanto a nivel de campo como de mensaje.
Manejo de errores : cuando se produce una infracción, protovalidate proporciona información detallada sobre el error para ayudarle a identificar rápidamente el origen y solucionar un problema.
protovalidate es el sucesor espiritual de protoc-gen-validate , y ofrece la misma funcionalidad presente en el complemento original, sin la necesidad de generar código personalizado, y la nueva capacidad de describir restricciones complejas en CEL.
Las restricciones de protovalidate emulan muy de cerca las de protoc-gen-validate para garantizar una transición fácil para los desarrolladores. Para migrar de protoc-gen-validate a protovalidate , utilice la herramienta de migración proporcionada para actualizar incrementalmente sus archivos .proto .
Ofrecido bajo la licencia Apache 2.
