Англійська для обробки помилок gRPC

gRPC є високопродуктивним віддаленим викликом процедур, який широко використовується в архітектурах мікросервісів. На відміну від REST, який використовує коди стану HTTP для обміну помилками, gRPC має власний набір кодів стану і моделі помилок. Якщо ви працюєте зі службами gRPC і співпрацюєте англійською мовою, розуміння того, як чітко обговорювати обробку помилок, зробить ваші перегляди коду, обговорення проектування і документацію набагато ефективнішими.

Ключовий словник

Код стану gRPC визначає набір стандартних кодів стану, які вказують на результат виклику RPC. На відміну від кодів стану HTTP, коди стану gRPC є мовними агностиками і семантично специфічними. Поширені приклади включають OK, NOT_FOUND, INVALID_ARGUMENT, і UNAVAILABLE. Приклад: «Коли запитаного ресурсу не існує, ми повертаємо статус NOT_FOUND, а не загальну помилку.»

** Закінчення метаданих ** У gRPC додаткову інформацію про помилку можна додати до відповіді як кінцеві метадані — пари ключ- значення, які надсилаються після тіла відповіді. Це дозволяє серверам надавати структуровані відомості про помилку разом з кодом стану.

• Приклад: « Ми включаємо помилки перевірки полів у кінцеві метадані, щоб клієнт міг показувати користувачеві певні повідомлення про помилки. » *

Крайний термін Термін виконання — це момент часу, до якого RPC має бути завершено. Якщо термін закінчення перевищується, виклик зазнає невдачі зі станом DEADLINE_EXCEEDED. Встановлення відповідних термінів є ключовою частиною створення стійких служб gRPC.

• Приклад: « Ми встановили двосекундний термін для всіх викликів до служби інвентарізації, щоб запобігти каскадним тайм- аутам. » *

** Правило повторення спроб ** Правило повторення визначення умов, за яких неможливий віддалений виклик процедури (RPC) має бути автоматично повторено, і кількості повторень. gRPC підтримує налаштування правил повторення на рівні каналу. Приклад: «У нас є правила повторних спроб, налаштовані на повторні спроби до трьох разів на помилки UNAVAILABLE з експоненційним відступом.»

Перехоплювач Перехоплювач є середнім програмним забезпеченням для gRPC — компонентом, який перехоплює вихідні або вхідні виклики, щоб додати крос-сегментні проблеми, такі як ведення журналу, автентифікація або збагачення помилок.

• Приклад: « Наш перехоплювач на стороні сервера ловить всі необроблені винятки і відображає їх відповідними кодами стану gRPC. » *

Поширені сценарії, де використовується ця мова

В обзоре кода: “Я помітив, що цей обробник повертає INTERNAL для всіх помилок. Ми повинні бути більш конкретними — якщо вхід невірний, ми повинні повернути INVALID_ARGUMENT, щоб клієнт знав, що це проблема з запитом, а не з помилкою сервера»

** У обговоренні дизайну API: ** « Для цього RPC, який код стану ми повинні повернути, коли користувач намагається створити ресурс, який вже існує? У gRPC, ALREADY_EXISTS є традиційним вибором для цього сценарію»

** Під час зневадження інциденту: ** “Попередження показує пік DEADLINE_EXCEEDED помилок на платіжному сервісі. Зазвичай це означає, що або база даних, що виконується нижче, працює повільно, або клієнт встановлює нерозумно короткий термін виконання. Давайте перевіримо обидва»

** Під час написання документації щодо обслуговування: ** Документування кодів стану, які може повернути метод gRPC, є важливим для команд споживачів. Кожен можливий стан помилки має бути вказано у списку разом з кодом стану, описом і рекомендованою відповіддю з боку клієнта.

Корисні фрази для обговорення обробки помилок gRPC

• Цей RPC може повернути NOT_FOUND, якщо користувача не існує, або PERMISSION_DENIED, якщо викликаючий не має доступу
• «Ми завжди повинні встановлювати термін вихідних RPC, щоб уникнути нескінченного блокування»
• «Статус UNAVAILABLE зазвичай можна отримати знову — клієнт повинен відступити і спробувати знову»
• «Ми використовуємо перехоплювач для відображення винятків домену до відповідних кодів стану gRPC»
• «Розширення деталей помилки дозволяє нам включати структуровану інформацію про помилку разом з кодом стану.»
• «FAILED_PRECONDITION тут є відповідним — операція не дозволена, враховуючи поточний стан ресурсу.»
• «Ми повинні розрізняти між INVALID_ARGUMENT для поганих вхідних даних і OUT_OF_RANGE для значень поза прийнятними межами»
• «Клієнт повинен розглядати помилки INTERNAL як невідновлювані — щось несподіване сталося на сервері»
• «Ми розповсюджуємо термін від вхідного запиту до всіх вихідних RPC, щоб дотримуватися бюджету тайм-аута виклику»
• «Додамо тест, який перевіряє правильний код стану, який повертається для кожного сценарію помилки.»

Документування відповідей на помилки gRPC

Під час документування служби gRPC, до кожного визначення методу слід додавати таблицю помилок. Для кожної можливої помилки, задокументуйте: код стану, умову, яка спричинила її, і дії, які повинен виконати клієнт.

Приклад документації для методу GetUser:

• OK : Користувача було знайдено і успішно повернено.
• NOT_FOUND : Користувача з вказаним ІД не існує. Клієнт повинен показувати повідомлення « користувача не знайдено ».
• INVALID_ARGUMENT : Наданий ІД користувача не є коректним UUID. Клієнт повинен перевірити введення перед викликом цього методу.
• PERMISSION_DENIED : Викликаючий не має прав доступу до даних цього користувача. Якщо термін дії сеансу користувача закінчився, клієнт має перенаправити його на сторінку реєстрації.
• INTERNAL : сталася неочікувана помилка сервера. Клієнт повинен показати загальне повідомлення про помилку і записати помилку у журнал для дослідження.

Практичні рекомендації

Перегляньте документацію щодо служби gRPC, з якою ви працюєте або яка вам знайома. Вкажіть один метод, який не має чіткої документації щодо помилок. Написати повну таблицю помилок для цього методу англійською мовою, у якій буде описано всі коди стану, які може повернути цей метод, і дії, які слід виконати клієнту у кожному з випадків. Спробуйте вказати умови, які спричиняють кожну з помилок, і рекомендовані дії клієнта.

Переклади: «Переклади з англійської мови» (англ. Translations from English to Polish)

Будьмо чесними - переклад технічного жаргону безпосередньо з вашої рідної мови на англійську не завжди ефективний. Це може призвести до непорозумінь, особливо в команді, де всі говорять однією і тією ж професійною англійською. Проблема не тільки в тому, щоб знати що означає код помилки; це про те, щоб передати це значення чітко і конструктивно, використовуючи фрази, які сигналізують про невідкладність, відповідальність або просто прохання про пояснення. Розглянемо цей типовий сценарій: ви надіслали запит на завантаження, що містить grpc_status з code = 5, що вказує на невдалий виклик сервера через тайм- аут. Ваша колега Марія (яка розмовляє переважно іспанською) відповідає: « Гаразд, код помилки п’ять. Чи виправлено це?» Хоча ця відповідь технічно правильна, вона не надає вам достатньо контексту, щоб ви могли зрозуміти, * чому * стався перевищення часу очікування або що слід зробити. У ній відсутня важлива інформація про основну причину і можливі рішення.

Ефективніша відповідь була б підтвердженням помилки, підштовхуючи до подальшого розслідування. Наприклад, Марія може сказати: «Гаразд, я бачу тайм-аут grpc_status = 5. Чи можете ви перевірити, чи не перевантажено службу сервера? Можливо, нам слід збільшити обмеження одночасності або реалізувати логіку повторних спроб для цих запитів. » Зауважте, що у цьому фрагменті використано певну термінологію (« служба сервера », « обмеження одночасності », « логіка повторних спроб ») і запропоновано обговорення, а не просто висловлення спостереження. Цей підхід відповідає найкращим практикам в професійній розробці програмного забезпечення - зосереджуючись на тому, * чому * щось не вдалося і пропонуючи конкретні кроки для його вирішення. Аналогічно, якщо ви пишете коментар про перегляд коду про помилку gRPC, уникаючи фраз на кшталт «Це неправильно» і вибираючи «grpc_status вказує на потенційну проблему мережі; розгляньте можливість додавання функціональності автоматичного вимкнення» демонструє більш обдуманий підхід.

Крім того, рівень необхідних деталей залежить від контексту. Під час швидкого повідомлення Slack, у якому обговорюється незначна проблема, може бути достатньо короткого пояснення. Однак, у формальному описі PR або під час перегляду коду, надання багатшого контексту - включаючи відповідні журнали, метрики і потенційні кореневі причини - має вирішальне значення для ефективного зневадження і запобігання майбутнім проблемам. Пам’ятайте, чітке спілкування не тільки про точність; це про сприяння розумінню і співпраці в команді. Це також про демонстрацію професіоналізму і прийняття відповідальності за проблему.

Ось приклад, який показує, як коди grpc_status можуть з’ являтися у повідомленні журналу:

ERROR [2023-10-27 14:35:22 UTC] gRPC Client: Call to /users failed with status code: 5 (DeadlineExceeded) - Timeout waiting for server response.

Ключовим моментом є те, що ви не просто повідомляєте про помилку; ви надаєте структурований опис проблеми, включаючи конкретний код grpc_status і будь-які супутні деталі, які допомагають в діагностиці. Цей рівень точності є важливим під час співпраці з іншими інженерами, які можуть не мати досвіду у процесі розробки або у архітектурі системи.