Strona główna / Artykuły

Wskazówki praktyczne: Utrzymywanie synchronizacji typów frontendu i backendu za pomocą TypeScript

Krok po kroku praktyczne wskazówki: utrzymywanie synchronizacji typów frontendu i backendu z TypeScriptem – umowy, sprawdzania oraz gotowe miejsca na kod dla zespołów wdrażających ten wzorzec.

Wydawca: REACTAPP.TOP7 min czytania1637 słów

Źródła: Keeping Frontend and Backend Types in Sync with Typescript Magic

Niech to służy jako wersja przeznaczona dla operatorów, zawierająca zasady przedstawione w artykule „Utrzymywanie synchronizacji typów frontendu i backendu za pomocą magii TypeScript”: wyraźne etapy, uporządkowane sekcje kodu oraz notatki naprawcze, które przetrwają przeniesienie obowiązków.

Błąd bez śladu wywołania

Błąd, który występuje na określonym etapie, funkcjonuje najlepiej, gdy traktowany jest jako mierzalna zmienna. Zanim rozszerzysz zakres pracy, zapisz jeden idealny przykład działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian. Zapisz również czas wykonywania operacji oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega nieoczekiwanym rachunkom, gdy przechodzi się z środowiska demonstracyjnego do wspólnych środowisk. Utrzymuj prostotę procesu renderowania i odkładaj kosztowne operacje na później, dopiero po ich zmierzeniu. Przedwczesne stosowanie mechanizmów memoizacji może ukrywać błędy związane ze starymi wartościami propów.

// 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;
  // ...
}

Dlaczego sprawa stała się pilna

Sposób traktowania tego etapu jako mierzalnej powierzchni sprawia, że działa najlepiej. Zanim rozszerzysz zakres, zapisz jeden idealny przykład działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian. Trzymaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny haseł oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności przeglądania całej struktury. Utrzymuj koszty renderowania na niskim poziomie i odkładaj drogie operacje obliczeniowe na później, dopiero po ich zmierzeniu. Przedwczesne stosowanie mechanizmów memoizacji może ukrywać błędy związane ze starymi wartościami.

Idea

Faza koncepcji działa najlepiej, gdy traktuje się ją jako mierzalną powierzchnię. Zapisz jeden idealny przypadek działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Zdokumentuj zarówno ścieżkę prawidłowego działania, jak i ścieżkę naprawczą. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości błędowych stanowią część produktu, a nie elementy dodawane później. Utrzymuj koszty renderowania na niskim poziomie i odkładaj drogie operacje wywodzenia na później, tylko po dokonaniu pomiarów. Przedwczesne stosowanie mechanizmów memoizacji może ukrywać błędy związane ze starymi danymi.

// 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>
>;

Cuda pisania, wyjaśnione

Magia pisania kodu wyjaśniona na tym etapie działa najlepiej, gdy traktuje się ją jako coś mierzalnego. Zapisz jeden udany przykład, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia zmian, zanim rozszerzysz zakres pracy. Wolno preferować małe, testowalne jednostki zamiast rozbudowanych skryptów. Gdy jakiś krok zawiedzie, awaria powinna wskazywać na konkretną odpowiedzialność, a nie na skomplikowany łańcuch operacji. Utrzymuj koszty renderowania na niskim poziomie i odkładaj drogie operacje wyliczeniowe na później, dopiero po ich zmierzeniu. Przedwczesne stosowanie mechanizmów memoizacji może ukrywać błędy związane ze starymi danymi.

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;

Podłącz to do metody, a nie do zapytania

Najlepiej funkcjonuje proces przesyłania danych na scenę, gdy traktuje się go jako mierzalną powierzchnię. Zapisz jeden idealny przykład działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Traktuj tę fazę jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nadaj nazwy poszczególnym elementom, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadań. Utrzymuj koszty renderowania na niskim poziomie i odkładaj drogie operacje wywodzenia na później, dopiero po dokonaniu pomiarów. Przedwczesne stosowanie mechanizmów memoizacji może ukrywać błędy związane ze starymi danymi. Najlepiej funkcjonuje proces przesyłania danych na scenę, gdy traktuje się go jako mierzalną powierzchnię. Zapisz jeden idealny przykład działania, jeden przypadek awarii oraz notatkę dotyczącą cofnięcia działań, zanim rozszerzysz zakres. Utrzymuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury.

// 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>

Zapewnienie jego działania

W fazie „Udrożnienia działania” należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok na podstawie znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Należy udokumentować zarówno prawidłowy przebieg procesu, jak i ścieżkę naprawczą. Próby ponownych działań, kontrolne punkty ludzkie oraz obsługa wiadomości błędnych stanowią część produktu, a nie elementy dodawane później w celu udoskonalenia. Stan powinien być przechowywany razem z komponentem, który odpowiada za jego zmianę. Umieszczanie wszystkiego w globalnym magazynie utrudnia wykrycie błędów związanych z czasem wykonywania operacji.

// 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" } }

Odczytywanie błędu

W przypadku etapu związанego z błędem podczas odczytu należy najpierw określić dane wejściowe, osobę odpowiedzialną za ten krok oraz kryteria zakończenia przed modyfikacją kodu. Operatorzy powinni móc ponownie uruchomić ten krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Lepiej używać małych, łatwych do przetestowania jednostek niż rozbudowanych skryptów. Gdy krok zawodzi, błąd powinien wskazywać na konkretną odpowiedzialność, a nie na skomplikowaną strukturę przepływu. Stan powinien być przechowywany razem z komponentem, który odpowiada za jego modyfikację. Umieszczanie wszystkiego w globalnym magazynie utrudnia wykrycie błędów związanych z czasem wykonywania operacji.

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

Jakie to koszty i gdzie to nie działa

Dla etapu „Ile to kosztuje” należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić ten krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Traktuj ten etap jako umowę pomiędzy danymi wejściowymi a zweryfikowanymi wynikami. Nazwij poszczególne elementy, zdefiniuj kryteria sukcesu i odrzuć ciche, częściowe ukończenie zadania. Umieść stan w tym samym komponencie, który odpowiada za jego modyfikację. Umieszczanie wszystkiego w globalnym magazynie utrudnia wykrycie błędów związanych z czasem wykonywania operacji. Dla etapu „Ile to kosztuje” należy zdefiniować dane wejściowe, osobę odpowiedzialną za dany krok oraz kryteria zakończenia przed zmianą kodu. Operatorzy powinni móc ponownie uruchomić ten krok od znanego punktu kontrolnego, bez konieczności zgadywania ukrytego stanu. Przechowuj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny tajnych danych oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności czytania całej struktury aplikacji.

Główny punkt

Podczas prace nad etapem „Główny punkt”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie. Zdokumentuj zarówno prawidłowy przebieg działania, jak i ścieżkę naprawczą. Próby ponowne, kontrola przez ludzi oraz obsługa wiadomości błędowych są częścią produktu, a nie elementem dodatkowej optymalizacji. Traktuj efekty jako synchronizację z otaczającym światem, a nie jako zamiennik wartości wyliczanych podczas renderowania.

Podczas prace nad etapem „Lista kontrolna operacyjna”, najpierw zapisz umowę: wymagane dane wejściowe, sygnał sukcesu oraz to, co dzieje się w przypadku częściowego niepowodzenia. Taka lista kontrolna zapewnia uczciwość późniejszych zmian w kodzie.

Zapisz czasy wykonywania operacji oraz koszt tokenów lub zapytań obok wyników funkcjonalnych. Wczesna widoczność kosztów zapobiega niespodziewanym rachunkom, gdy ścieżka przechodzi z środowiska demonstracyjnego do wspólnych środowisk.

Traktuj efekty jako synchronizację z otaczającym światem, a nie jako zamiennik wartości wyliczanych podczas renderowania.

Zamroź wersje zależności i zapisz digest obrazu, który uruchomił demo. Powtarzalność jest lepsza od wiedzy praktycznej nabytej bezpośrednio.

Zachowaj konfigurację poza kodem aplikacji. Pliki środowiskowe, magazyny sekretów oraz flagi funkcjonalne powinny znajdować się w jednym miejscu, które operatorzy mogą sprawdzić bez konieczności analizowania całej struktury.

Traktuj efekty jako synchronizację z otaczającym światem, a nie jako zamiennik wartości wyliczanych podczas renderowania.

Zanim zastosujesz nową architekturę, zamroź wersje, stwórz dokładny zapis procesu dla kluczowej ścieżki oraz potwierdź kroki odwracające zmiany. Środowiska współdzielone wymagają ograniczeń szybkości, weryfikacji dostępu oraz jasno określonego właściciela odpowiedzialnego za rotację sekretów. Wolisz nudną niezawodność od pomysłowych, jednorazowych demonstracji.

Uwagi dotyczące partii 99a16b87e27d: unikaj umieszczania kluczy dostawcy w repozytorium, ustaw ograniczenie liczby tokenów na sesję oraz przechowuj transkrypcje obok plików testowych, aby późniejsze zmiany modeli pozostały porównywalne.

Literatura pokrewna

  • Notatki praktyczne: AI Agents kontra tradycyjne aplikacje backendowe – co tak naprawdę jest — Szczegółowy przewodnik po Notatkach praktycznych: AI Agents kontra tradycyjne aplikacje backendowe – co tak naprawdę jest: umowy, sprawdzania oraz miejsca na kod do wklejenia dla zespołów wdrażających ten wzorzec.
  • Notatki praktyczne: MCP to po prostu RPC z lepszą promocją: perspektywa inżyniera backendowego — Szczegółowy przewodnik po Notatkach praktycznych: MCP to po prostu RPC z lepszą promocją: perspektywa inżyniera backendowego: umowy, sprawdzania oraz miejsca na kod do wklejenia dla zespołów wdrażających ten wzorzec.