Практычныя нататкі: сінхранізацыя тыпаў фронтэнду і бэкэнду ў TypeScript
Практычны разбор тэмы «сінхранізацыя тыпаў фронтэнду і бэкэнду ў TypeScript»: кантракты, праверкі і гатовыя фрагменты кода для каманд, якія ўкараняюць гэты падыход.
Крыніцы: Keeping Frontend and Backend Types in Sync with Typescript Magic
Існавайце гэта як перапрацоўку ідэй з артыкула “Зберагчыце тыпы фронтэнду і бэкэнду сінхроннымі за дапамогою Typescript” для аператараў: чыстыя этапы, арганізаваныя блакі коду і прыметкі па восстанавленню, якія застаюцца пасля перадачы.
Баг без стэк-трэйсу
Баг, які існуе на певным этапе, найэфектывнейшаў калі яго розглядаць як вімерную характэрыстыку. Запісайце адна ідэальная транскрыпцыю, адзін прыклад неудачы і прыметкі па атрыбутаванню назад да пачатковага стану пры розшырэнні масштаба. Запісвайце часы выканання і косты токеноў або запытаў разам з функцыйнальнымі рэзультатамі. Відразлівае прадставленне костаў запобегае неспакойным рашчыткам, калі працэс пераходзіць з дэмаверсіі ў спяльныя сераўысы. Робіце працэс рэндарування дышучым і атрыбутавайце дорогія працэсы вырахунку пасля меравання, толькі праз мемоізацыю. Неранняя мемоізацыя можа сховаць багі з застарэлымі атрыбутамі.
// backend/src/topics/topics.service.ts
async findAll(): Promise<TopicRow[]> {
return this.prisma.topic.findMany({ select: TOPIC_SELECT });
}
// frontend/src/types.ts
export interface TopicRow {
id: string;
code: string;
requiresKey: boolean;
// ...
}
Чаму гэта стало трагічным
Што стосуецца прычыны, чаму сітуацыя стала трагічной, то ёй лепшае падходжэнне — расследаваць яе як мерыемую велічыну. Запісаць адна ідэальная версія, адзін прыклад неудачы і прыметкі па поверненню да попярэдней версіі прычаму расшырэння масштаба. Хавайце конфігурацыю пазначкай за межамі коду прыемленае. Файлы сяродавішняй асяроддзя, храненні секрэтных даных і флагі функцый павінны знаходзіцца ў адном месцы, куды аператары можаць пераглядаць без неабяжнага чытання всіх дадзеных. Стараўцесь, каб працэс атрыбутавання дадзеных быў дышацкі, а складныя вычысленні выпраўляць праз мемаізацыю толькі пасля ўжо здабытых мераў. Неранняя мемаізацыя можа сховаць багі, вызваные застарэлымі дадзеннямі.
Ідэя
Этап ідэі працюе найкрашча, калі яго розглядаць як вімерную плошчу. Запісаце адна ідэальная версія, адзін прыклад неудачы і запіс працэў па адвярненню перш чым расшырваць масштаб. Дакументаваце як успішны, так і варыянт вяселення працэў. Перапрыбуткі, людзкія контралі і обработка некорэктных паведамленняў ёсць часткай продукту, а не пасляднім дапрацоўкам. Робіце працэс генеравання дакументаў недорогім і адкладайце дорогія працэсы выведання толькі пасля вімеравання. Недакладная мемаізацыя можа сховаць багі, зв’язаныя з застарэлымі данымі.
// backend/contract/assert.ts
/** The wire shape of a server value: JSON.stringify turns Date into string. */
export type Jsonify<T> = T extends Date
? string
: T extends (infer U)[]
? Jsonify<U>[]
: T extends object
? { [K in keyof T]: Jsonify<T[K]> }
: T;
/** Invariant (not merely assignable) equality - catches widened optionals. */
export type Equal<A, B> =
(<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2)
? true
: false;
export type Expect<T extends true> = T;
/** The element type of a service method that resolves to an array. */
export type RowOf<T> = Jsonify<Awaited<T>> extends (infer U)[] ? U : never;
/** The resolved wire shape of a service method. */
export type ResultOf<T> = Jsonify<Awaited<T>>;
/** The row type of a paginated `{ rows, total }` service method. */
export type PagedRowOf<T> =
Jsonify<Awaited<T>> extends { rows: (infer U)[] } ? U : never;
// backend/contract/api-contract.ts
import type { Equal, Expect, PagedRowOf, RowOf } from './assert';
import type { TopicsService } from '../src/topics/topics.service';
import type { ContactRequestsService } from '../src/contact-requests/contact-requests.service';
import type { TopicRow, ContactRequestRow } from '../../frontend/src/types';
// GET /topics
export type _Topics = Expect<
Equal<RowOf<ReturnType<TopicsService['findAll']>>, TopicRow>
>;
// GET /contact-requests (paginated)
export type _ContactRequests = Expect<
Equal<PagedRowOf<ReturnType<ContactRequestsService['findAll']>>, ContactRequestRow>
>;
Магія падзеў пад час набору тэксту, пояснена
Магія кэліграфіі, якая адкладаецца на стадзіі рэалізацыі, працуе наяўней калі яе спрыяваць як мерыемую велічыну. Запісаце адны ідэальны прыклад, адну справу з бягам і прыметку па вярнэнню да пачатковага стану пры расшырэнні масштаба. Валіце вялікія, складныя скрыпты на карысць маленькіх, тэставаных елементаў. Калі якісь крок не выйшоў, прычына бягу должна вказываць на адну конкрэтную адпаведальнасць, а не на заплутаны ланцужок задач. Робіце працэс генеравання тэксту простым, а дорогія працэсы вырахоўвання застаўляйце пасля меравання, толькі з вікорыстоўваннем мемаізацыі. Нерэшаная мемаізацыя можа закрыць відгледы багоў у старых даных.
export type _Topics = Expect<
Equal<RowOf<ReturnType<TopicsService['findAll']>>, TopicRow>
>;
type Equal<A, B> = A extends B ? (B extends A ? true : false) : false; // too loose
(<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2
export type RowOf<T> = Jsonify<Awaited<T>> extends (infer U)[] ? U : never;
Праўяце яго да методу, а не да запыту
Працэс падзеўкі даных на стадыю працюе найэфектывней, калі яго спрыяваць як мерымае паверхне. Зберагачыце адны ідэальны прыклад працы, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расшырваць масштабы. Спрыяйце гэтай стадыўцы як кантракту межа вхіднымі дадзеннямі і перакананымі выходнымі рэзультатамі. Даўце назвы артыфактам, задаць крытэрыя успеху і адмовіцеся ад тыхняга частковага завершэння без паведамлення. Робіце працэс генеравання дадзэнняў дышачым, а дорогія працэсы вырахоўвання пераводзіце пасля мэмуязыі, толькі пасля ўсёх мераванняў. Нерэшаная мэмуязыя можа закрыць багі, зв’язаныя з застарэлымі дадзеннямі. Працэс падзеўкі даных на стадыю працюе найэфектывней, калі яго спрыяваць як мерымае паверхне. Зберагачыце адны ідэальны прыклад працы, адзін прыклад неудачы і запіс пра вярнэнне да пачатковага стану перш чым расшырваць масштабы. Храніце настройкі за межамі коду прыемлівача. Файлы сяродавішча, хранільнікі секрэтных дадзенняў і флагі функцый должны знаходзіцца ў аднам месцы, куда аператары можу аўдытаваць іх без неабходнасці чытаць весь структурны лямбда.
// Wrong: misses everything the method does after the query
Equal<Jsonify<TopicSelectResult>, TopicRow>
// Right: whatever the method actually resolves to
Equal<RowOf<ReturnType<TopicsService['findAll']>>, TopicRow>
Установка працы
У стадыі «Забезпечыць працу» неабяжна практычна вказаць інпуты, адміністратара крока і крэтэрыя завершэння пры перадзеіснавленні коду. Аператары должны магчымаць перзапуск крока з вядомай точкі контролю, не падозрываючы схованы стан. Неабяжна аддокументаваць як шлях успеху, так і шлях вярнення. Перапрыбуткі, людзкіе перакрыцця і апрацоўка некорэктных паведамленняў ёсць часткай продукту, а не чымсь, што дадаецца пазней. Стан неабяжна размешчаць разам з компонентам, які керуе мутацыямі. Перанесенне усяго у глобальны хранільнік ускладняе выяўленне багоў з часавымі аспектамі.
// backend/tsconfig.contract.json
{
"extends": "./tsconfig.json",
"compilerOptions": {
"noEmit": true,
"rootDir": "..", // program spans both packages
"module": "preserve",
"moduleResolution": "bundler" // resolve the way the frontend's bundler does
},
"include": ["src/**/*", "contract/**/*", "../frontend/src/types.ts"]
}
{ "scripts": { "check:contract": "tsc -p tsconfig.contract.json" } }
Чытанне пра бягучую адмову
Для этапы адміністрування збоў неабходна пазначыць вхідныя даны, адпаведальнага за крок і крытэрыя завершэння пры перадзеіснаванні коду. Аператары должны магчымае перадзеіснаваць крок з вядомай точкі контролю, не прабуючы спадарожваць схованы стан. Валідзіце маленькія, тэставаныя елементы замест большых скрыптов. Калі крок не выконваецца, прычына збою павінна вказываць на адзін конкрэтны элемент, а не на заплутаны ланцюг задач. Размешчайце стан разам з компонентам, які керуея змянамі. Размешчэнне всего ў глобальным хранільніку ускладняе выяўленне багоў, зв’язаных з часама выканання.
type P1 = A extends B ? true : false; // false => server is narrower / has extra
type P2 = B extends A ? true : false; // false => frontend is wider
type Extra = Exclude<keyof A, keyof B>; // fields the server sends, frontend lacks
type Missing = Exclude<keyof B, keyof A>; // fields the frontend invented
Якая ў гэтага цена, і дзе гэта не дасягае
Для раздэла «Калкулатацыя костоў і стадыя» неабходна прадзефінаваць вхідныя даны, адпаведальную за шаг і крэтыры завершэння пры змяне коду. Аперацыйныя працавнікі должны магчымае перайсці на выкананне шага з вядомага пункта контролю, не спрабоўваючы здагадвацца пра схованы стан. Спрыяйце таму, каб гэтая стадыя была схожа на контракт межа вхіднымі данымі і перакананымі выходнымі рэзультатамі. Дайце назвы артыфактам, прадзефінаваць крэтыры успеху і не прымайце часткова завершаныя рэзультаты без паведамлення. Размешчайце стан разам з компонентам, які адпаведальны за яго змяну. Размешчэнне всего ў глобальным хранільніку ускладняе выяўленне багоў, зв’язаных з часам выканання. Для раздэла «Калкулатацыя костоў і стадыя» неабходна прадзефінаваць вхідныя даны, адпаведальную за шаг і крэтыры завершэння пры змяне коду. Аперацыйныя працавнікі должны магчымае перайсці на выкананне шага з вядомага пункта контролю, не спрабоўваючы здагадвацца пра схованы стан. Зберагачыце настройкі параду коду прыкладнення. Файлы сераўіса, хранільнікі секрэтных дадзеных і флагі функцый должны знаходзіцца ў аднам месцы, якое працавнікі можу аўдытаваць, не чытаючы весь структураны код.
Галоўная мысль
Калі працуеце над стадыяй «Галоўная мысль», спачатку запішыце умовы вікорыстання: неабходныя даны, сігнал успеху і тое, што вядзець да частковага невыпання. Такі спіс дапамагае заліцварыць пазнейшыя змены ў кодзе.
Чэрніця для эксплуатацыі
Калі працуеце над стадыяй «Чэрніця для эксплуатацыі», спачатку запішыце умовы вікорыстання: неабходныя даны, сігнал успеху і тое, што вядзець да частковага невыпання. Такі спіс дапамагае заліцварыць пазнейшыя змены ў кодзе.
Запісвайце час выканання аперацый, а таксу токенаў чы запітоў разам з функцыйнальнымі рэзултатамі. Відразы цены з самага пачатку запобегае неспакойным рахункам, калі працэс пераходзіць з дэмаверсіі ў спяльныя сераўры.
Спрыткія эфекты трэба спрацоўваць як сінхронізацыю з зямным светам, а не як замену для значэнняў, якія вылучаюцца пад час адрасавання.
Фіксуйце версіі залежнасцяў і запішыце хэш адпрацоўванага зображэння, якое выкарыстоўваўся для дамаў. Возможнасць павторэння важлівей, чым традыцыйныя знаёмства.
Канфігурацыю трэба зберагаць паза кодам прыкладнай програмы. Файлы сераўнавання, хранільнікі секрэтных дадзенняў і флагі функцыйяй должны знаходзіцца ў аднам месцы, якое аператары можаць пераглядаць без неабяжнай чытанняў усіх элементаў структуры.
Спрыткія эфекты трэба спрацоўваць як сінхронізацыю з зямным светам, а не як замену для значэнняў, якія вылучаюцца пад час адрасавання.
Перш чым пераходзіць на новую структуру, заморажуйце версіі, зафіксуйце крытычны варыант дадзенняў для ключовых частак і параканайце крокі для вярнення да пачатковага стану. У спільных сераўнах неабходны ліміты швайнасці, пераказы наявнасці рэсурсаў і чысткі власнік для змены секрэтных дадзенняў. Валіце простую надзейнасць працы над крэатывнымі, але разовымі дамаў.
Запіскі для пакета 99a16b87e27d: не класты ключы прадаўцоў у рэпазітарыю, задаць максымальны ліміт токена на сесію, а таксама зберагчы транскрыпціі праза фіксатуры для ацэнкі, каб пазнейшыя замены мадэляў заставаліся пораўнанымі.