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

tRPC швидко зростає в TypeScript full-stack командах, і його словник має характерний смак, який поєднує концепції backend API з термінологією типової системи TypeScript. Якщо ви приєдналися до команди, що використовує tRPC, а англійська не є вашою першою мовою, ви можете виявити, що не знаєте, як описати « процедуру », пояснити « безпеку типів від початку до кінця » або запитати про « контекст » під час перегляду коду, не здаваючись неопределенным. У цьому підручнику ви знайдете точний словник і фрази англійською мовою, які досвідчені розробники tRPC використовують щодня.

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

Процедура Фундаментальний блок API tRPC. Процедура є однією викликною кінцевою точкою, визначеною .query() або .mutation() (або .subscription() ). Він замінює концепцію маршруту REST або розв’язувача GraphQL.

• Приклад: « Я додав процедуру getUser під маршрутизатором користувача, яка отримує користувача за ідентифікатором з бази даних. » *

** Запит ** Процедура tRPC визначена з .query(), яка читає дані без побічних ефектів. Еквівалент HTTP GET у інтенсі. Запити повинні бути idempotent — викликаючи їх декілька разів, ви отримаєте той самий результат. Приклад: “Процедура listPosts є запитом, оскільки вона тільки читає з бази даних і ніколи не змінює стан.”

Мутація Процедура tRPC, визначена .mutation(), яка змінює стан на стороні сервера — створює, оновлює або вилучає дані. Еквівалентний за змістом HTTP POST, PUT, PATCH або DELETE. Приклад: «Ми виявили deleteComment як мутацію, оскільки вона назавжди вилучає запис з бази даних.»

Маршрутизатор Збірка процедур, згрупованих за спільним простором імен. Маршрутизатори можуть бути вкладені для створення ієрархічної структури API. Кореневий маршрутизатор зазвичай називається appRouter. Приклад: “Ми розділили API на три маршрутизатори — userRouter, postRouter, і commentRouter — і об’єднали їх в appRouter.”

** Контекст ** Об’ єкт, створений за запитом (за допомогою функції createContext), який вводиться у кожну процедуру. Контекст зазвичай містить з’ єднання бази даних, аутентифікований сеанс користувача та інші ресурси, що відповідають обсягу запиту.

• Приклад: « Сеанс користувача знаходиться у контексті, тому кожна процедура може перевіряти автентифікацію без повторення логіки автентифікації. » *

** Проміжне програмне забезпечення ** Функція, яка виконується перед розв’ язувачем процедури і може читати або змінювати контекст, показувати помилку або скорочувати запит. Зазвичай використовується для захисту автентифікації і ведення журналу. Приклад: “Ми написали protectedProcedure середнє програмне забезпечення, яке викидає UNAUTHORIZED помилку, якщо в контексті немає сеансу.”

** Безпека типу “край-край” ** Гарантія того, що типи TypeScript перетікають без проміжків від визначень вводу і виводу процедури сервера до місця виклику клієнта, без необхідності ручного введення типів або кроків створення коду. Приклад: “tRPC дає нам безпеку типу end-to-end — якщо я перейменую поле вводу процедури на сервері, компілятор TypeScript негайно позначає застарілий виклик клієнта.”

** appRouter / визначення маршрутизатора** Один кореневий маршрутизатор, який було експортовано з сервера і використано для визначення типу клієнта. Тип клієнта походить з RouterInputs і RouterOutputs інструментів, зберігаючи типи клієнтів постійно в синхронізації з визначеннями сервера. Приклад: “Ми експортуємо AppRouter з серверного пакунку і імпортуємо його в клієнт, щоб TypeScript знав точну форму кожної процедури.”

Звичайні фрази

** В обзорах коду: **

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

В стоячих позах:

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

** У документації: **

• Всі процедури, що вимагають автентифікації, повинні бути побудовані на protectedProcedure, що вимагає чинного сеансу через середнє програмне забезпечення
• «Вхідні форми перевіряються за допомогою схем Zod, приєднаних до кожної процедури; виведені типи TypeScript автоматично доступні на клієнті»
• «Вкладіть маршрутизатори за доменом функцій і об’єднайте їх в appRouter ; уникати розміщення процедур безпосередньо на кореневому маршрутизаторі»

Фрази, яких слід уникати

Скажите “конечная точка”, когда вы имеете в виду “процедура.” У tRPC правильним терміном є « процедура ». Використання « кінцевої точки » не є помилкою (процедури tRPC відображаються на кінцевих точках HTTP під капотом), але це свідчить про незнання власного словника tRPC. У обговореннях команди використовуйте «процедура», «запит» або «мутація», щоб бути точним.

**Слово “тип-безпечний API” означає безпеку типу end-to-end. ** REST API з написаними від руки TypeScript інтерфейсами також є «тип-безпечними» у вільному сенсі. Конкретне значення tRPC забезпечує * end-to-end * безпеку типів - типи перетікають від сервера до клієнта без ручної синхронізації. Використовуйте повний текст: « end- to- end type safety » або « inferenced types across the client- server boundary. »

** Використання фрази « контекст має користувача », коли ви маєте на увазі « контекст переносить сеанс ». ** Не вживайте неясних слів. У англійській мові на командах tRPC, скажіть: « Об’ єкт сеансу у контексті показує розпізнаного користувача ». Цей варіант буде більш точним і показує, що ви розумієте, що контекст є структурованим об’ єктом, а не простою змінною.

Краткий справочник

Term	How to use it
procedure	”Add a getProfile procedure to the user router.”
query	”Use a query for any read-only data fetch.”
mutation	”Expose data changes as mutations, not queries.”
context	”Thread the db client through context, not procedure arguments.”
end-to-end type safety	”Rename a server field and the client breaks at compile time — that is end-to-end type safety.”

Навигація складності: Посібник з tRPC термінології

tRPC це не просто набір коду; це спосіб мислення про будівництво надійних, безпечних API. Успішно поширювати ці ідеї - особливо при співпраці з іншими - вимагає певного словникового запасу і фразування. Для людей, для яких англійська не є рідною мовою, це може бути особливо складним, тому розберемо деякі ключові терміни і як їх впевнено обговорювати. Знання нюансів щодо * маршрутизації *, * безпеки типів від початку до кінця * і архітектури tRPC значно поліпшить вашу здатність брати участь у технічних обговореннях і ефективно робити свій внесок.

Розглянемо звичайний сценарій: коментар перегляду коду. Уявіть, що ви отримуєте такий відгук на PR, що пропонує зміну логіки маршрутизації: «Ця обробка маршруту могла б отримати користь від яснішої документації, яка б описувала очікувані типи вводу і потенційні сценарії помилок. Розгляньте можливість додавання тверджень для більш суворих вимог щодо типів. » Ключовим тут є не лише переклад слів, але і розуміння * чому* використовується ця фраза. « Яскравіша документація » передбачає потребу у більшій точності — важливому елементі професійного спілкування. Аналогічно, «суворіше виконання типу» відноситься до використання властивих переваг tRPC в гарантії цілісності даних. Це стосується передачі не тільки того, що потрібно зробити, але і того, як це збігається з основними принципами tRPC. Фрази на кшталт «використання властивих переваг tRPC» демонструють розуміння технології в грі — знак технічної майстерності і залучення.

Іншою поширеною ситуацією є обговорення налаштування маршрутизатора. Уявіть повідомлення Slack: « Нам потрібно змінити поріг затримки маршруту, щоб поліпшити час відповіді для наших мобільних користувачів ». Фраза тут зосереджена на * впливі * - « поліпшити час відповіді ». Це не тільки про швидкість; це про досвід користувача, і ефективне повідомлення про вплив є життєво важливим. Використання таких термінів, як «поріг затримки» демонструє знайомство з технічною деталлю, в той час як обговорення навколо «мобільних користувачів» пов’язує його з реальним результатом. Важливо уникати надмірно спрощеної мови при обговоренні складних систем.

Нарешті, розглянемо опис концепції * end-to-end типу безпеки *. Пояснення цього комусь, хто не знайомий з tRPC, може включати в себе такі слова: “tRPC забезпечує, що кожен шматок даних - від початкового запиту до кінцевої відповіді - строго типізований. Це виключає потенційні помилки під час виконання і забезпечує набагато вищий рівень впевненості в коректності нашого API.” Фраза “строго типизований” є особливо важливою; вона підкреслює основну перевагу порівняно з традиційними підходами, де перевірка типів може бути обмежена або відсутня. Це стосується підкреслення того, що tRPC не тільки * підтримує * безпеку типів, але і * забезпечує * її по всій системі.

// Example: Illustrating type enforcement with a simplified tRPC request
// (This is conceptual - actual tRPC code would be more complex)
const requestData = {
  userId: "12345",
  name: "John Doe",
  age: 30, // Type enforced here!
};

// Assuming 'validateRequest' function checks types before processing.
// validateRequest(requestData); // Example of type validation in action

Сфокусувавшись на ясній і точній мові, розуміючи * чому * за термінологією, і використовуючи фрази, які відповідають основним принципам tRPC, не-рідні носії англійської мови можуть впевнено брати участь у технічних дискусіях і робити внесок в успішні проекти з розробки. Пам’ятайте, ефективне спілкування так само важливо, як і сам код.