tRPC v11: TypeScript API Vocabulary for Full-Stack Engineers (англійською)

tRPC надає вам змогу створювати повністю безпечні API без написання окремої схеми або запуску генератора коду. Версія 11 ввела кілька важливих нових шаблонів, включаючи підтримку FormData і тіснішу інтеграцію з TanStack Query. Якщо ви працюєте над повноцінними проектами TypeScript, словник, який ви знайдете у цій статті, допоможе вам розширити ваші здібності до обговорення tRPC англійською мовою під час перегляду коду, під час зустрічей команди і технічних інтерв’ ю.

---

Основні принципи та процедури

** router ** — об’ єкт верхнього рівня у tRPC, який групує пов’ язані процедури разом, подібно до контролера у MVC- фреймворках; маршрутизатори можна вкладати, щоб створити деревоподібний API.

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

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

“Процедура отримання профілю користувача визначена як запит, оскільки вона виконує лише читання з бази даних.”

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

• “Ми додаємо об’ єкт сеансу до контексту у функції createContext, щоб кожна процедура могла перевірити, хто робить запит.” *

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

• “Проміжне програмне забезпечення isAuthenticated повертає помилку UNAUTHORIZED, якщо у контексті немає користувача, що захищає всі процедури, які вимагають сеансу з входом у систему.” *

---

Вхід, вихід і перевірка

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

• “Перевірка введення відхилила запит, оскільки у полі електронної пошти не було вказано потрібний формат, що зменшило кількість поїздок у обидві сторони з бази даних.” *

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

• “Ми додали схему виводу до процедури користувача, щоб гарантувати, що геш пароля ніколи не буде включено до відповіді API.” *

** Zod schema ** — схема бібліотеки перевірки TypeScript- first, яку використовують для визначення форми і обмежень вхідних і вихідних даних процедури tRPC.

• “Схема Zod для вводу create- order вимагає додатного цілого числа кількості і непорожнього рядка ідентифікатора продукту.” *

---

Клієнт-серверна інтеграція

** useQuery ** — гачок TanStack Query, який обгортає tRPC, щоб ви могли викликати процедуру запиту з компонента React з автоматичним кешуванням і отриманням у фоновому режимі.

• “Ми замінили виклик отримання на сторінці профілю викликом useQuery, щоб дані було кешовано у всіх навігаціях.” *

** useMutation ** — засіб запитів TanStack обгортає tRPC для виклику процедур мутації, повертаючи функцію mutate разом зі станами завантаження і помилки.

• “Форма викликає useMutation під час надсилання, і ми показуємо спинер, поки мутація перебуває у стані очікування.” *

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

“Підвищення до адаптера TanStack Query в v11 вилучив близько 200 рядків вручну отримати обгортки коду з нашої кодової бази.”

---

11-та піхотна дивізія

** Процедура FormData ** — новий шаблон у tRPC v11, який надає змогу процедурі приймати стандартний об’ єкт HTML FormData як вхідний, що дозволяє вивантаження файлів і надсилання форм.

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

** http: // batchstreamlink. com ** — посилання клієнта tRPC, яке перетворює декілька пакетних викликів процедур у один HTTP- запит і передає потоком відповіді, коли кожен з них буде розв’ язано, зменшуючи затримку.

• “Перехід на httpBatchStreamLink означав, що сторінка завантажувалася швидше, оскільки результати окремих процедур з’ являлися одразу після їх готовності.” *

** inferRouterInputs і inferRouterOutputs ** — типи інструментів TypeScript, експортовані tRPC, які надають вам змогу видобувати типи вводу і виводу ваших процедур без дублювання визначень схеми.

• “Ми використовували inferRouterOutputs для введення даних у наш компонент спільної карти без прямого імпорту схеми Zod.” *

---

Practice

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

Mastering the T: A Practical Guide to Building with tRPC v11 (англійською)

Погляньмо правді в очі — розуміння концепцій API не тільки про знання TypeScript. Це глибоко пов’язано з тим, як ви повідомляєте свої рішення щодо проектування, співпрацюєте з іншими інженерами і документуєте свою роботу. Цей розділ зосереджений на перекладі технічних знань на ясну, професійну англійську, особливо в контексті tRPC v11. Ми дослідимо термінологію, важливу для ефективного спілкування під час перегляду коду, обговорення Slack і описів PR - ключовий елемент в забезпеченні гладкої співпраці на повноцінних проектах.

Поширеним розчаруванням при впровадженні нових технологій є сприйнята складність. Часто розробники борються, щоб сформулювати * чому * щось працює або як це вписується в більш широку систему. Ясна, коротка мова зменшує неоднозначність і прискорює розуміння. Подумайте про опис стратегії маршрутизації вашого API - простого зауваження “ми використовуємо маршрутизатори” недостатньо. Вам слід пояснити, * як* визначено ці маршрути, які дані вони обробляють і як вони взаємодіють з іншими компонентами. Ця ясність відображається в добре написаних описах PR і вмілих коментарях до перегляду коду.

Наприклад, уявіть ситуацію, коли ви пропонуєте нову функцію середовища для автентифікації. Замість того, щоб просто сказати «це середнє програмне забезпечення обробляє аутентифікацію», хорошим описом буде: «Вреалізовано нове середнє програмне забезпечення verifyToken, яке використовує перевірку JWT проти AuthService, забезпечуючи доступ до процедури /users/:id тільки автентифікованим запитам». Зауважте деталі - це вказує * як * функціонує середнє програмне забезпечення, посилаючись на зовнішні служби і чітко визначаючи обсяг його відповідальності. Цей рівень специфічності є важливим для рецензентів, щоб швидко зрозуміти ваші наміри і оцінити потенційний вплив.

Крім того, ефективне спілкування виходить за межі окремих компонентів. При обговоренні інтеграції TanStack Query з tRPC, його оформлення як «оптимізації стратегій отримання даних» або «зменшення непотрібних викликів API» передає стратегічне розуміння, що виходить за рамки просто технічної реалізації. Ця здатність з’ єднувати різні елементи у вашій архітектурі є ключем до демонстрації справжнього майстерності.

Давайте проілюструємо це на простому прикладі коду:

// Example Middleware - Simple Rate Limiting
import { RateLimiterMiddleware } from './rateLimit';

const rateLimiter = new RateLimiterMiddleware({
  key: 'api/users',
  limit: 10,
  windowMs: 60000 // 1 minute
});

export default rateLimiter;

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

Врешті-решт, оволодіння словником tRPC є лише частиною рівняння. Це про впевнене вираження ваших ідей і значний внесок в загальну технічну стратегію команди - перетворення складного коду в чітке спілкування.