icon안동민 개발노트

타입스크립트 디버깅 기법

 효과적인 디버깅은 개발 과정에서 필수적인 기술입니다.

 TypeScript를 사용할 때 정적 타입 검사의 이점을 누릴 수 있지만, 런타임 문제를 해결하기 위해서는 강력한 디버깅 기법이 필요합니다.

 이 절에서는 TypeScript 프로젝트의 다양한 디버깅 기법과 전략을 살펴봅니다.

VSCode에서 TypeScript 디버깅 설정

 1. launch.json 파일 생성

  • VSCode에서 디버그 뷰 열기 (Ctrl+Shift+D)
  • 'launch.json 파일 만들기' 클릭
  • Node.js 환경 선택

 2. launch.json 구성 예시

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug TypeScript",
      "program": "${workspaceFolder}/src/index.ts",
      "preLaunchTask": "tsc: build - tsconfig.json",
      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
      "sourceMaps": true
    }
  ]
}

 3. tsconfig.json에 소스맵 설정 추가

{
  "compilerOptions": {
    "sourceMap": true,
    "outDir": "./dist"
  }
}

소스맵의 이해와 활용

 소스맵은 컴파일된 코드와 원본 소스 코드 사이의 매핑을 제공합니다. TypeScript 디버깅에서 중요한 역할을 합니다.

  • 브라우저나 Node.js에서 TypeScript 코드를 직접 디버깅 가능
  • 컴파일된 JavaScript 대신 원본 TypeScript 코드에 브레이크포인트 설정 가능

 효과적인 소스맵 구성

  1. tsconfig.json에서 "sourceMap": true 설정
  2. 웹팩 사용 시 devtool: "source-map" 옵션 추가
  3. 프로덕션 빌드 시 소스맵 생성 여부 신중히 결정 (보안 고려)

브라우저 개발자 도구를 사용한 TypeScript 디버깅

 Chrome DevTools 사용

  • Sources 탭에서 TypeScript 파일 찾기
  • 브레이크포인트 설정 및 변수 검사
  • Watch 표현식 추가로 복잡한 상태 모니터링

 주의사항

  • 소스맵이 올바르게 로드되었는지 확인
  • 프로덕션 환경에서는 소스맵 비활성화 고려

Node.js 환경에서의 TypeScript 디버깅

  1. node --inspect
node --inspect -r ts-node/register src/index.ts
  • Chrome DevTools를 통한 원격 디버깅 가능
  1. ndb (Node Debugger)
ndb ts-node src/index.ts
  • 향상된 UI와 성능 제공
  • TypeScript 파일 직접 디버깅 가능

 비교

  • node --inspect : 표준적이고 널리 지원됨
  • ndb : 더 풍부한 기능과 사용자 친화적 인터페이스 제공

TypeScript 특유의 디버깅 문제 해결

 1. 제네릭 디버깅

  • VSCode의 "Inline Values" 기능 활용
  • 복잡한 제네릭 타입의 경우 중간 변수 사용하여 타입 추론 확인

 2. 고급 타입 디버깅

  • 조건부 타입, 매핑된 타입 등의 경우 타입 단언 활용
type ComplexType<T> = T extends string ? number : boolean;
let value: ComplexType<string>;
(value as number).toFixed(2); // 디버깅 시 타입 확인 용이

 3. 타입 가드 활용

function isString(value: unknown): value is string {
  return typeof value === 'string';
}
 
if (isString(someValue)) {
  // someValue의 타입이 string으로 좁혀짐
  console.log(someValue.toUpperCase());
}

로깅과 에러 처리 전략

  1. 구조화된 로깅
import winston from 'winston';
 
const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'error.log', level: 'error' }),
    new winston.transports.File({ filename: 'combined.log' })
  ]
});
 
// 사용 예
logger.info('Info message', { contextData: 'some data' });
logger.error('Error message', { err: new Error('Some error') });
  1. 커스텀 에러 클래스
class AppError extends Error {
  constructor(public code: string, message: string) {
    super(message);
    this.name = 'AppError';
  }
}
 
try {
  throw new AppError('INVALID_INPUT', 'The input is invalid');
} catch (error) {
  if (error instanceof AppError) {
    logger.error(`${error.code}: ${error.message}`);
  }
}

컴파일러 API를 활용한 커스텀 디버깅 도구

 TypeScript 컴파일러 API를 사용하여 AST(Abstract Syntax Tree)를 분석하고 커스텀 디버깅 정보를 추출할 수 있습니다.

import * as ts from 'typescript';
 
function getSymbolAtPosition(fileName: string, position: number) {
  const program = ts.createProgram([fileName], {});
  const sourceFile = program.getSourceFile(fileName);
  const typeChecker = program.getTypeChecker();
 
  if (sourceFile) {
    const node = findNodeAtPosition(sourceFile, position);
    if (node) {
      const symbol = typeChecker.getSymbolAtLocation(node);
      if (symbol) {
        console.log(typeChecker.symbolToString(symbol));
      }
    }
  }
}
 
function findNodeAtPosition(sourceFile: ts.SourceFile, position: number): ts.Node | undefined {
  function find(node: ts.Node): ts.Node | undefined {
    if (position >= node.getStart() && position < node.getEnd()) {
      return ts.forEachChild(node, find) || node;
    }
  }
  return find(sourceFile);
}
 
// 사용 예
getSymbolAtPosition('path/to/file.ts', 100);

 이 도구를 VSCode 익스텐션이나 CLI 도구로 확장하여 더 강력한 디버깅 경험을 제공할 수 있습니다.

프로덕션 환경 디버깅 전략

 1. 소스맵 관리

  • 프로덕션 빌드 시 소스맵 생성 후 안전한 위치에 보관
  • 필요 시에만 소스맵 로드하여 디버깅

 2. 에러 추적 서비스 활용

  • Sentry, Rollbar 등의 서비스 사용
  • TypeScript 소스맵 업로드로 원본 코드 라인 추적

 3. 로깅 강화

  • 중요 지점에 상세한 로그 추가
  • 사용자 세션, 컨텍스트 정보 포함

 4. 특정 사용자/세션에 대한 디버그 모드

const isDebugMode = (userId: string) => {
  return process.env.DEBUG_USERS?.includes(userId) ?? false;
};
 
if (isDebugMode(currentUser.id)) {
  logger.setLevel('debug');
  // 추가적인 디버그 정보 로깅
}

Best Practices와 팁

 1. 엄격한 타입 체크 활성화

{
  "compilerOptions": {
    "strict": true
  }
}

 2. 단위 테스트 작성

  • 복잡한 로직에 대한 단위 테스트로 디버깅 필요성 감소

 3. 디버그 설정 버전 관리

  • launch.json을 프로젝트 레포지토리에 포함

 4. 조건부 브레이크포인트 활용

  • VSCode에서 브레이크포인트에 조건 추가 가능

 5. 로그포인트 사용

  • 코드 수정 없이 로그 출력 가능

 6. 타입 단언 최소화

  • 디버깅을 위한 임시 사용은 괜찮지만, production 코드에서는 지양

 7. 환경별 설정 분리

  • 개발, 테스트, 프로덕션 환경에 따른 디버그 설정 분리

 8. 성능 프로파일링

  • Chrome DevTools 또는 Node.js 프로파일러 활용

 9. 코드 품질 도구 활용

  • ESLint, SonarQube 등을 사용하여 잠재적 버그 조기 발견

 10. 지속적인 학습과 도구 업데이트

  • TypeScript와 관련 도구의 새로운 기능 주시

 TypeScript 디버깅은 정적 타입 시스템의 이점과 JavaScript의 유연성을 결합하여 강력한 문제 해결 능력을 제공합니다.

 소스맵의 올바른 구성과 활용은 TypeScript 디버깅의 핵심입니다.

 이를 통해 컴파일된 JavaScript가 아닌 원본 TypeScript 코드를 직접 디버깅할 수 있어 생산성이 크게 향상됩니다.

 로깅과 에러 처리 전략을 체계적으로 구현하면 프로덕션 환경에서 발생하는 문제를 더 쉽게 진단하고 해결할 수 있습니다.

이전으로다음으로