TypeScript Academy · Lekcja

Strategia pakietu współdzielonych typów

Utwórz dedykowany pakiet typów używany w całym monorepo.

Strategia pakietu współdzielonych typów to bezpłatna lekcja TypeScript Academy na CoddyKit. To lekcja 3 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej TypeScript Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs TypeScript Academy zawiera 4 lekcji w sumie.

Dlaczego warto mieć współdzielony pakiet typów

Współdzielenie typów między frontendem a backendem eliminuje rozbieżności między kontraktami API. Jedno źródło prawdy oznacza błędy kompilacji, gdy zmienia się struktura API.

// packages/types/src/index.ts
export interface User { id: string; name: string; email: string; }
export interface ApiResponse<T> { data: T; error?: string; }

Struktura pakietu

Pakiet typów powinien być minimalny: powinien zawierać wyłącznie eksporty typów i nie mieć logiki wykonywanej w czasie działania. Dzięki temu nie wywołuje efektów ubocznych i można go skutecznie optymalizować za pomocą tree shaking.

packages/types/
├── src/
│   ├── index.ts      # re-exports all
│   ├── user.ts
│   ├── product.ts
│   └── api.ts
├── tsconfig.json
└── package.json

tsconfig dla pakietu typów

Należy włączyć emitDeclarationOnly, aby nie generować kodu JavaScript — tylko pliki .d.ts, do których odwołują się odbiorcy pakietu.

{
  "compilerOptions": {
    "composite": true,
    "declaration": true,
    "emitDeclarationOnly": true,
    "outDir": "./dist",
    "rootDir": "./src"
  }
}

Korzystanie z pakietu typów

Należy dodać odwołanie do pakietu typów zarówno w API, jak i w aplikacji webowej, a typy importować za pomocą import type, aby uniknąć narzutu w czasie działania.

import type { User, ApiResponse } from "@myapp/types";

async function getUser(id: string): Promise<ApiResponse<User>> {
  // ...
}

Zapewnianie bezpieczeństwa serializacji typów

Typy współdzielone między klientem a serwerem powinny zawierać wyłącznie wartości możliwe do serializacji do JSON. Należy unikać obiektów Date — zamiast nich używać typu string w formacie ISO.

// Good: serialization-safe
interface Event { id: string; createdAt: string; /* ISO date */ }
// Bad: Date is not JSON-serializable
interface Event { id: string; createdAt: Date; }

Wersjonowanie pakietu typów

Pakiet typów należy wersjonować zgodnie z semver. Zmiana powodująca niezgodność, taka jak usunięcie lub zmiana nazwy pola, wymaga zwiększenia wersji major.

# Breaking change: major bump
npm version major
# Adding optional fields: minor bump
npm version minor

Generowanie typów z OpenAPI

Pakiet typów można automatycznie generować ze specyfikacji OpenAPI za pomocą openapi-typescript. Dzięki temu typy zawsze odpowiadają backendowi.

npx openapi-typescript ./api/openapi.yaml -o ./packages/types/src/api.ts

Używanie Zod do typów czasu działania i kompilacji

Należy definiować typy za pomocą schematów Zod i wyprowadzać z nich typy TypeScript. Zarówno walidacja w czasie działania, jak i typy statyczne pochodzą z tego samego źródła.

import { z } from "zod";
export const UserSchema = z.object({ id: z.string(), name: z.string() });
export type User = z.infer<typeof UserSchema>;

Unikanie zależności cyklicznych

Pakiet typów nie powinien importować niczego z innych pakietów workspace, aby zapobiegać cyklicznym łańcuchom zależności. Należy utrzymywać go jako liść grafu zależności.

// types/ should not import from ui/ or api/
// ui/ and api/ both import from types/

Testowanie poprawności typów

Należy użyć tsd do pisania asercji na poziomie typów, które sprawdzają, czy współdzielone typy odpowiadają oczekiwaniom.

import { expectType } from "tsd";
import type { User } from "@myapp/types";
expectType<User>({ id: "1", name: "Alice", email: "a@b.com" });

Podsumowanie: strategia współdzielonych typów

Współdzielony pakiet typów eliminuje rozbieżności w API: generuje wyłącznie deklaracje, zawiera typy możliwe do serializacji do JSON, jest wersjonowany zgodnie z semver, może być automatycznie generowany z OpenAPI i testowany za pomocą tsd.

Szybkie sprawdzenie

Dlaczego we współdzielonych typach API należy używać string zamiast Date?

Czego się Państwo nauczyli

Współdzielony pakiet typów jest jednym źródłem prawdy dla kontraktów API. Należy ograniczyć go do deklaracji, zadbać o bezpieczeństwo serializacji do JSON, wersjonować zgodnie z semver i opcjonalnie generować z OpenAPI, aby wyeliminować rozbieżności między frontendem a backendem.

Często zadawane pytania

Czy lekcja „Strategia pakietu współdzielonych typów” jest bezpłatna?

Tak — pełny tekst „Strategia pakietu współdzielonych typów” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu TypeScript Academy, przejdź na CoddyKit PRO. Kurs TypeScript Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „Strategia pakietu współdzielonych typów”?

Utwórz dedykowany pakiet typów używany w całym monorepo. Ćwiczysz TypeScript Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć TypeScript Academy?

Nie wymagamy żadnego doświadczenia. TypeScript Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 3 z 4.

Ile czasu zajmuje lekcja „Strategia pakietu współdzielonych typów”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji TypeScript Academy?

Tak. Każda lekcja TypeScript Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

Objaśnienie referencji projektów TypeScript
Obszary robocze pnpm z TypeScript
Strategia pakietu współdzielonych typów
Kompilacje przyrostowe i pamięć podręczna w monorepo

← Powrót do TypeScript Academy