Unduh protovalidate - protovalidate Unduhan kode sumber

protovalidate

C/C++

v0.9.0

Unduh

protovalidasi

protovalidate adalah serangkaian perpustakaan yang dirancang untuk memvalidasi pesan Protobuf saat runtime berdasarkan aturan validasi yang ditentukan pengguna. Didukung oleh Common Expression Language (CEL) Google, ini memberikan landasan yang fleksibel dan efisien untuk menentukan dan mengevaluasi aturan validasi khusus. Tujuan utama protovalidate adalah membantu pengembang memastikan konsistensi dan integritas data di seluruh jaringan tanpa memerlukan kode yang dihasilkan.

Catatan

protovalidate adalah penerus spiritual dari protoc-gen-validate. Itu tidak memerlukan pembuatan kode apa pun dan mendukung batasan khusus.

Kami merekomendasikan agar proyek baru dan yang sudah ada beralih menggunakan protovalidate bukan protoc-gen-validate .

Baca postingan blog kami jika Anda ingin mempelajari lebih lanjut tentang batasan protoc-gen-validate dan bagaimana kami merancang protovalidate menjadi lebih baik.

Apa repositori ini?

Repositori ini adalah inti dari proyek protovalidate . Ini berisi:

Definisi API: digunakan untuk menjelaskan batasan validasi
Dokumentasi: bagaimana menerapkan protovalidate secara efektif
Peralatan migrasi: bermigrasi secara bertahap dari protoc-gen-validate
Contoh: contoh file .proto menggunakan protovalidate
Utilitas pengujian kesesuaian: untuk pengujian penerimaan implementasi protovalidate

Implementasi

Implementasi runtime dari protovalidate dapat ditemukan di repositori mereka sendiri:

Buka: protovalidate-go (rilis beta)
C++: protovalidate-cc (rilis beta)
Java: protovalidate-java (rilis beta)
Python: protovalidate-python (rilis beta)
TypeScript: protovalidate-ts (segera hadir)

Tertarik untuk menambahkan dukungan untuk bahasa lain? Lihat Pedoman Berkontribusi kami.

Penggunaan

Impor protovalidasi

Untuk menentukan batasan dalam pesan Protobuf Anda, impor buf/validate/validate.proto ke dalam file .proto Anda:

 syntax = "proto3" ;

package my.package ;

import "buf/validate/validate.proto" ;

Bangun dengan `buf`

Tambahkan ketergantungan pada buf.build/bufbuild/protovalidate ke buf.yaml modul Anda:

 version : v1
# <snip>
deps :
  - buf.build/bufbuild/protovalidate
# <snip>

Setelah memodifikasi buf.yaml Anda, jangan lupa menjalankan buf mod update untuk memastikan dependensi Anda mutakhir.

Bangun dengan `protoc`

Tambahkan jalur impor ( -I flag) yang menunjuk ke konten direktori proto/protovalidate ke pemanggilan protoc Anda:

protoc 
  -I ./vendor/protovalidate/proto/protovalidate 
  # <snip>

Menerapkan batasan validasi

Batasan validasi dapat diterapkan menggunakan paket Protobuf buf.validate . Aturannya ditentukan langsung di file .proto .

Mari kita pertimbangkan beberapa contoh:

Validasi bidang skalar: Untuk pesan User dasar, kita dapat menerapkan batasan seperti panjang minimum nama pengguna.

 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 ];
}

Validasi bidang peta: Untuk pesan Product dengan peta jumlah item, kami dapat memastikan bahwa semua kuantitas positif.

 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 ];
}

Validasi tipe terkenal (WKT): Untuk pesan User , kita dapat menambahkan batasan untuk memastikan stempel waktu created_at sudah lewat.

 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 ];
}

Untuk batasan lebih lanjut atau batasan khusus, protovalidate memungkinkan ekspresi CEL yang dapat menggabungkan informasi lintas bidang.

Ekspresi tingkat bidang: Kita dapat menerapkan price produk, yang dikirim sebagai string, menyertakan simbol mata uang seperti "$" atau "£". Kami ingin memastikan bahwa harganya positif dan simbol mata uangnya valid.

 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"
  }];
}

Ekspresi tingkat pesan: Untuk pesan Transaction , kita dapat menggunakan ekspresi CEL tingkat pesan untuk memastikan bahwa delivery_date selalu setelah 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"
  };
}

Menghasilkan pesan kesalahan dalam ekspresi: Kita dapat menghasilkan pesan kesalahan khusus secara langsung dalam ekspresi CEL. Dalam contoh ini, jika age kurang dari 18 tahun, ekspresi CEL akan dievaluasi menjadi string pesan kesalahan.

 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': ''"
  }];
}

Lihat examples untuk contoh batasan standar dan batasan CEL khusus.

Validasi Pesan

Setelah pesan dianotasi dengan batasan, gunakan salah satu pustaka bahasa yang didukung untuk memvalidasi; tidak diperlukan pembuatan kode tambahan.

Dokumentasi

protovalidate menyediakan kerangka kerja yang kuat untuk memvalidasi pesan Protobuf dengan menerapkan batasan standar dan khusus pada berbagai tipe data, dan menawarkan informasi kesalahan terperinci ketika terjadi pelanggaran validasi. Untuk gambaran rinci tentang semua komponennya, batasan yang didukung, dan cara menggunakannya secara efektif, silakan merujuk ke dokumentasi komprehensif kami. Komponen utamanya meliputi:

Batasan Standar : protovalidate mendukung berbagai batasan standar untuk semua jenis bidang serta fungsi khusus untuk Tipe Terkenal Protobuf. Anda dapat menerapkan batasan ini pada pesan Protobuf Anda untuk memastikan pesan tersebut memenuhi ketentuan umum tertentu.
Batasan Khusus : Dengan Common Expression Language (CEL) Google, protovalidate memungkinkan Anda membuat batasan khusus yang kompleks untuk menangani skenario validasi unik yang tidak tercakup dalam batasan standar baik di tingkat bidang maupun pesan.
Penanganan Kesalahan : Ketika pelanggaran terjadi, protovalidate memberikan informasi kesalahan terperinci untuk membantu Anda mengidentifikasi sumber dengan cepat dan memperbaiki suatu masalah.

validasi protoc-gen

protovalidate adalah penerus spiritual dari protoc-gen-validate , menawarkan semua fungsi yang sama yang ada di plugin asli, tanpa memerlukan pembuatan kode khusus, dan kemampuan baru untuk menjelaskan batasan kompleks di CEL.

Kendala protovalidate sangat mirip dengan kendala di protoc-gen-validate untuk memastikan transisi yang mudah bagi pengembang. Untuk bermigrasi dari protoc-gen-validate ke protovalidate , gunakan alat migrasi yang disediakan untuk meningkatkan versi file .proto Anda secara bertahap.