protovalidate

التحقق من صحة

protovalidate عبارة عن سلسلة من المكتبات المصممة للتحقق من صحة رسائل Protobuf في وقت التشغيل بناءً على قواعد التحقق المحددة من قبل المستخدم. مدعومًا بلغة التعبير الشائعة (CEL) من Google، فهو يوفر أساسًا مرنًا وفعالاً لتحديد وتقييم قواعد التحقق المخصصة. الهدف الأساسي من protovalidate هو مساعدة المطورين على ضمان اتساق البيانات وسلامتها عبر الشبكة دون الحاجة إلى تعليمات برمجية تم إنشاؤها.

ملحوظة

protovalidate هو الوريث الروحي لـ protoc-gen-validate. لا يتطلب أي إنشاء تعليمات برمجية ويدعم القيود المخصصة.

نوصي بأن تنتقل المشاريع الجديدة والحالية إلى استخدام protovalidate بدلاً من protoc-gen-validate .

اقرأ منشور مدونتنا إذا كنت تريد معرفة المزيد حول القيود protoc-gen-validate وكيف قمنا بتصميم protovalidate -gen ليكون أفضل.

ما هو هذا المستودع؟

هذا المستودع هو جوهر مشروع protovalidate . أنه يحتوي على:

• تعريف API: يستخدم لوصف قيود التحقق من الصحة
• التوثيق: كيفية تطبيق protovalidate بشكل فعال
• أدوات الترحيل: الترحيل التدريجي من protoc-gen-validate
• أمثلة: مثال على ملفات .proto باستخدام protovalidate
• أدوات اختبار المطابقة: لاختبار قبول تطبيقات protovalidate

التنفيذ

يمكن العثور على تطبيقات وقت التشغيل لـ protovalidate في المستودعات الخاصة بها:

• Go: protovalidate-go (إصدار تجريبي)
• C++: protovalidate-cc (إصدار تجريبي)
• جافا: protovalidate-java (إصدار تجريبي)
• بايثون: 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
# 
deps :
  - buf.build/bufbuild/protovalidate
# 

بعد تعديل buf.yaml ، لا تنس تشغيل buf mod update للتأكد من أن تبعياتك محدثة.

بناء مع protoc

أضف مسار استيراد (علامة -I ) يشير إلى محتويات دليل proto/protovalidate لاستدعاء protoc :

protoc 
  -I ./vendor/protovalidate/proto/protovalidate 
  # 

تنفيذ قيود التحقق من الصحة

يمكن فرض قيود التحقق باستخدام حزمة buf.validate Protobuf. يتم تحديد القواعد مباشرة في ملفات .proto .

دعونا نفكر في بعض الأمثلة:

1. التحقق من صحة الحقل العددي: بالنسبة لرسالة 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 ];
   }

2. التحقق من صحة حقل الخريطة: بالنسبة لرسالة Product التي تحتوي على خريطة لكميات العناصر، يمكننا التأكد من أن جميع الكميات موجبة.

   item_quantities = 1 [(buf.validate.field).map.values.int32.gt = 0]; }" style=";text-align:right;direction:rtl">

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

3. التحقق من صحة النوع المعروف (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 التي يمكنها دمج المعلومات عبر الحقول.

1. التعبيرات على مستوى الحقل: يمكننا أن نفرض أن price المنتجات، الذي يتم إرساله كسلسلة، يتضمن رمز عملة مثل "$" أو " £". نريد التأكد من أن السعر إيجابي وأن رمز العملة صالح.

   0" }]; }" style=";text-align:right;direction:rtl">

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

2. التعبيرات على مستوى الرسالة: بالنسبة لرسالة Transaction ، يمكننا استخدام تعبير CEL على مستوى الرسالة للتأكد من أن delivery_date يقع دائمًا بعد purchase_date .

   this.purchase_date" }; }" style=";text-align:right;direction:rtl">

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

3. إنتاج رسالة خطأ في التعبير: يمكننا إنتاج رسائل خطأ مخصصة مباشرة في تعبيرات 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 المعروفة. يمكنك تطبيق هذه القيود على رسائل Protobuf الخاصة بك للتأكد من أنها تستوفي شروطًا مشتركة معينة.

• القيود المخصصة : باستخدام لغة التعبير الشائعة (CEL) من Google، يتيح لك protovalidate إنشاء قيود مخصصة ومعقدة للتعامل مع سيناريوهات التحقق الفريدة التي لا تغطيها القيود القياسية على مستوى الحقل والرسالة.

• معالجة الأخطاء : عند حدوث انتهاك، يوفر protovalidate معلومات تفصيلية عن الخطأ لمساعدتك في التعرف بسرعة على المصدر وإصلاح المشكلة.

التحقق من صحة protoc-gen

protovalidate هو الوريث الروحي لـ protoc-gen-validate ، حيث يقدم نفس الوظائف الموجودة في البرنامج الإضافي الأصلي، دون الحاجة إلى إنشاء تعليمات برمجية مخصصة، والقدرة الجديدة على وصف القيود المعقدة في CEL.

تحاكي قيود protovalidate بشكل وثيق تلك الموجودة في protoc-gen-validate لضمان انتقال سهل للمطورين. للترحيل من protoc-gen-validate إلى protovalidate ، استخدم أداة الترحيل المتوفرة لترقية ملفات .proto بشكل متزايد.

النظام البيئي

• بوف
• مواصفات سيل

قانوني

معروض بموجب ترخيص Apache 2.