Практические советы: синхронизация типов фронтенда и бэкенда с 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: не включайте ключи поставщиков в репозиторий, установите лимит токенов на сессию и храните транскрипции рядом с фиксами для оценки, чтобы последующие замены моделей оставались сопоставимыми.