TypeScript Academy · Lekcja

Komunikaty błędów w DSL na poziomie typów

Wyświetlaj użytkownikom DSL pomocne błędy kompilacji

Lekcja 4 z 413 kroki

Komunikaty błędów w DSL na poziomie typów to bezpłatna lekcja TypeScript Academy na CoddyKit. To lekcja 4 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.

Czytelne błędy w DSL-ach na poziomie typów

Najtrudniejszym elementem DSL-a na poziomie typów jest zapewnienie, aby błędy były czytelne. Surowe błędy never lub komunikaty „not assignable” wprowadzają użytkowników w błąd. Można wyświetlać opisowe komunikaty za pomocą typów błędów z oznaczeniem oraz odpowiednio skonstruowanych komunikatów never.

Problem z never

Gdy walidacja kończy się rozwiązaniem do never, kompilator wyświetla komunikat „Argument of type X is not assignable to never”, który nie wyjaśnia użytkownikowi, dlaczego wystąpił błąd. Można to zrobić lepiej.

Typy błędów z oznaczeniem

Zamiast zwykłego never należy zwrócić typ błędu o unikalnej strukturze, zawierający w swoim typie ciąg znaków z komunikatem czytelnym dla człowieka.

type TypeError<Msg extends string> = {
  readonly __error: Msg;
};

type E = TypeError<"Column 'foo' does not exist">;

Zwracanie błędów z walidacji

Walidator zwraca albo typ poprawnej wartości, albo typ błędu z oznaczeniem opisujący problem. Sprawdzenie „has a dot” jest wzorcem literału szablonowego (w rzeczywistym kodzie zapisuje się go za pomocą odwrotnych apostrofów); tutaj oznaczamy go jako HasDot.

// HasDot<S> is the backtick pattern: any text, ".", any text.

type Validate<S extends string> =
  S extends HasDot
    ? S
    : TypeError<"Path must contain a dot, e.g. user.name">;

Wymuszanie wyświetlenia błędu

Należy ograniczyć parametr tak, aby przekazanie wartości, której nie można przypisać do oznaczenia błędu, spowodowało wyświetlenie komunikatu. Typ błędu pojawi się bezpośrednio w danych wyjściowych kompilatora.

declare function path<S extends string>(
  p: Validate<S> extends TypeError<infer M> ? TypeError<M> : S
): void;

path("oops");
// Error message includes: __error: "Path must contain a dot..."

Rozróżnianie wielu błędów

Różne niepowodzenia zwracają różne komunikaty, dzięki czemu użytkownicy otrzymują konkretne wskazówki zamiast jednego ogólnego odrzucenia. HasDot to ponownie wzorzec literału szablonowego zapisywany w rzeczywistym kodzie za pomocą odwrotnych apostrofów, oznaczający „zawiera kropkę”.

type Check<S extends string> =
  S extends "" ? TypeError<"Path cannot be empty">
  : S extends HasDot ? S
  : TypeError<"Missing dot separator">;

never w innej odsłonie

Inna technika łączy pozycję wartości z literałem zawierającym komunikat, dzięki czemu można go zobaczyć po wskazaniu elementu. Należy przeciąć typ zawierający problematyczną wartość z obiektem mającym odpowiednią etykietę.

type Invalid<M extends string> = { error: M } & never;
// using never keeps it unassignable while the label hints the cause

Błędy we fluent DSL-ach

W łańcuchowym DSL-u niepoprawny następny krok powinien zwracać typ z oznaczeniem błędu zamiast poprawnego etapu, aby edytor wyświetlał komunikat dokładnie w miejscu popełnienia błędu.

interface Stage {
  // calling done() before where() yields a labeled error
  done(): TypeError<"Call .where() before .done()">;
}

Zwięzłe komunikaty

Długie typy komunikatów zwiększają objętość danych wyjściowych kompilatora i spowalniają narzędzia. Należy preferować zwięzłe, konkretne sformułowania. Jeśli nie wymaga to dużego nakładu, warto uwzględnić problematyczny token, ale należy unikać bardzo dużych interpolacji.

Testowanie błędów

Należy pisać testy na poziomie typów, które sprawdzają, czy dla znanych niepoprawnych danych wejściowych pojawia się oznaczenie błędu. Dzięki temu refaktoryzacje nie pogorszą po cichu jakości pracy programisty.

type Expect<T extends true> = T;
type _t = Expect<Validate<"oops"> extends TypeError<any> ? true : false>;

Dlaczego ma to znaczenie

DSL jest tak dobry, jak jego komunikaty o błędach. Typy błędów z oznaczeniem zamieniają niejasne błędy never w komunikaty wyjaśniające się same, znacznie poprawiając korzystanie z API na poziomie typów.

Szybkie sprawdzenie

Upewnij się, że rozumiesz komunikaty o błędach na poziomie typów.

Odpowiedz w interaktywnej lekcji

Podsumowanie

Aby DSL-e na poziomie typów były użyteczne, należy zastąpić samo never typami błędów z oznaczeniem, które zawierają czytelne komunikaty. Walidatory zwracają albo poprawny typ, albo konkretne oznaczenie błędu; ograniczanie parametrów powoduje wyświetlenie komunikatu w danych wyjściowych kompilatora. Komunikaty powinny być krótkie i przetestowane.

Bezpłatny start

Ucz się TypeScript dzięki korepetycjom AI — za darmo

Pisz i uruchamiaj kod w przeglądarce, otrzymuj natychmiastową pomoc od korepetytora AI dostępnego 24/7 i kontynuuj naukę w sieci lub w aplikacji.

Kursy: 101
Lekcje: 352

Zacznij naukę bezpłatnie Wyświetl pełny kurs

Często zadawane pytania

Czy lekcja „Komunikaty błędów w DSL na poziomie typów” jest bezpłatna?

Tak — pełny tekst „Komunikaty błędów w DSL na poziomie 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 „Komunikaty błędów w DSL na poziomie typów”?

Wyświetlaj użytkownikom DSL pomocne błędy kompilacji Ć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 4 z 4.

Ile czasu zajmuje lekcja „Komunikaty błędów w DSL na poziomie 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

Czym jest DSL na poziomie typów
Projektowanie fluent query DSL
Walidacja danych wejściowych w czasie kompilacji
Komunikaty błędów w DSL na poziomie typów

← Powrót do TypeScript Academy