protovalidate
é uma série de bibliotecas projetadas para validar mensagens Protobuf em tempo de execução com base em regras de validação definidas pelo usuário. Desenvolvido pela Common Expression Language (CEL) do Google, ele fornece uma base flexível e eficiente para definir e avaliar regras de validação personalizadas. O objetivo principal do protovalidate
é ajudar os desenvolvedores a garantir a consistência e integridade dos dados em toda a rede sem a necessidade de código gerado.
Observação
protovalidate
é o sucessor espiritual de protoc-gen-validate. Não requer nenhuma geração de código e oferece suporte a restrições personalizadas.
Recomendamos que projetos novos e existentes façam a transição para o uso de protovalidate
em vez de protoc-gen-validate
.
Leia nossa postagem no blog se quiser saber mais sobre as limitações do protoc-gen-validate
e como projetamos protovalidate
para ser melhor.
Este repositório é o núcleo do projeto protovalidate
. Ele contém:
protovalidate
de forma eficazprotoc-gen-validate
.proto
usando protovalidate
protovalidate
Implementações de tempo de execução do protovalidate
podem ser encontradas em seus próprios repositórios:
protovalidate-go
(versão beta)protovalidate-cc
(versão beta)protovalidate-java
(versão beta)protovalidate-python
(versão beta)protovalidate-ts
(em breve)Interessado em adicionar suporte para outro idioma? Confira nossas Diretrizes de Contribuição.
Para definir restrições em suas mensagens Protobuf, importe buf/validate/validate.proto
para seus arquivos .proto
:
syntax = "proto3" ;
package my.package ;
import "buf/validate/validate.proto" ;
buf
Adicione uma dependência de buf.build/bufbuild/protovalidate
ao buf.yaml
do seu módulo:
version : v1
#
deps :
- buf.build/bufbuild/protovalidate
#
Depois de modificar seu buf.yaml
, não se esqueça de executar buf mod update
para garantir que suas dependências estejam atualizadas.
protoc
Adicione um caminho de importação (flag -I
) apontando para o conteúdo do diretório proto/protovalidate
para sua invocação de protoc
:
protoc
-I ./vendor/protovalidate/proto/protovalidate
#
As restrições de validação podem ser impostas usando o pacote buf.validate
Protobuf. As regras são especificadas diretamente nos arquivos .proto
.
Vamos considerar alguns exemplos:
Validação de campo escalar: para uma mensagem básica User
, podemos impor restrições como um comprimento mínimo para o nome do usuário.
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 ];
}
Validação do campo do mapa: Para uma mensagem Product
com um mapa de quantidades de itens, podemos garantir que todas as quantidades são 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 ];
}
Validação de tipo bem conhecido (WKT): para a mensagem User
, podemos adicionar uma restrição para garantir que o carimbo de data/hora created_at
esteja no passado.
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 restrições mais avançadas ou personalizadas, protovalidate
permite expressões CEL que podem incorporar informações entre campos.
Expressões em nível de campo: podemos impor que o price
de um produto, enviado como uma string, inclua um símbolo de moeda como "$" ou "£". Queremos garantir que o preço seja positivo e que o símbolo da moeda seja 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"
}];
}
Expressões em nível de mensagem: para uma mensagem Transaction
, podemos usar uma expressão CEL em nível de mensagem para garantir que delivery_date
seja sempre posterior a 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"
};
}
Produzindo uma mensagem de erro na expressão: Podemos produzir mensagens de erro customizadas diretamente nas expressões CEL. Neste exemplo, se a age
for inferior a 18 anos, a expressão CEL será avaliada como a sequência da mensagem de erro.
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': ''"
}];
}
Confira examples
de restrições padrão e restrições CEL personalizadas.
Depois que as mensagens forem anotadas com restrições, use uma das bibliotecas de idiomas suportadas para validar; nenhuma geração de código adicional é necessária.
protovalidate
fornece uma estrutura robusta para validar mensagens Protobuf, aplicando restrições padrão e personalizadas em vários tipos de dados e oferecendo informações detalhadas sobre erros quando ocorrem violações de validação. Para uma visão geral detalhada de todos os seus componentes, as restrições suportadas e como usá-los de forma eficaz, consulte nossa documentação abrangente. Os principais componentes incluem:
Restrições padrão : protovalidate
suporta uma ampla gama de restrições padrão para todos os tipos de campo, bem como funcionalidades especiais para os tipos bem conhecidos do Protobuf. Você pode aplicar essas restrições às suas mensagens Protobuf para garantir que atendam a certas condições comuns.
Restrições personalizadas : com a Common Expression Language (CEL) do Google, protovalidate
permite criar restrições personalizadas e complexas para lidar com cenários de validação exclusivos que não são cobertos pelas restrições padrão no nível do campo e da mensagem.
Tratamento de erros : quando ocorre uma violação, protovalidate
fornece informações detalhadas sobre o erro para ajudá-lo a identificar rapidamente a origem e corrigir um problema.
protovalidate
é o sucessor espiritual do protoc-gen-validate
, oferecendo todas as mesmas funcionalidades presentes no plugin original, sem a necessidade de geração de código customizado, e a nova capacidade de descrever restrições complexas no CEL.
As restrições de protovalidate
emulam muito de perto aquelas em protoc-gen-validate
para garantir uma transição fácil para os desenvolvedores. Para migrar de protoc-gen-validate
para protovalidate
, use a ferramenta de migração fornecida para atualizar incrementalmente seus arquivos .proto
.
Oferecido sob a licença Apache 2.