TypeScript Academy · 강의

유창한 쿼리 DSL 설계

연결 가능하고 자체적으로 검증하는 쿼리 API를 구축합니다.

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

플루언트 쿼리 DSL 설계하기

각 단계가 반환 타입을 통해 허용되는 다음 단계를 더 구체화하는 연결 가능한 쿼리 DSL을 설계합니다. 결과는 SQL처럼 읽히며 잘못된 순서는 컴파일 시점에 거부됩니다.

대상 문법

원하는 문법은 다음과 같습니다. from 다음에 선택적인 where를 반복해서 사용하고, 마지막에 select를 둡니다. from 전에 select를 사용할 수 없고, from을 두 번 사용할 수도 없습니다.

상태 인터페이스

각 단계를 다음 단계를 반환하는 인터페이스로 모델링합니다.

interface Builder {
  from(table: string): FromStage;
}
interface FromStage {
  where(cond: string): FromStage; // repeatable
  select(...cols: string[]): Result;
}
interface Result { sql: string; }

순서 강제하기

select는 FromStage에만 존재하므로 초기 Builder에서 호출하면 컴파일 오류가 발생합니다. 각 단계가 어떤 메서드를 제공하는지만으로 순서가 강제됩니다.

declare const db: Builder;
db.from("users").select("id"); // ok
db.select("id");               // Error: select missing on Builder

선택한 열 추적하기

어떤 열을 선택했는지 기억하도록 팬텀 제네릭을 추가하면 결과 타입을 정확하게 만들 수 있습니다.

interface FromStage<T extends string = never> {
  where(c: string): FromStage<T>;
  select<C extends string>(...cols: C[]): Result<C>;
}
interface Result<C extends string> { columns: C[]; }

호출할 때마다 정교화하기

각 where는 타입에 제약 조건을 누적할 수도 있습니다. 여기서는 단순하게 유지하지만, 이 패턴은 바인딩된 매개변수를 추적하는 데에도 일반화할 수 있습니다.

const q = db.from("users").where("age > 18").where("active = true");
// still FromStage; select remains available

from 반복 방지하기

FromStage는 from을 제공하지 않으므로 두 번 호출할 수 없습니다. 문법이 구조적으로 이를 금지하므로 실행 시 보호 장치가 필요하지 않습니다.

db.from("a").from("b"); // Error: from does not exist on FromStage

종결 단계

select는 Result를 반환하며, 이 타입에는 where와 from이 모두 없습니다. 따라서 연결이 종료되고 결과를 읽는 작업만 남습니다.

const r = db.from("users").select("id", "name");
r.columns; // ("id" | "name")[]
// r.where(...) -> Error: where not on Result

타입이 지정된 열 제약 조건

또 다른 제네릭을 사용해 열을 알려진 테이블 스키마로 제한하면 알 수 없는 열이 거부됩니다. 이렇게 하면 이 DSL을 앞선 객체 관계 매핑 개념과 결합할 수 있습니다.

interface Table<Cols extends string> {
  select<C extends Cols>(...cols: C[]): Result<C>;
}
// db.from gives Table<"id" | "name" | "age">

선택적 단계와 필수 단계

단계 다음의 메서드만 제공하여 해당 단계를 필수로 만들 수 있습니다. 예를 들어 where를 호출한 후에만 select가 나타나는 단계를 반환하면 where를 한 번 이상 사용하도록 강제할 수 있습니다. 같은 연결형 타입은 쿼리 실행의 결과 행 타입도 추론할 수 있으므로, 컴파일 시점 문법과 실행 시점 데이터를 연결합니다.

이 내용이 중요한 이유

이렇게 설계한 플루언트 DSL은 자체적으로 문서화되며 잘못 사용할 수 없습니다. 자동 완성에는 유효한 다음 단계만 표시되고, 잘못된 순서는 절대 컴파일되지 않습니다. 이것이 사용하기 편리한 빌더 라이브러리의 핵심 기반입니다.

빠른 점검

플루언트 DSL 설계를 이해했는지 확인해 보세요.

복습

플루언트 쿼리 DSL을 타입 수준 상태 머신으로 설계했습니다. 각 단계 인터페이스는 다음 단계를 반환하고 유효한 메서드만 제공합니다. 팬텀 제네릭은 선택한 열을 추적하고, 종결 단계는 연결을 끝내며, 열 제약 조건은 알 수 없는 이름을 거부합니다. 이 모든 동작은 반환 타입으로 강제됩니다.

자주 묻는 질문

“유창한 쿼리 DSL 설계” 강의는 무료인가요?

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

“유창한 쿼리 DSL 설계”에서 뭘 배우나요?

연결 가능하고 자체적으로 검증하는 쿼리 API를 구축합니다. 브라우저에서 직접 실행하는 실습 코드로 TypeScript Academy을(를) 배우며, 24/7 AI 튜터가 강의를 진행하면서 질문에 답변해줍니다.

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

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

“유창한 쿼리 DSL 설계” 강의는 얼마나 걸리나요?

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

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

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

이 강의의 모든 강의

← TypeScript Academy(으)로 돌아가기