Learn Rust Coding · درس

تعريفات Protobuf والخدمات

صِف API الخاصة بك باستخدام proto

تعريفات Protobuf والخدمات درس مجاني في Learn Rust Coding على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Learn Rust Coding، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Learn Rust Coding 4 دروس في المجموع.

لماذا gRPC وProtobuf

إن gRPC إطار عمل عالي الأداء لاستدعاء الإجراءات عن بُعد، مبني على HTTP/2 وProtocol Buffers. وفي Rust، تنفّذ حزمة tonic gRPC من البداية إلى النهاية.

أما Protobuf فهي لغة تعريف الواجهات (IDL). تصفون الرسائل والخدمات مرة واحدة في ملف .proto، ثم تنشئ مولدات الشيفرة هياكل عميلة وخادمة ذات أنواع محددة بقوة.

بنية ملف .proto

يعلن كل ملف proto عن إصدار بناء الجملة وحزمة. وتُستخدم الحزمة لتحديد نطاق الأنواع المولَّدة وتجنب التعارضات.

استخدموا proto3 مع tonic. ويُحوَّل اسم الحزمة إلى مسار وحدة Rust بعد التوليد.

syntax = "proto3";

package greeter.v1;

تعريف الرسائل

الرسالة سجلّ ذو أنواع محددة. لكل حقل نوع واسم ورقم حقل فريد يُستخدم لترميز البيانات على السلك.

يجب أن تظل أرقام الحقول ثابتة: لا تعيدوا استخدام حقل أو تعيدوا ترقيمه بعد وجود بيانات، وإلا أخللتم بالتوافق.

message HelloRequest {
  string name = 1;
  int32 age = 2;
}

الأنواع العددية ومطابقتها في Rust

تُطابق الأنواع العددية في Protobuf أنواع Rust عبر prost. يتحول string إلى String، وint32 إلى i32، وbool إلى bool، وbytes إلى Vec<u8>.

في proto3 لكل نوع عددي قيمة افتراضية (سلسلة فارغة، و0، وfalse)؛ ولا تكون هذه الأنواع اختيارية إلا إذا وُسِمت بذلك.

message Metric {
  string label = 1;
  double value = 2;
  bool active = 3;
}

تعريف خدمة

تجمع service طرق RPC. ويعلن كل rpc عن اسم طريقة ورسالة طلب ورسالة استجابة.

يولّد tonic سمة للخادم وبنية للعميل من هذه الكتلة. وتطبيق السمة هو الطريقة التي توفّرون بها السلوك.

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply);
}

message HelloReply {
  string message = 1;
}

أنواع طرق RPC الأربعة

يدعم gRPC أربعة أشكال من البث: أحادي الطلب، وبث من الخادم، وبث من العميل، وبث ثنائي الاتجاه.

تشيرون إلى البث باستخدام الكلمة المفتاحية stream في جانب الطلب أو الاستجابة أو كليهما.

service Chat {
  rpc Unary (Msg) returns (Msg);
  rpc ServerStream (Msg) returns (stream Msg);
  rpc ClientStream (stream Msg) returns (Msg);
  rpc BiDi (stream Msg) returns (stream Msg);
}

التعدادات في Protobuf

التعدادات مدعومة بأعداد صحيحة. في proto3 يجب ترقيم القيمة الأولى بالرقم 0، وتعمل بوصفها القيمة الافتراضية.

ينشئ prost تعداد Rust بالإضافة إلى أدوات مساعدة للتحويل من i32 الأساسي، لأن القيم غير المعروفة قد تصل عبر السلك.

enum Status {
  STATUS_UNKNOWN = 0;
  STATUS_ACTIVE = 1;
  STATUS_BANNED = 2;
}

الحقول المتداخلة والمتكررة

حقل repeated هو قائمة، ويُطابق Vec<T> في Rust. ويمكن تداخل الرسائل أو الإشارة إليها بالاسم.

يتيح لكم ذلك نمذجة المجموعات والبيانات المركبة دون إجراءات إضافية.

message Order {
  string id = 1;
  repeated Item items = 2;
}

message Item {
  string sku = 1;
  int32 qty = 2;
}

النوعان Empty والأنواع المعروفة

بالنسبة إلى الطرق التي لا تتلقى شيئًا أو تعيده، استوردوا google/protobuf/empty.proto واستخدموا Empty.

تشمل الأنواع الأخرى المعروفة Timestamp وDuration. وتوفّر tonic هذه التعريفات، لذا يمكنكم استيرادها في عملية البناء.

import "google/protobuf/empty.proto";

service Health {
  rpc Ping (google.protobuf.Empty) returns (google.protobuf.Empty);
}

إدارة الإصدارات باستخدام الحزم

يتيح وضع إصدار في الحزمة، مثل greeter.v1، تطوير واجهة API بأمان. ويوضع التغيير غير المتوافق في greeter.v2 بينما يواصل الإصدار v1 تقديم الخدمة.

تحافظ هذه الاتفاقية على نظافة وحدات Rust المولَّدة: يمكن أن تتعايش greeter::v1 وgreeter::v2.

package greeter.v1;
// later, a parallel file:
// package greeter.v2;

قواعد توافق الحقول

إضافة حقل جديد برقم جديد متوافقة مع الإصدارات السابقة؛ إذ يتجاهله العملاء القدامى. أما إزالة حقل فتنطوي على مخاطر، ما لم تحجزوا رقمه واسمه باستخدام reserve.

يمنع الحجز أي شخص من إعادة استخدام رقم حقل متقاعد وإفساد فك الترميز.

message User {
  reserved 3, 5;
  reserved "legacy_token";
  string id = 1;
  string email = 2;
}

تحقق سريع

اختبروا مدى فهمكم لتعريفات الخدمات في proto3.

مراجعة

عرّفتم الخدمات والرسائل في proto3: أرقام الحقول الثابتة، ومطابقة الأنواع العددية بأنواع Rust، والتعدادات، والحقول المتكررة والمتداخلة، وأشكال RPC الأربعة، والأنواع المعروفة، وإدارة الإصدارات عبر الحزم.

ستحوّلون هذه التعريفات بعد ذلك إلى شيفرة Rust باستخدام tonic-build.

الأسئلة الشائعة

هل درس «تعريفات Protobuf والخدمات» مجاني؟

نعم — نص درس «تعريفات Protobuf والخدمات» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Learn Rust Coding، انتقل إلى CoddyKit PRO. تتضمن دورة Learn Rust Coding 4 دروس في المجموع.

ماذا ستتعلم في «تعريفات Protobuf والخدمات»؟

صِف API الخاصة بك باستخدام proto تتمرن على Learn Rust Coding مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Learn Rust Coding؟

لا تُشترط خبرة سابقة. Learn Rust Coding على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «تعريفات Protobuf والخدمات»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Learn Rust Coding هذا؟

نعم. كل درس في Learn Rust Coding يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Learn Rust Coding