Англійська для розробників oRPC

oRPC є бібліотекою TypeScript для створення end-to-end API безпечних для типів, використовуючи модель RPC (віддалене викликання процедури) замість написаних вручну REST або GraphQL схем — клієнт викликає функцію, а типи переносяться з сервера на клієнта без кодгену. Оскільки він знаходиться на перетині розмов про «дизайн API» і «типову систему», обговорення перегляду змішують контрактний словник з словником TypeScript. Ось англійська, яку вам потрібно, щоб говорити про це чітко.

---

Процедури і контракти

Procedure — базовий блок API oRPC, одна викликана функція, відкрита для клієнтів, приблизно аналогічна кінцевій точці REST або розв’язувачу GraphQL.

“Збережемо цю процедуру як одну замість розділення її на три — клієнту потрібно викликати її лише як одну одиницю.”

Contract-first — визначає форму вхідних і вихідних даних (через схему) перед реалізацією логіки процедури, тому контракт типу існує незалежно від будь-якої реалізації.

• “Ми почали з контракту, щоб команда фронтенду могла почати роботу над інтерфейсом користувача ще до того, як буде написано розв’ язувач.” *

** Схема вводу/ виводу ** — схема перевірки (часто Zod), приєднана до процедури, яка визначає і намагається виконати прийняті аргументи і форму повернення.

“400, що ви бачите, це вхідна схема, що відкидає запит — в корисному навантаженні відсутнє поле userId.”

---

Тип Безпека і виведення

** Безпека типів від початку до кінця ** — властивість, за якої зміна типів процедури на стороні сервера негайно відображається як помилка типу на клієнті, без вручну синхронізації.

“Це і є суть цієї пропозиції — перейменуйте поле на сервері, і виклик клієнта змінить колір на червоний у вашому редакторі ще до того, як ви запустите щось.”

Type inference — TypeScript автоматично виводить типи вводу/виводу процедури з її схеми, замість того, щоб розробник вручну писав відповідні інтерфейси з обох сторін.

“Ми більше не підтримуємо пакунок спільних типів — виведення обробляє його, тому є на одну річ менше, що може вийти з синхронізації.”

** Маршрутизатор ** — об’ єкт, який групує пов’ язані процедури у вкладений, викликаний простір імен на клієнті (наприклад, client.users.get, client.users.create ).

“Пересунути цю процедуру під маршрутизатор billing — вона не належить під users концептуально, навіть якщо вона зараз живе там.”

---

Транспорт та зв’язок

** Проміжне програмне забезпечення ** — логіка багаторазового використання (перевірка автентичності, ведення журналу, обмеження швидкості), яка виконується перед обробником процедури, з якою можна працювати у декількох процедурах.

• “Додати до цієї процедури проміжне програмне забезпечення аутентифікації — зараз його можна викликати без сеансу, що є справжнім прогалиною.” *

RPC-over-HTTP — підхід oRPC до серіалізації викликів процедур як HTTP-запитів під капотом, при цьому все ще представляючи інтерфейс виклику функцій для розробника.

“Він все ще говорить простим HTTP під капотом, тому ми можемо вдарити ці процедури з curl для зневадження, навіть якщо клієнт ніколи не робить цього.”

Adapter — частина коду, що з’єднує маршрутизатор oRPC з певною серверною платформою (Node’s http, Hono, Next.js маршрутизатори, тощо).

“Ми не заблоковані в одній структурі — зміна адаптера на Hono не вимагає торкання жодного визначення процедури.”

---

Поширені помилки

• Сказати «тип неправильний» без вказівки, чи невідповідність походить з схеми, інструкції повернення процедури, або використання клієнта — кожен потребує іншого виправлення.
• Розгляд «контракту» і «схеми» як неспоріднених концепцій в огляді, коли схема є конкретною реалізацією контракту.
• Забув, що порядок проміжного програмного забезпечення має значення, а потім заплутався, коли перевірка автентифікації запускалася після виклику бази даних, яку вона мала захищати.

Практичні вправи

1. Поясніть у двох реченнях розробнику, що використовує REST, різницю між процедурою і маршрутизатором.
2. Написати короткий опис PR для додавання проміжного програмного забезпечення автентифікації до процедури, яка раніше не була захищена.
3. Створити коментар перегляду коду, у якому буде пояснено, чому пакунок спільних типів не потрібний, якщо використовувати виведення типів з кінця до кінця.

Зв’язані ресурси

• Англійська для розробників TypeScript
• Англійська мова для API Design Reviews
• Англійська для розробників tRPC

Навигація по нюансах: практична англійська для oRPC команд

Основний словник * oRPC * - включаючи такі поняття, як контракти, середнє програмне забезпечення, і навіть сам RPC - може відчувати себе на диво щільним, коли намагається ефективно спілкуватися в команді розробників. Легко впасти в надто технічний жаргон або боротися, щоб точно сформулювати те, що потрібно зробити, особливо коли справа доходить до складних взаємодій між різними службами. Цей розділ зосереджений на перекладі цих технічних термінів на ясну, дієву англійську, особливо актуальну для носіїв англійської мови, які не є рідними для них, які прагнуть професійної ясності в своїх обговореннях. Метою є не просто використовувати правильні слова, але ефективно виражати наміри і очікування - важливий елемент, який часто відсутній у чисто технічному спілкуванні.

Розглянемо сценарій під час перегляду коду: «Цей запит змінює правила перевірки контракту User. Нам потрібно забезпечити зворотну сумісність з існуючими споживачами цієї послуги. ” Це твердження є точним, але потенційно заляканим для когось, хто менш знайомий з нюансами контрактів і версій. Більш зрозумілим варіантом може бути: « Ми оновлюємо спосіб перевірки даних користувачів у цьому запиті, але ми хочемо переконатися, що старі версії служби все ще можуть читати і обробляти дані цих користувачів правильно ». Зауважте, що у переглянутій формулюванні уникається надмірно технічних термінів, таких як « правила перевірки », і замість цього сконцентровано увагу на * результаті * — забезпечення того, щоб існуючі користувачі продовжували функціонувати. Аналогічно, при описі нового компонента середовища — «Це середовище обробляє автентифікацію за допомогою JWT-токенів» — ясніше пояснення може бути: «Ця частина коду перевіряє, чи користувач має доступ до цієї служби, перевіряючи їхні дані»

Крім того, ключовим є активне спілкування про потенційні проблеми. Замість того, щоб сказати «Є невідповідність імпедансу», розробник повинен намагатися зробити щось на зразок: «Структура даних, що повертається, не ідеально збігається з очікуваннями, визначеними в контракті. Нам потрібно розв’язати цю проблему до її розгортання». Це підкреслює проблему - невідповідність - а не викидає жаргон. Навчання розв’язувати технічні проблеми з точки зору користувача - як це впливає на кінцевого користувача або інші послуги - є безцінним. Ефективне спілкування будує довіру і уникає непорозумінь, що призводить до гладких циклів розвитку.

Ось приклад використання curl для взаємодії зі службою oRPC:

curl -X POST \
  http://orpc-service/users \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  }'

Ця проста команда показує практичне застосування розуміння API- запитів і відповідей — основний елемент обміну даними oRPC, незалежно від вашої рідної мови. Ключовим є переклад наміру команди на просту англійську: «Ми відправляємо ці дані до кінцевої точки users служби oRPC, щоб створити новий обліковий запис користувача»