{"canonical_url":"https://engineer.company/uk/glossary/grpc/","content_markdown":"# gRPC\n\n## Що це таке\n\ngRPC — це фреймворк для віддаленого виклику процедур. Програма викликає метод на\nсервері, що працює на іншій машині, так, ніби сервер був локальним об'єктом, а\ngRPC переносить виклик мережею у власному протоколі поверх HTTP/2 і доставляє\nвідповідь назад як значення, яке повертає метод.\n\nУсе починається з визначення сервісу: методів, які можна викликати ззовні, з\nтипом кожного запиту й кожної відповіді. За замовчуванням його описують за\nдопомогою Protocol Buffers у файлі, назва якого закінчується на `.proto`.\nProtocol Buffers — це формат Google з відкритим кодом для серіалізації даних,\nнезалежний від мови та платформи. Можна підключити й інші формати, але без\nокремих вказівок gRPC використовує саме protocol buffers. Компілятор `protoc`\nразом із плагіном gRPC читає цей файл і генерує код для обох половин. Клієнт\nотримує stub — локальний об'єкт із тими самими методами, що й сервіс (у деяких\nмовах його називають просто клієнтом), а сервер отримує інтерфейс, який треба\nреалізувати. Оскільки обидві половини походять з одного файлу, сервер, написаний\nна Java, може відповідати клієнтам, написаним на Go, Python чи Ruby.\n\nМетод має одну з чотирьох форм. Унарний метод приймає один запит і повертає одну\nвідповідь, як звичайний виклик функції. Метод із серверним потоком приймає один\nзапит і надсилає назад потік відповідей, метод із клієнтським потоком робить\nнавпаки, а двонаправлений потоковий метод дає обом сторонам надсилати свої\nпотоки незалежно одна від одної. У межах одного виклику gRPC гарантує, що\nповідомлення надходять у тому порядку, в якому їх надіслали.\n\nНа рівні мережі gRPC працює поверх HTTP/2. Кожен виклик — це `POST` на шлях, що\nскладається з повного імені сервісу та назви методу, з типом вмісту\n`application/grpc`. Кожне повідомлення йде за п'ятибайтовим префіксом: один байт\nкаже, чи стиснуте повідомлення, а чотири задають його довжину. Результат виклику\n— це не HTTP-статус. Відповідь, яку формує сам gRPC, має статус 200, навіть коли\nвиклик завершився помилкою, а справжній результат приходить у трейлерах, тобто\nполях заголовків, які надсилають після тіла: `grpc-status` із числом і, за\nпотреби, `grpc-message` з описом помилки.\n\nЧерез це gRPC — зовсім інша річ, ніж REST. REST API називає ресурси й працює з\nними власними методами та кодами статусу HTTP, зазвичай із тілами в JSON, які\nможе прочитати будь-хто. gRPC API — це перелік методів із типізованими\nдвійковими повідомленнями, а HTTP/2 — лише транспорт під ними. Документація\nProtocol Buffers сама підсумовує свій формат так: «як JSON, тільки менший і\nшвидший».\n\n## Чому це важливо\n\nСпершу контракт, а код випливає з нього. У багатьох HTTP API опис і код, що\nобслуговує API, — дві окремі речі, які можуть розійтися, а клієнта часто пишуть\nвручну за документом. У gRPC файл `.proto` — єдине місце, де визначають метод чи\nполе, і з нього генерують усіх клієнтів і всі сервери. Зміна повідомлення\nдоходить до кожної мови через той самий генератор, а не через те, що хтось\nперечитав документ.\n\nКодування компактне, бо кожне поле передається як його номер і значення, а не як\nназва. Ціна в тому, що повідомлення неможливо повністю розтлумачити без його\nфайлу `.proto`, адже protocol buffers не описують самі себе, і що формат\nрозрахований на те, що ціле повідомлення вміщується в пам'ять за один раз.\nВласна документація формату радить інше рішення для даних, більших за кілька\nмегабайтів.\n\nПотокова передача — частина задуму, а не надбудова. Виклики йдуть як потоки в\nз'єднаннях HTTP/2, тож метод із серверним потоком може й далі надсилати\nрезультати тим самим механізмом, що й виклик, який відповідає один раз.\n\nОбмеження часу супроводжує виклик. Клієнт задає дедлайн, gRPC передає залишок\nчасу в заголовку `grpc-timeout`, а коли час спливає, клієнт отримує\n`DEADLINE_EXCEEDED`, а виклик на боці сервера скасовується. Коли сервер сам\nвикликає інший сервер, деякі реалізації передають дедлайн далі: Java і Go\nроблять це за замовчуванням, а в C++ це треба ввімкнути. Оскільки дедлайн\nперетинає кожну ланку як залишок часу, а не як позначка часу на годиннику,\nмашини з розбіжними годинниками однаково припиняють чекати в той самий момент.\n\nПомилки мають спільний словник. gRPC визначає 17 кодів статусу, від 0 `OK` до 16\n`UNAUTHENTICATED`, і вони є частиною самого протоколу, тож клієнт на Go і сервер\nна Java однаково розуміють, що означає `NOT_FOUND` чи `UNAVAILABLE`.\n\nУсе це добре підходить для трафіку між сервісами, які контролює одна команда чи\nодна компанія, де обидва кінці можуть ділитися файлами `.proto` і збиратися з\nних. Для браузера це підходить гірше. Власні нотатки проєкту gRPC про протокол\nкажуть, що браузери не дають скриптам доступу до фреймів HTTP/2 і ніколи не\nдаватимуть, тому код у браузері розмовляє окремим протоколом, gRPC-Web, і\nзазвичай проксі перекладає його на нативний gRPC.\n\n## Як це виглядає на практиці\n\nОсь невеликий сервіс виставлення рахунків. Унарний метод отримує один рахунок, а\nметод із серверним потоком надсилає рахунки замовника по одному:\n\n```protobuf\nsyntax = \"proto3\";\n\npackage billing.v1;\n\nservice InvoiceService {\n  rpc GetInvoice(GetInvoiceRequest) returns (Invoice);\n  rpc WatchInvoices(WatchInvoicesRequest) returns (stream Invoice);\n}\n\nmessage GetInvoiceRequest {\n  string invoice_id = 1;\n}\n\nmessage WatchInvoicesRequest {\n  string customer_id = 1;\n}\n\nmessage Invoice {\n  reserved 4;\n  reserved \"discount_code\";\n  string invoice_id = 1;\n  string customer_id = 2;\n  int64 total_cents = 3;\n  string currency = 5;\n}\n```\n\nЧисла тут — не значення за замовчуванням. Це номери полів, і в двійковому\nкодуванні вони ідентифікують кожне поле замість його назви. Номери від 1 до 15\nзаймають один байт, тож їх варто віддавати полям, які заповнюють найчастіше. Два\nрядки `reserved` фіксують поле, яке колись існувало, номер 4 з назвою\n`discount_code`, щоб ні номер, ні назва не повернулися як інше поле.\n\nДля Python одна команда генерує `billing_pb2.py` з класами повідомлень і\n`billing_pb2_grpc.py` з класами клієнта й сервера:\n\n```sh\npython -m grpc_tools.protoc -Iprotos \\\n  --python_out=. --grpc_python_out=. protos/billing.proto\n```\n\nОдин виклик `GetInvoice` у фреймах HTTP/2 тоді виглядає так:\n\n```text\nHEADERS (flags = END_HEADERS)\n:method = POST\n:scheme = https\n:path = /billing.v1.InvoiceService/GetInvoice\n:authority = billing.example.com\nte = trailers\ncontent-type = application/grpc+proto\ngrpc-timeout = 2S\n\nDATA (flags = END_STREAM)\n\u003cLength-Prefixed Message\u003e\n\nHEADERS (flags = END_HEADERS)\n:status = 200\ncontent-type = application/grpc+proto\n\nDATA\n\u003cLength-Prefixed Message\u003e\n\nHEADERS (flags = END_STREAM, END_HEADERS)\ngrpc-status = 0\n```\n\n`2S` означає дві секунди, а `te = trailers` потрібен, щоб виявляти проксі,\nнесумісні з gRPC. Якщо рахунку не існує, відповідь однаково починається з\n`:status = 200`, а останній фрейм несе `grpc-status = 5`, тобто `NOT_FOUND`,\nразом із `grpc-message` на кшталт `invoice not found`. Сервер, який одразу\nзавершує виклик помилкою, може навіть надіслати єдиний фрейм `HEADERS` зі\nстатусом і без жодного повідомлення.\n\nГенерувати обидві сторони з одного контракту — не винахід gRPC. В одному проєкті\nз портфоліо сайту\n[контракт API згенерували з бази даних назовні](/uk/portfolio/generated-the-api-contract-from-the-database-out/)\nдля API, описаного в OpenAPI. Ланцюг починається з бази даних і тягнеться\nназовні: типи Go визначають API, Huma формує з них опис OpenAPI, з цього опису\nгенеруються типізований клієнт на TypeScript і mock-обробники, а перевірка\nконтракту в CI зупиняє збірку, коли те, що надсилає фронтенд, перестає збігатися\nз тим, чого чекає API. gRPC вбудовує ту саму дисципліну у свій інструментарій,\nде єдиним джерелом є файл `.proto`.\n\n## Де виникають проблеми\n\n**Виклик без дедлайну може чекати вічно.** За замовчуванням gRPC не задає\nдедлайну, тож клієнт, який викликає сервер, що завис, може чекати відповіді\nфактично вічно. Задавайте кожному виклику реалістичний дедлайн. У Python це\nаргумент `timeout` у секундах:\n\n```python\nimport grpc\n\nimport billing_pb2\nimport billing_pb2_grpc\n\ncredentials = grpc.ssl_channel_credentials()\nwith grpc.secure_channel(\"billing.example.com:443\", credentials) as channel:\n    stub = billing_pb2_grpc.InvoiceServiceStub(channel)\n    request = billing_pb2.GetInvoiceRequest(invoice_id=\"INV-1001\")\n    invoice = stub.GetInvoice(request, timeout=2.0)\n```\n\nКоли час спливає, виклик кидає `grpc.RpcError`, а метод `code()` цього винятку\nповертає `grpc.StatusCode.DEADLINE_EXCEEDED`. На сервері gRPC скасовує виклик із\n`CANCELLED`, щойно дедлайн минув, але зупинити роботу, яку запустив обробник,\nмає власний код сервісу, тож обробник, що працює довго, мусить сам перевіряти,\nчи виклик скасовано, і зупинятися.\n\n**Таймаут не означає, що нічого не сталося.** Клієнт і сервер кожен сам вирішує,\nчи вдався виклик, тож виклик може успішно завершитися на сервері й водночас\nупасти на клієнті з `DEADLINE_EXCEEDED`. Зміни, зроблені до скасування, теж не\nвідкочуються. Клієнт, який просто повторює спробу, може створити той самий\nрахунок двічі. Протокол не вважає виклик ідемпотентним, якщо його явно так не\nпозначено. `UNAVAILABLE` — код, який найчастіше означає тимчасовий збій і за\nякого варто повторити спробу з backoff, але документація кодів статусу\nпопереджає, що повторювати неідемпотентні операції не завжди безпечно. Той самий\nдокумент покладає на код, що робить виклики, рішення, за яких кодів повторювати\nспробу.\n\n**Повторно використаний номер поля псує дані.** Номер поля не можна змінювати,\nколи тип повідомлення вже використовується. Якщо поле видалити, а його номер\nзгодом віддати новому полю, старіші клієнти й збережені повідомлення декодують\nнове поле з байтів, які означали щось інше. Посібник з Protocol Buffers\nперелічує можливі наслідки: помилки розбору, витік персональних даних і\nпошкоджені дані. Ніколи не перенумеровуйте поле і резервуйте кожен видалений\nномер і кожну назву, як у прикладі вище.\n\n**Кожна помилка для HTTP виглядає як успіх.** Оскільки gRPC відповідає\nHTTP-статусом 200, навіть коли виклик завершився помилкою, усе, що оцінює трафік\nлише за HTTP-статусом, наприклад журнал доступу чи частка помилок, побудована на\nкодах статусу, зараховує збої до успіхів. Специфікація саме з цієї причини каже\nсерверам відповідати 415 на запити з типом вмісту, відмінним від\n`application/grpc`, щоб інші клієнти HTTP/2 не прочитали помилку gRPC як успіх.\nРахуйте за `grpc-status`, а не за `:status`.\n\n**Довгі потоки прив'язують навантаження до одного сервера.** Виклики йдуть як\nпотоки в спільному з'єднанні HTTP/2, і щойно потік почався, його не можна\nперенести на інший сервер. Потік, що живе годинами, тримає своє навантаження\nтам, де почався, хоч скільки серверів додадуть пізніше. Кожне з'єднання також\nмає ліміт одночасних потоків, і коли його досягнуто, наступні виклики чекають на\nклієнті, доки якийсь потік не завершиться. Посібник gRPC з продуктивності радить\nвикористовувати потоки лише там, де вони дають суттєвий виграш у продуктивності\nчи простоті, і виділяти окремий канал для кожної ділянки з високим\nнавантаженням.\n\n**Великі обсяги даних не вміщуються в одне повідомлення.** gRPC обмежує\nмаксимальний розмір повідомлення, і повідомлення, більше за налаштований ліміт,\nвідхиляється з `RESOURCE_EXHAUSTED` на тій стороні, яка його надсилає чи\nотримує. Підвищення ліміту лише переносить проблему, бо protocol buffers\nочікують усе повідомлення в пам'яті, а з великими даними там одночасно може\nопинитися кілька серіалізованих копій. Розбивайте великі дані на потік менших\nповідомлень або виносьте їх за межі gRPC.\n\n## Що почитати далі\n\n- [Core concepts, architecture and lifecycle](https://grpc.io/docs/what-is-grpc/core-concepts/)\n  — визначення сервісів, чотири види методів, stubs, дедлайни та скасування.\n- [gRPC over HTTP2](https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md)\n  — протокол на рівні мережі: шляхи, заголовки, префікс повідомлення і статус у\n  трейлерах.\n- [Status Codes](https://grpc.io/docs/guides/status-codes/) — усі 17 кодів, що\n  означає кожен і які з них сама бібліотека ніколи не формує.\n- [Deadlines](https://grpc.io/docs/guides/deadlines/) — чому немає значення за\n  замовчуванням, як дедлайни доходять до сервера і як вони передаються між\n  сервісами.\n- [Language Guide (proto 3)](https://protobuf.dev/programming-guides/proto3/) —\n  номери полів, зарезервовані поля і правила безпечної зміни типу повідомлення.\n\n\u003chttps://engineer.company/uk/glossary/grpc/\u003e\n","date_modified":"2026-10-29T11:17:41Z","description":"Як файл .proto стає згенерованими клієнтами й серверами, що спілкуються через HTTP/2, і де підводять дедлайни, номери полів і повторні спроби.","formats":{"gemtext":"https://engineer.company/uk/glossary/grpc/index.gmi","gopher":"https://engineer.company/uk/glossary/grpc/gophermap","html":"https://engineer.company/uk/glossary/grpc/","json":"https://engineer.company/uk/glossary/grpc/index.json","markdown":"https://engineer.company/uk/glossary/grpc/index.md","pdf":"https://engineer.company/uk/glossary/grpc/index.pdf"},"kind":"page","language":"uk","title":"Що таке gRPC?","url":"https://engineer.company/uk/glossary/grpc/","version":1}