gRPC & Protocol Buffers Vocabulary: 30 Терміни для розробників API
Визначення служби gRPC, буфери протоколів, типи потоків, перехоплювачі, терміни виконання і словник створення клієнтів.
Якщо ви працюєте з мікросервісами або розподіленими системами, ви майже напевно чули, як колеги згадують gRPC у переглядах коду, на зустрічах з архітекторами або в гілках Slack. gRPC — це високопродуктивний фреймворк віддаленого виклику процедур, розроблений Google, і використовує Protocol Buffers (часто називається « protobuf ») як типовий формат серіалізації. Разом вони забезпечують зв’язок між службами в компаніях, починаючи від стартапів на ранніх стадіях до великих інженерних організацій. Освоєння словника gRPC і protobuf допоможе вам впевнено брати участь у технічних обговореннях, писати більш чітку документацію і розуміти коментарі до запитів на звантаження без необхідності щоразу просити про пояснення.
Основні поняття: Визначення вашого API
** Файл прототипу ** — файл з простим текстом з суфіксом .proto, у якому описано форму ваших даних і операції, які виконує ваша служба. Все починається тут; протофайл є єдиним джерелом правди для вашого договору API.
“Протофайл вже зафіксований? Я хочу почати генерувати клієнтські заголовки.»
«Не змінюйте прото файл без запуску його через команду backend спочатку — будь-яке порушення вплине на три інші служби.»
** Визначення служби ** — блок у протофайлі, який оголошує, які віддалені методи буде показано сервером. Це gRPC еквівалент інтерфейсу або контролера в REST API.
«Опис послуги виглядає чистим, але у вас відсутній метод для масових оновлень»
«Ми погодилися, що визначення сервісу буде жити в спільному прототипі репо, щоб всі команди тягнули з одного місця»
** Повідомлення ** — структурований тип даних, визначений у протофайлі, схожий на клас або структуру. Повідомлення описують як запит, так і відповідь.
Ваше
CreateOrderRequestповідомлення не містить поляcurrency_code— додайте його до наступного випуску
«Ми повторно використовуємо те ж саме повідомлення
UserProfileчерез чотири різні виклики RPC, щоб зберегти все послідовним»
** Номер поля ** — унікальний цілий номер, який буде призначено для кожного поля у повідомленні. Буфери протоколів використовують номери полів — а не назви полів — для ідентифікації даних у дроті, саме тому їх ніколи не слід змінювати або повторно використовувати після того, як схема буде створено.
«Ви можете вільно перейменувати поле, але ніколи не присвоюйте його номер поля — це пошкодить існуючі серіалізовані дані»
«Ми закінчили однозначні номери полів, але це добре; просто зберігайте їх послідовно, і це не вплине на продуктивність»
Protoc compiler — інструмент командного рядка ( protoc ), який читає файли .proto і генерує код, специфічний для мови, наприклад, структури Go, класи Java або інтерфейси TypeScript. Додатки розширюють його для створення додаткових виводів, таких як заголовки gRPC або специфікації OpenAPI.
«Запустити protoc після кожної зміни схеми — сформовані файли повинні завжди бути зафіксовані разом з прото файлом»
«Наш CI конвеєр запускає protoc автоматично, тому ніхто не випадково не відправляє застарілий генерований код.»
РНК-полімерази та їхні ланцюги зв’язку
gRPC підтримує чотири окремі шаблони зв’язку. Знання різниці між ними допоможе вам обрати правильний варіант під час обговорення проекту.
** Одноразовий RPC ** — найпростіший шаблон: клієнт надсилає один запит і очікує на одну відповідь. Цей запит поводиться так само, як і традиційний запит HTTP.
Для кінцевої точки входу, унарний RPC в порядку — немає причини для потоку однієї токена назад
** Server- streaming RPC ** — клієнт надсилає один запит, а сервер відповідає потоком повідомлень. Корисно для таких речей, як подачі даних у реальному часі або великі набори результатів.
«Ми змінили кінцеву точку пошуку на сервер-стримінг, тому результати з’являються поступово, а не всі за раз.»
«Стримінг сервера зробив панель управління набагато швидшою — користувачі відразу бачать перші рядки»
** RPC з потоком клієнтів ** — клієнт надсилає потік повідомлень, а сервер відповідає однією відповіддю після завершення потоку. Зазвичай використовується для вивантаження файлів або пакетного вживання.
«Кінечна точка телеметриї використовує клієнт-стрімінг — пристрої відсилають сотні показань і отримують одне підтвердження назад»
** Двосторонній поток RPC ** — клієнт і сервер одночасно надсилають незалежні потоки повідомлень. Цей шаблон підходить для інструментів співпраці в реальному часі, систем чату і синхронізації стану гри.
«Мультиплеєрний режим потребує двостороннього потокового передачі; все інше вводить занадто багато затримки»
«Bidi streaming є потужним, але важче обґрунтувати — переконайтеся, що ви правильно обробляєте half-close»
** Stub ** — автоматично створений код з боку клієнта, який надає вам змогу викликати віддалені методи так, ніби вони є локальними функціями. Заголовок обробляє серіалізацію, мережевий транспорт і десеріалізацію прозорими способами.
«Якщо protoc генерує stub, виклик віддаленого методу не відрізняється від виклику локальної функції.»
«Заглушка для платіжної служби знаходиться в папці
/generated— імпортуйте її і ви готові до роботи»
** Канал ** — постійне з’ єднання між клієнтом gRPC і сервером, що керує основним з’ єднанням HTTP/ 2, балансуванням навантаження і логікою перез’ єднання.
Не створюйте новий канал за запитом — створюйте один при запуску і використовуйте його протягом усього життя програми
«Канал підтримує балансування навантаження на основі імені, тому ви можете вказувати на запис DNS і дозволити йому розподіляти трафік»
Надійність, спостережливість і безпека
** Перехоплювач ** — середнє програмне забезпечення, яке виконується перед або після виклику gRPC на стороні клієнта або сервера. Перехоплювачі є стандартним місцем для додавання таких перетинаючихся питань, як ведення журналу, автентифікація, збір метрик і відстеження запитів.
«Додати перехоплювач для розподіленого відстеження, щоб кожен виклик автоматично поширював ідентифікатор відстеження»
«Auth перехоплювач перевіряє JWTs на кожному вхідному запиті — вам не потрібно перевіряти токен вручну в кожному обробнику.»
** Термін / Тайм- аут ** — момент часу (термін) або тривалість (тайм- аут), після закінчення якого виклик gRPC буде автоматично скасовано. Встановлення строків закінчення запобігає поширенню повільних служб на всю систему.
Завжди встановлюйте термін для вихідних викликів — без нього, залежність буде блокувати ваш горутин назавжди
«Крайній термін поширюється через контекст, тому дочірні виклики автоматично скасуються, коли батьківський тайм-аут»
** Код стану ** — стандартизований код, який gRPC повертає разом з кожною відповіддю, що вказує на успішність виклику або описує тип невдачі. Приклади включають OK, NOT_FOUND, UNAVAILABLE, і DEADLINE_EXCEEDED.
Поверніть
INVALID_ARGUMENT, коли клієнт посилає погані дані — не використовуйтеINTERNAL, просто тому що це зручно
«Логіка повторних спроб ключується на
UNAVAILABLEіDEADLINE_EXCEEDEDкоди стану тільки.»
** Метадані ** — пари ключ- значення, які додаються до виклику gRPC, подібно до заголовків HTTP. Метадані використовуються для перенесення токенів розпізнавання, ідентифікаторів запитів, інформації щодо локалі та інших контекстних даних, які не є частиною корисного вмісту повідомлення.
Передавати ідентифікатор кореляції у вихідних метаданих, щоб кожна служба нижнього рівня записувала його для відстеження
«Ми додаємо локаль користувача до метаданих запитів замість того, щоб вставляти їх в кожен тип повідомлення»
** Формат дротів ** — двійкове кодування, яке використовується протокольними буферами для послідовного перетворення повідомлень перед надсиланням їх по мережі. Цей протокол компактний і швидкий, але не зрозумілий для людини — використовуйте protoc --decode або інструмент на зразок grpcurl, коли вам потрібно перевірити трафік під час зневадження.
«Формат дротів значно менший, ніж JSON, що має значення, коли ви надсилаєте мільйони повідомлень за секунду»
Якщо вам потрібно перевірити формат дротів в стаджі, використовуйте grpcurl — він декодиратиме вантажі protobuf в читабельний текст
** Зворотна сумісність ** — здатність новітньої версії прото- схеми правильно читати повідомлення, що були серіалізовані за допомогою старішої версії, і навпаки. Підтримка зворотної сумісності означає: ніколи не вилучайте або не змінюйте нумерацію існуючих полів; використовуйте ключове слово reserved для вилучених полів; і додавайте нові поля з новими номерами полів.
«Позначте застаріле поле як зарезервоване, а не вилучайте його — це зберігає зворотну сумісність зі старими клієнтами»
«Ми маємо перевірку сумісності схеми в CI, яка зазнає невдачі, якщо хтось вилучає номер поля з живого прото.»
** grpc- gateway ** — додаток protoc, який генерує зворотний проксі, перекладаючи RESTful HTTP/ JSON запити на виклики gRPC. За його допомогою ви можете відкрити службу gRPC для клієнтів, які не можуть розмовляти HTTP/ 2 або protobuf, наприклад, для переглядачів або інтеграцій сторонніх розробників.
«Ми використовуємо grpc-gateway, щоб зовнішні партнери могли викликати наші gRPC-сервіси через простий REST без будь-яких додаткових зусиль»
«Анотації шлюзу живуть в прото файлі поряд з визначенням сервісу — немає окремої специфікації OpenAPI для підтримки»
Як використовувати їх у розмові
** Сценарій 1 — Перегляд коду нової служби **
“Прото файл виглядає твердим, але в повідомленні
SearchResponseвідсутні поля сторінкування. Також, я б перевернув кінцеву точку переліку з унарного на сервер-стримінг, щоб клієнт міг відображати результати поступово»
** Сценарій 2 — Зневадження відключення**
“Всі помилки
DEADLINE_EXCEEDED— термін виконання виклику інвентарного сервісу встановлено на 500 мс, що занадто жорстко. Збільшити його до 2 с і додати перехоплювач для запису повільних викликів, щоб ми могли побачити цей шаблон раніше. ”
** Сценарій 3 — Введення нового члена команди **
“Почніть з читання файлу прото в репозиторії shared-protos — він розповість вам все, що може зробити служба. Запустіть протокол protoc, щоб відновити локальні замітки, а потім імпортуйте канал з пакунка конфігурації. Перехоплювач аутентифікації вже підключений, тому вам потрібно тільки зосередитися на вашій бізнес-логіці»
** Сценарій 4 — Обговорення архітектури **
“Для живого потоку даних нам потрібно серверне потокове відтворення, а не опитування. Ми будемо анонсувати метод в прото файлі і додати кінцеву точку grpc-gateway, щоб команда фронтенду могла споживати його через SSE, поки вони не мігрують до клієнта gRPC-Web. “
Краткий справочник
| Term | What it means in plain English |
|---|---|
| Proto file | Schema file describing messages and services |
| Service definition | Declares which remote methods the server exposes |
| Message | Structured data type used for requests and responses |
| Field number | Unique integer identifying a field on the wire — never change it |
| Stub | Auto-generated client code for calling remote methods |
| Channel | Persistent connection between client and server |
| Interceptor | Middleware for logging, auth, tracing, and metrics |
| Deadline | Hard cut-off time after which a call is cancelled |
| Status code | Standardised result code (OK, NOT_FOUND, UNAVAILABLE, etc.) |
| Backward compatibility | Ability of new schema versions to read old messages safely |