답변.

질문의 역사:

많은 JavaScript 생태계의 라이브러리는 자체 타입 없이 소스 js 파일만 제공합니다. 외부 또는 커스텀 라이브러리뿐만 아니라 전역 변수에 대한 타입을 설명하기 위해 TypeScript에서는 .d.ts(선언 파일) 확장자를 가진 파일 형식을 구현했습니다. 이는 모든 js 모듈 위의 프로젝트에서 타입 정보를 보장하고 타입 안전성을 제공하는 표준이 되었습니다.

문제:

타입이 정의되지 않은 외부 JS 모듈에 대해서는 TypeScript가 그러한 임포트를 any로 해석해야 하며, 이는 정적 타입 지정의 모든 장점을 잃게 만듭니다: 호출에서의 오류, 존재하지 않는 필드, 잘못된 매개변수는 컴파일을 통과하게 되고, 코드 실행 후에만 발견됩니다. 또한 타입에 대한 자동 완성과 탐색을 할 수 없습니다.

해결책:

선언 파일을 사용하여 모든 JS 코드에 대해 수동으로 타입을 설명할 수 있습니다: 함수, 클래스, 객체, 네임스페이스, 심지어 전역 상수까지. 이렇게 함으로써 프로젝트는 외부 라이브러리의 출처와 관계없이 타입 안전성을 유지할 수 있습니다.

코드 예시:

// hello.d.ts
declare module 'hello' {
  export function sayHello(name: string): string;
}
// app.ts
import { sayHello } from 'hello';
sayHello('TypeScript'); // 타입 안전

주요 특징:

• 구현(원본 JS 코드)에서 시그니처 및 타입 구조 설명을 분리합니다;
• 외부/구식 빌드에서도 엄격한 타입 지정을 도입할 수 있게 합니다;
• .d.ts 파일에서는 구현이 금지되며, 오직 시그니처/설명만 가능합니다.

함정 질문.

선언 파일에서 함수의 구현을 직접 선언할 수 있습니까?

아니요, 선언 파일에서는 구조와 시그니처만 선언할 수 있으며 구현은 허용되지 않습니다. 함수 본체를 포함시키면 컴파일 오류가 발생합니다.

// 안 됩니다:
declare function sum(a: number, b: number) { return a + b; }

소스 패키지에 없는 인기 npm 모듈의 타입은 어디서 찾을 수 있습니까?

DefinitelyTyped 저장소(npm 패키지 @types/<lib>): 거의 모든 인기 패키지는 별도의 npm 모듈 형태로 최신 타입을 가지고 있습니다.

d.ts 파일을 사용하여 전역 변수를 설명할 수 있습니까(임포트 없이)?

예, ambient declarations 메커니즘을 통해 가능합니다. 예를 들어, declare var VERSION: string;. 이는 window.X, 전역 상수 및 변수를 설명하는 데 유용합니다.

타입 오류 및 안티 패턴

• d.ts 파일에 함수와 클래스의 본체를 작성하는 것;
• 불완전하거나 오래된 시그니처를 설명하여 실제 구조와 충돌을 일으키는 것;
• 동일한 모듈/전역 변수에 대해 서로 다른 타입을 연결하여 타입 충돌을 일으키는 것.

실제 사례

** 부정적인 사례 프로젝트에서 타입이 없는 JS 라이브러리를 사용하고 있습니다. 개발자들이 d.ts 파일을 잊고 any를 통해 API에 접근합니다. 라이브러리를 업데이트할 때 버그가 발생합니다: 오래된 호출이 깨지지만 컴파일러는 이를 인식하지 못합니다.

장점:

• 빠른 시작, 추가 설명이 필요하지 않음.

단점:

• 숨겨진 오류, 명시되지 않은 동작, 대규모 코드에서의 디버그가 복잡해짐.

** 긍정적인 사례 현재 라이브러리에 대한 자체 d.ts 파일이 개발되어 시그니처가 최신 상태로 유지되어 있으며 IDE에서 자동 완성과 탐색이 사용됩니다.

장점:

• 완전한 타입 안전성, API 변경 시 즉시 오류가 보이게 됨;
• 개발 속도가 빨라지며, 새로운 개발자를 JS 코드에 대한 깊은 학습 없이 쉽게 참여시킬 수 있음.

단점:

• d.ts 파일에 대한 별도의 관리가 필요하며, JS 라이브러리 업데이트 시 동기화를 확인해야 함.