در gRPC، تعریف پیام‌ها (messages) و سرویس‌ها (services) بخش مرکزی فایل‌های .proto را تشکیل می‌دهد. این تعاریف ساختار ارتباط بین کلاینت و سرور را مشخص می‌کنند. پیام‌ها مشخص می‌کنند که چه داده‌هایی باید رد و بدل شوند و سرویس‌ها مشخص می‌کنند که چه عملیات‌هایی در دسترس هستند.
تعریف پیام‌ها (Messages)
پیام‌ها نوعی ساختار داده هستند که به صورت strongly typed تعریف می‌شوند و شامل مجموعه‌ای از فیلدهای عدددار هستند. هر فیلد دارای یک نوع داده، یک نام و یک شماره یکتا است. این شماره برای ترتیب سریال‌سازی استفاده می‌شود و هرگز نباید پس از انتشار تغییر کند.
مثال:
message Book {
int32 id = 1;
string title = 2;
string author = 3;
repeated string tags = 4;
}
در این پیام:
-
id,title,authorفیلدهای ساده هستند. -
tagsفیلدی از نوعrepeatedاست، که به معنای یک لیست از رشته‌ها است.
پیام‌ها می‌توانند پیام‌های دیگر را به‌عنوان فیلد درون خود جای دهند:
message Library {
repeated Book books = 1;
}
استفاده از enum در پیام‌ها
enum BookStatus {
AVAILABLE = 0;
CHECKED_OUT = 1;
}
message Book {
int32 id = 1;
string title = 2;
BookStatus status = 3;
}
استفاده از oneof برای حالت‌های مختلف
message Contact {
oneof method {
string email = 1;
string phone = 2;
}
}
در این ساختار فقط یکی از email یا phone می‌تواند مقدار داشته باشد.
تعریف سرویس‌ها (Services)
سرویس‌ها شامل مجموعه‌ای از توابع (RPCs) هستند که کلاینت می‌تواند آن‌ها را فراخوانی کند. هر RPC دارای یک پیام ورودی و یک پیام خروجی است.
مثال پایه:
service BookService {
rpc GetBook (BookRequest) returns (Book);
rpc ListBooks (Empty) returns (Library);
}
تعریف پیام‌ها:
message BookRequest {
int32 id = 1;
}
message Empty {}
در این مثال:
-
GetBookکتابی را با شناسه مشخص دریافت می‌کند. -
ListBooksتمام کتاب‌ها را بازمی‌گرداند و نیازی به پارامتر ورودی ندارد.
چهار نوع RPC در gRPC
| نوع ارتباط | توضیح |
|---|---|
| unary RPC | کلاینت یک پیام می‌فرستد و یک پاسخ می‌گیرد. |
| server streaming RPC | کلاینت یک پیام می‌فرستد، ولی سرور چندین پیام در پاسخ ارسال می‌کند. |
| client streaming RPC | کلاینت چند پیام می‌فرستد و یک پاسخ دریافت می‌کند. |
| bidirectional streaming RPC | هر دو طرف به صورت همزمان پیام ارسال و دریافت می‌کنند. |
مثال از هر نوع:
service StreamService {
rpc Upload(stream FileChunk) returns (UploadStatus); // client streaming
rpc Download(FileRequest) returns (stream FileChunk); // server streaming
rpc Chat(stream ChatMessage) returns (stream ChatMessage); // bidirectional
}
در اینجا:
-
کلمه
streamنشان‌دهنده انتقال چندبخشی اطلاعات است. -
در
Chatارتباط دوطرفه و همزمان برقرار است.
خلاصه ساختار پیشنهادی فایل .proto
syntax = "proto3";
package books;
message Book { ... }
message BookRequest { ... }
message Empty {}
service BookService {
rpc GetBook (BookRequest) returns (Book);
rpc ListBooks (Empty) returns (Library);
}
جدول اجزای کلیدی پیام‌ها و سرویس‌ها
| مؤلفه | تعریف و کاربرد |
|---|---|
message |
ساختار داده برای انتقال اطلاعات |
enum |
مقدارهای ثابت و محدود برای پیام‌ها |
repeated |
لیست از یک نوع فیلد |
oneof |
فیلدهای شرطی که فقط یکی فعال است |
rpc |
عملیات قابل فراخوانی از سمت کلاینت |
stream |
برای ارسال یا دریافت چند پیام به صورت متوالی |
تعریف دقیق و تمیز پیام‌ها و سرویس‌ها در فایل .proto نقش کلیدی در موفقیت توسعه مبتنی بر gRPC دارد. این تعاریف باید ساده، مستند و پایدار باشند تا امکان توسعه بلندمدت و تعامل با سرویس‌های مختلف فراهم گردد.