TypeScript Academy · 강의

타입 수준 DSL의 오류 메시지

DSL 사용자에게 유용한 컴파일 오류를 표시합니다.

타입 수준 DSL의 오류 메시지은(는) CoddyKit의 무료 TypeScript Academy 강의입니다. 이것은 4개 중 4번째 강의입니다. 아래에서 전체 강의를 무료로 읽을 수 있으며, 내장 코드 에디터와 24/7 AI 튜터와 함께 브라우저에서 직접 실습할 수 있습니다. 이 강의는 TypeScript Academy 학습 경로의 일부이며, 진행 상황이 웹과 CoddyKit 앱에 동기화됩니다. TypeScript Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

타입 수준 DSL에서 유용한 오류 메시지

타입 수준 DSL에서 가장 어려운 부분은 실패 원인을 읽기 쉽게 만드는 것입니다. 원시적인 never 또는 "할당할 수 없음" 오류는 사용자를 혼란스럽게 합니다. 브랜딩된 오류 타입과 정교하게 만든 never 메시지를 사용하여 설명적인 오류를 표시합니다.

never의 문제점

유효성 검사가 never로 평가되어 실패하면 컴파일러는 "X 타입의 인수를 never에 할당할 수 없습니다"라고 표시하지만, 이것만으로는 사용자가 왜 실패했는지 알 수 없습니다. 더 나은 방법이 있습니다.

브랜딩된 오류 타입

일반적인 never 대신, 타입 안에 사람이 읽을 수 있는 메시지 문자열을 담은 고유한 형태의 오류 타입을 반환합니다.

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

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

유효성 검사에서 오류 반환하기

유효성 검사기는 유효한 값의 타입이나 문제를 설명하는 브랜딩된 오류 중 하나를 반환합니다. "점이 있는지" 검사는 템플릿 리터럴 패턴(실제 코드에서는 백틱)이며, 여기서는 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">;

오류가 드러나도록 만들기

오류 브랜드에 할당할 수 없는 값을 전달할 때 메시지가 표시되도록 매개변수를 제한하십시오. 오류 타입이 컴파일러 출력에 직접 나타납니다.

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..."

여러 오류 구분하기

서로 다른 실패는 서로 다른 메시지를 반환하므로, 사용자는 하나의 일반적인 거부 메시지 대신 구체적인 안내를 받습니다. HasDot은 다시 "점이 포함되어 있음"을 나타내는 백틱 템플릿 리터럴 패턴입니다.

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

색다르게 활용하는 never

또 다른 방법은 값의 위치에 리터럴 메시지를 결합하여 마우스를 올렸을 때 메시지가 표시되도록 하는 것입니다. 문제가 있는 타입과 레이블이 지정된 객체의 교집합을 만듭니다.

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

유창한 DSL의 오류

연쇄형 DSL에서는 유효하지 않은 다음 단계가 유효한 스테이지 대신 오류 브랜드가 지정된 타입을 반환하도록 하십시오. 그러면 실수가 발생한 바로 그 위치에서 편집기가 메시지를 표시합니다.

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

메시지를 짧게 유지하기

메시지 타입이 길면 컴파일러 출력이 불필요하게 커지고 도구의 속도가 느려집니다. 간결하면서도 바로 조치할 수 있는 문구를 우선하십시오. 비용이 적게 든다면 문제가 된 토큰을 포함하되, 지나치게 큰 보간은 피하십시오.

오류 테스트하기

잘못된 것으로 알려진 입력에서 오류 브랜드가 나타나는지 확인하는 타입 수준 테스트를 작성하십시오. 그러면 리팩터링으로 개발자 경험이 조용히 저하되는 일을 막을 수 있습니다.

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

중요한 이유

DSL의 품질은 오류 메시지의 품질만큼 좋습니다. 브랜딩된 오류 타입은 암호 같은 never 실패를 스스로 설명하는 메시지로 바꾸어, 타입 수준 API 사용 경험을 크게 향상합니다.

빠른 확인

타입 수준 오류 메시지에 대한 이해도를 확인하십시오.

복습

타입 수준 DSL을 사용하기 쉽게 만들려면 단순한 never 대신 읽기 쉬운 메시지를 포함하는 브랜딩된 오류 타입을 사용하십시오. 유효성 검사기는 유효한 타입이나 구체적인 오류 브랜드 중 하나를 반환하고, 매개변수를 제한하면 컴파일러 출력에 메시지가 나타납니다. 메시지는 짧게 유지하고 테스트하십시오.

자주 묻는 질문

“타입 수준 DSL의 오류 메시지” 강의는 무료인가요?

네 — “타입 수준 DSL의 오류 메시지” 전체 내용을 이 웹사이트에서 무료로 읽을 수 있습니다. 인터랙티브하게 실습하려면(내장 코드 에디터와 24/7 AI 튜터), CoddyKit PRO로 업그레이드하면 TypeScript Academy 강의 전체를 잠금 해제할 수 있습니다. TypeScript Academy 강의에는 총 4개의 강의가 포함되어 있습니다.

“타입 수준 DSL의 오류 메시지”에서 뭘 배우나요?

DSL 사용자에게 유용한 컴파일 오류를 표시합니다. 브라우저에서 직접 실행하는 실습 코드로 TypeScript Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

TypeScript Academy을(를) 시작하는 데 경험이 필요한가요?

사전 경험은 필요하지 않습니다. CoddyKit의 TypeScript Academy은(는) 초급자부터 고급 학습자까지를 위해 구성되어 있으므로, 여기서 시작하거나 처음부터 시작할 수 있으며 자신의 속도대로 진행할 수 있습니다. 이것은 4개 중 4번째 강의입니다.

“타입 수준 DSL의 오류 메시지” 강의는 얼마나 걸리나요?

대부분의 CoddyKit 강의는 약 5~10분이 소요됩니다. 각 강의는 간결하고 인터랙티브하여 꾸준한 진행이 가능하며, 웹과 앱에서 중단한 부분부터 바로 시작할 수 있습니다.

이 TypeScript Academy 강의에서 코드를 작성하고 실행할 수 있나요?

네. 모든 TypeScript Academy 강의에는 내장 코드 에디터가 포함되어 있으므로, 브라우저에서 바로 실제 코드를 작성하고 실행한 후 즉시 AI 피드백을 받을 수 있습니다 — 로컬 설정이 필요 없습니다.

이 강의의 모든 강의

← TypeScript Academy(으)로 돌아가기