ดาวน์โหลด protovalidate - ดาวน์โหลด protovalidate ซอร์สโค้ด

protovalidate

ซี/ซี++

v0.9.0

ดาวน์โหลด

ตรวจสอบความถูกต้อง

ซีไอ

protovalidate เป็นชุดของไลบรารีที่ออกแบบมาเพื่อตรวจสอบข้อความ Protobuf ณ รันไทม์ตามกฎการตรวจสอบที่ผู้ใช้กำหนด ขับเคลื่อนโดย Common Expression Language (CEL) ของ Google โดยเป็นรากฐานที่ยืดหยุ่นและมีประสิทธิภาพสำหรับการกำหนดและประเมินกฎการตรวจสอบที่กำหนดเอง เป้าหมายหลักของ protovalidate คือการช่วยให้นักพัฒนามั่นใจในความสอดคล้องและความสมบูรณ์ของข้อมูลทั่วทั้งเครือข่ายโดยไม่ต้องใช้โค้ดที่สร้างขึ้น

บันทึก

protovalidate เป็นผู้สืบทอดทางจิตวิญญาณใน protoc-gen-validate ไม่ต้องการการสร้างโค้ดใดๆ และรองรับข้อจำกัดแบบกำหนดเอง

เราขอแนะนำให้โปรเจ็กต์ใหม่และโปรเจ็กต์ที่มีอยู่เปลี่ยนไปใช้ protovalidate แทน protoc-gen-validate

อ่านโพสต์บนบล็อกของเรา หากคุณต้องการเรียนรู้เพิ่มเติมเกี่ยวกับข้อจำกัดของ protoc-gen-validate และวิธีที่เราออกแบบ protovalidate ให้ดียิ่งขึ้น

พื้นที่เก็บข้อมูลนี้คืออะไร?

พื้นที่เก็บข้อมูลนี้เป็นแกนหลักของโครงการ protovalidate ประกอบด้วย:

คำจำกัดความของ API: ใช้เพื่ออธิบายข้อจำกัดในการตรวจสอบ
เอกสารประกอบ: วิธีใช้ protovalidate อย่างมีประสิทธิภาพ
เครื่องมือการโยกย้าย: โยกย้ายแบบค่อยเป็นค่อยไปจาก protoc-gen-validate
ตัวอย่าง: ตัวอย่างไฟล์ .proto ที่ใช้ protovalidate
ยูทิลิตี้การทดสอบความสอดคล้อง: สำหรับการทดสอบการยอมรับการใช้งาน protovalidate

การดำเนินการ

การใช้งานรันไทม์ของ protovalidate สามารถพบได้ในที่เก็บของตัวเอง:

ไป: protovalidate-go (รุ่นเบต้า)
C++: protovalidate-cc (รุ่นเบต้า)
Java: protovalidate-java (รุ่นเบต้า)
Python: protovalidate-python (รุ่นเบต้า)
TypeScript: 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`

เพิ่มเส้นทางการนำเข้า ( -I flag) ที่ชี้ไปยังเนื้อหาของไดเร็กทอรี proto/protovalidate ไปยังการเรียกใช้ 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 ];
}
```
การตรวจสอบประเภทที่รู้จักกันดี (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': ''"
  }];
}
```

ดู examples เกี่ยวกับข้อจำกัดมาตรฐานและข้อจำกัด CEL แบบกำหนดเอง

ตรวจสอบข้อความ

เมื่อข้อความถูกใส่คำอธิบายประกอบด้วยข้อจำกัดแล้ว ให้ใช้ไลบรารีภาษาที่รองรับเพื่อตรวจสอบความถูกต้อง ไม่จำเป็นต้องสร้างโค้ดเพิ่มเติม

เอกสารประกอบ

protovalidate จัดเตรียมเฟรมเวิร์กที่แข็งแกร่งสำหรับการตรวจสอบข้อความ Protobuf โดยการบังคับใช้ข้อจำกัดมาตรฐานและแบบกำหนดเองกับข้อมูลประเภทต่างๆ และเสนอข้อมูลข้อผิดพลาดโดยละเอียดเมื่อมีการละเมิดการตรวจสอบเกิดขึ้น สำหรับภาพรวมโดยละเอียดของส่วนประกอบทั้งหมด ข้อจำกัดที่รองรับ และวิธีการใช้งานอย่างมีประสิทธิภาพ โปรดดูเอกสารประกอบที่ครอบคลุมของเรา ส่วนประกอบที่สำคัญได้แก่:

ข้อจำกัดมาตรฐาน : protovalidate รองรับข้อจำกัดมาตรฐานที่หลากหลายสำหรับฟิลด์ทุกประเภท เช่นเดียวกับฟังก์ชันพิเศษสำหรับ Protobuf Well-Known-Types คุณสามารถใช้ข้อจำกัดเหล่านี้กับข้อความ Protobuf ของคุณเพื่อให้แน่ใจว่าตรงตามเงื่อนไขทั่วไปบางประการ
ข้อจำกัดที่กำหนดเอง : ด้วย Common Expression Language (CEL) ของ Google protovalidate ช่วยให้คุณสร้างข้อจำกัดที่กำหนดเองที่ซับซ้อนเพื่อจัดการกับสถานการณ์การตรวจสอบที่ไม่ซ้ำกันที่ไม่ครอบคลุมโดยข้อจำกัดมาตรฐานทั้งในระดับฟิลด์และข้อความ
การจัดการข้อผิดพลาด : เมื่อมีการละเมิดเกิดขึ้น protovalidate จะให้ข้อมูลข้อผิดพลาดโดยละเอียดเพื่อช่วยให้คุณระบุแหล่งที่มาและแก้ไขปัญหาได้อย่างรวดเร็ว

protoc-gen-ตรวจสอบ

protovalidate เป็นผู้สืบทอดทางจิตวิญญาณของ protoc-gen-validate โดยนำเสนอฟังก์ชันการทำงานเดียวกันทั้งหมดที่มีอยู่ในปลั๊กอินดั้งเดิม โดยไม่จำเป็นต้องสร้างโค้ดแบบกำหนดเอง และความสามารถใหม่ในการอธิบายข้อจำกัดที่ซับซ้อนใน CEL

ข้อจำกัดของ protovalidate จะเลียนแบบข้อจำกัดใน protoc-gen-validate อย่างใกล้ชิดเพื่อให้แน่ใจว่านักพัฒนาจะมีการเปลี่ยนแปลงได้ง่าย หากต้องการย้ายจาก protoc-gen-validate ไปเป็น protovalidate ให้ใช้เครื่องมือการย้ายข้อมูลที่มีให้เพื่ออัปเกรดไฟล์ .proto ของคุณแบบส่วนเพิ่ม