TypeScript을 찾는 분이 가장 먼저 구분해야 할 기준부터 실제 순서까지 정리했습니다. TypeScript를 도입해도 strict 설정이 꺼져 있거나 외부 입력을 무검증 단언으로 넘기면 런타임 오류는 남습니다. 설정 기준, null 처리, optional 속성 의미, unknown 좁히기, 라이브러리 경계, 빌드 타입 검사를 한 단계씩 올려야 오류 원인을 추적할 수 있습니다.
읽는 시간 약 7분 · 가이드: 판단 기준 · 실행 순서 · 구매와 보관
TypeScript 문제 정의: 먼저 기준을 세워야 하는 이유
TypeScript를 도입해도 strict 설정이 꺼져 있거나 외부 입력을 무검증 단언으로 넘기면 런타임 오류는 남습니다. 설정 기준, null 처리, optional 속성 의미, unknown 좁히기, 라이브러리 경계, 빌드 타입 검사를 한 단계씩 올려야 오류 원인을 추적할 수 있습니다.
한 번에 모든 엄격 옵션을 켜고 수백 개 오류를 임의 단언으로 덮으면 기술 부채가 다른 형태로 남습니다. 기준 빌드와 오류 수를 저장하고 한 옵션씩 활성화한 뒤 오류 유형별로 수정해야 개선 원인을 설명할 수 있습니다.
| 첫 확인 | 기준 오류 수 |
|---|
현실 차이: 겉으로 비슷해도 결과가 달라지는 지점
컴파일 통과와 런타임 안전의 차이
타입 검사는 선언을 확인하지만 네트워크·파일·사용자 입력의 실제 값까지 자동 검증하지 않습니다.
TypeScript의 컴파일 통과와 런타임 안전의 차이 단계에서는 외부 입력은 unknown으로 받고 실행 시 검증을 추가하세요. 이때 다른 조건은 유지해야 컴파일 통과와 런타임 안전의 차이에서 생긴 차이를 분리해 확인할 수 있습니다.
현실 관점의 판정 신호는 경계 검증입니다. 컴파일 통과와 런타임 안전의 차이의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
컴파일 통과와 런타임 안전의 차이 확인은 외부 입력은 unknown으로 받고 실행 시 검증을 추가하세요. 이후 경계 검증 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 컴파일 통과와 런타임 안전의 차이 결과가 한 번 더 재현되는지 확인하세요.
| 현실 확인 | 경계 검증 |
|---|
optional과 undefined의 차이
속성이 없는 상태와 값이 undefined인 상태는 런타임에서 다르게 동작할 수 있습니다.
이 항목의 optional과 undefined의 차이 단계에서는 데이터 계약에서 두 상태의 의미를 명시하세요. 이때 다른 조건은 유지해야 optional과 undefined의 차이에서 생긴 차이를 분리해 확인할 수 있습니다.
현실 관점의 판정 신호는 부재 의미 고정입니다. optional과 undefined의 차이의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
optional과 undefined의 차이 확인은 데이터 계약에서 두 상태의 의미를 명시하세요. 이후 부재 의미 고정 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 optional과 undefined의 차이 결과가 한 번 더 재현되는지 확인하세요.
| 현실 확인 | 부재 의미 고정 |
|---|
업그레이드 전후의 차이
strict 계열은 버전 변화로 새 검사가 추가될 수 있어 업그레이드 뒤 오류가 생길 수 있습니다.
이 항목의 업그레이드 전후의 차이 단계에서는 버전과 설정 파일을 고정한 기준 빌드를 남기세요. 이때 다른 조건은 유지해야 업그레이드 전후의 차이에서 생긴 차이를 분리해 확인할 수 있습니다.
현실 관점의 판정 신호는 버전 기준선입니다. 업그레이드 전후의 차이의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
업그레이드 전후의 차이 확인은 버전과 설정 파일을 고정한 기준 빌드를 남기세요. 이후 버전 기준선 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 업그레이드 전후의 차이 결과가 한 번 더 재현되는지 확인하세요.
| 현실 확인 | 버전 기준선 |
|---|
TypeScript 판단 기준 3가지
strict 기준
strict는 여러 엄격 검사 동작을 한 번에 활성화해 더 강한 정확성 보장을 제공합니다.
TypeScript의 strict 기준 단계에서는 활성화 전 오류 수와 테스트 결과를 저장하세요. 이때 다른 조건은 유지해야 strict 기준에서 생긴 차이를 분리해 확인할 수 있습니다.
판단 관점의 판정 신호는 기준 오류 수입니다. strict 기준의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
strict 기준 확인은 활성화 전 오류 수와 테스트 결과를 저장하세요. 이후 기준 오류 수 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 strict 기준 결과가 한 번 더 재현되는지 확인하세요.
| 판단 확인 | 기준 오류 수 |
|---|
null 처리
null과 undefined를 일반 값처럼 다루면 속성 접근에서 런타임 실패가 생길 수 있습니다.
이 항목의 null 처리 단계에서는 입력 경계에서 좁히고 함수 반환형에 가능 상태를 표현하세요. 이때 다른 조건은 유지해야 null 처리에서 생긴 차이를 분리해 확인할 수 있습니다.
판단 관점의 판정 신호는 nullable 명시입니다. null 처리의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
null 처리 확인은 입력 경계에서 좁히고 함수 반환형에 가능 상태를 표현하세요. 이후 nullable 명시 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 null 처리 결과가 한 번 더 재현되는지 확인하세요.
| 판단 확인 | nullable 명시 |
|---|
unknown 좁히기
any는 검사를 우회하지만 unknown은 사용 전에 타입 확인을 요구합니다.
이 항목의 unknown 좁히기 단계에서는 typeof, instanceof, 속성 검사와 사용자 정의 가드로 좁히세요. 이때 다른 조건은 유지해야 unknown 좁히기에서 생긴 차이를 분리해 확인할 수 있습니다.
판단 관점의 판정 신호는 무검증 any 감소입니다. unknown 좁히기의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
unknown 좁히기 확인은 typeof, instanceof, 속성 검사와 사용자 정의 가드로 좁히세요. 이후 무검증 any 감소 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 unknown 좁히기 결과가 한 번 더 재현되는지 확인하세요.
| 판단 확인 | 무검증 any 감소 |
|---|
optional 속성
optional 속성의 부재와 undefined 할당을 같은 의미로 둘지 계약에서 결정해야 합니다.
이 항목의 optional 속성 단계에서는 exact optional 옵션을 후보 브랜치에서 검증하세요. 이때 다른 조건은 유지해야 optional 속성에서 생긴 차이를 분리해 확인할 수 있습니다.
판단 관점의 판정 신호는 계약 일치입니다. optional 속성의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
optional 속성 확인은 exact optional 옵션을 후보 브랜치에서 검증하세요. 이후 계약 일치 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 optional 속성 결과가 한 번 더 재현되는지 확인하세요.
| 판단 확인 | 계약 일치 |
|---|
| 확인 항목 | 권장 신호 | 피할 신호 |
|---|---|---|
| strict 기준 | 기준 오류 수 | strict는 여러 엄격 검사 동작을 한 번에 활성화해 더 강한 정확성 보장을 제공합니다. |
| null 처리 | nullable 명시 | null과 undefined를 일반 값처럼 다루면 속성 접근에서 런타임 실패가 생길 수 있습니다. |
| unknown 좁히기 | 무검증 any 감소 | any는 검사를 우회하지만 unknown은 사용 전에 타입 확인을 요구합니다. |
| optional 속성 | 계약 일치 | optional 속성의 부재와 undefined 할당을 같은 의미로 둘지 계약에서 결정해야 합니다. |
TypeScript 실행법 3단계
1단계 · 기준 빌드 저장
현재 컴파일러 버전, 설정 파일, 오류 수, 테스트 결과를 기록합니다.
TypeScript의 1단계 · 기준 빌드 저장 단계에서는 변경 전 로그를 보존하세요. 이때 다른 조건은 유지해야 1단계 · 기준 빌드 저장에서 생긴 차이를 분리해 확인할 수 있습니다.
실행 관점의 판정 신호는 기준선 확보입니다. 1단계 · 기준 빌드 저장의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
1단계 · 기준 빌드 저장 확인은 변경 전 로그를 보존하세요. 이후 기준선 확보 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 1단계 · 기준 빌드 저장 결과가 한 번 더 재현되는지 확인하세요.
| 실행 확인 | 기준선 확보 |
|---|
2단계 · strict 활성화 후보
작은 브랜치에서 strict를 켜고 오류를 null, 암시적 any, 함수 경계 등으로 분류합니다.
이 항목의 2단계 · strict 활성화 후보 단계에서는 오류 유형별 목록을 만드세요. 이때 다른 조건은 유지해야 2단계 · strict 활성화 후보에서 생긴 차이를 분리해 확인할 수 있습니다.
실행 관점의 판정 신호는 오류 분류입니다. 2단계 · strict 활성화 후보의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
2단계 · strict 활성화 후보 확인은 오류 유형별 목록을 만드세요. 이후 오류 분류 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 2단계 · strict 활성화 후보 결과가 한 번 더 재현되는지 확인하세요.
| 실행 확인 | 오류 분류 |
|---|
3단계 · 외부 입력 경계 수정
API 응답과 사용자 입력을 unknown으로 받고 검증 후 도메인 타입으로 변환합니다.
이 항목의 3단계 · 외부 입력 경계 수정 단계에서는 실패 입력 테스트를 추가하세요. 이때 다른 조건은 유지해야 3단계 · 외부 입력 경계 수정에서 생긴 차이를 분리해 확인할 수 있습니다.
실행 관점의 판정 신호는 입력 검증입니다. 3단계 · 외부 입력 경계 수정의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
3단계 · 외부 입력 경계 수정 확인은 실패 입력 테스트를 추가하세요. 이후 입력 검증 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 3단계 · 외부 입력 경계 수정 결과가 한 번 더 재현되는지 확인하세요.
| 실행 확인 | 입력 검증 |
|---|
4단계 · 한 옵션씩 확장
optional 속성 등 추가 옵션은 별도 변경으로 적용합니다.
이 항목의 4단계 · 한 옵션씩 확장 단계에서는 각 단계에서 빌드와 테스트가 유지될 때만 다음으로 이동하세요. 이때 다른 조건은 유지해야 4단계 · 한 옵션씩 확장에서 생긴 차이를 분리해 확인할 수 있습니다.
실행 관점의 판정 신호는 단일 변수 적용입니다. 4단계 · 한 옵션씩 확장의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
4단계 · 한 옵션씩 확장 확인은 각 단계에서 빌드와 테스트가 유지될 때만 다음으로 이동하세요. 이후 단일 변수 적용 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 4단계 · 한 옵션씩 확장 결과가 한 번 더 재현되는지 확인하세요.
| 실행 확인 | 단일 변수 적용 |
|---|
주의점: 잘못 적용하기 쉬운 부분
TypeScript 적용 전 확인과 실행 중 확인을 분리해서 보세요. 아래 항목이 맞지 않으면 범위나 재시도 횟수를 늘리지 마세요.
- 오류를 전부 타입 단언으로 덮기컴파일 오류만 사라지고 실제 값 불일치가 남을 수 있습니다.
- 외부 입력을 any로 고정경계에서 타입 검사가 무력화되어 코드 전반으로 불확실성이 퍼질 수 있습니다.
- 여러 설정 동시 활성화어떤 옵션이 어떤 오류를 만든 것인지 추적하기 어렵습니다.
- 라이브러리 타입만 신뢰실제 응답과 선언이 다를 수 있으므로 실행 시 검증이 필요합니다.
- 버전 업그레이드와 리팩터링 동시 진행오류 원인이 컴파일러 변화인지 코드 변화인지 분리하기 어렵습니다.
상황별 적용: 같은 기준을 다르게 쓰는 법
API 응답을 받는 경우
응답을 unknown으로 받고 필수 속성과 값 범위를 확인한 뒤 검증된 데이터 모델로 변환합니다.
TypeScript의 API 응답을 받는 경우 단계에서는 잘못된 응답 샘플 테스트를 추가하세요. 이때 다른 조건은 유지해야 API 응답을 받는 경우에서 생긴 차이를 분리해 확인할 수 있습니다.
상황 관점의 판정 신호는 실패 입력 검증입니다. API 응답을 받는 경우의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
API 응답을 받는 경우 확인은 잘못된 응답 샘플 테스트를 추가하세요. 이후 실패 입력 검증 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 API 응답을 받는 경우 결과가 한 번 더 재현되는지 확인하세요.
| 상황 확인 | 실패 입력 검증 |
|---|
기존 JavaScript를 전환하는 경우
핵심 경계부터 타입을 추가하고 남은 미전환 범위를 기록합니다.
이 항목의 기존 JavaScript를 전환하는 경우 단계에서는 무검증 any의 위치와 제거 계획을 남기세요. 이때 다른 조건은 유지해야 기존 JavaScript를 전환하는 경우에서 생긴 차이를 분리해 확인할 수 있습니다.
상황 관점의 판정 신호는 점진 전환입니다. 기존 JavaScript를 전환하는 경우의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
기존 JavaScript를 전환하는 경우 확인은 무검증 any의 위치와 제거 계획을 남기세요. 이후 점진 전환 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 기존 JavaScript를 전환하는 경우 결과가 한 번 더 재현되는지 확인하세요.
| 상황 확인 | 점진 전환 |
|---|
컴파일러를 업그레이드하는 경우
버전만 바꾼 브랜치에서 새 오류를 수집하고 설정 변화와 분리합니다.
이 항목의 컴파일러를 업그레이드하는 경우 단계에서는 기준 테스트가 유지될 때만 병합하세요. 이때 다른 조건은 유지해야 컴파일러를 업그레이드하는 경우에서 생긴 차이를 분리해 확인할 수 있습니다.
상황 관점의 판정 신호는 업그레이드 격리입니다. 컴파일러를 업그레이드하는 경우의 실행 전후에 이 신호를 같은 위치에서 읽으면 추측 대신 관찰 결과로 판단할 수 있습니다.
컴파일러를 업그레이드하는 경우 확인은 기준 테스트가 유지될 때만 병합하세요. 이후 업그레이드 격리 상태를 기록하는 순서로 마칩니다. 이 주제의 다음 단계로 넘어가기 전에 컴파일러를 업그레이드하는 경우 결과가 한 번 더 재현되는지 확인하세요.
| 상황 확인 | 업그레이드 격리 |
|---|
근거를 읽는 방법과 확인 순서
TypeScript 공식 문서는 strict가 더 강한 정확성 보장을 위한 여러 검사 동작을 활성화한다고 설명하며, 향후 버전에서 추가 엄격 검사가 포함될 수 있다고 안내합니다. exact optional 옵션은 속성의 부재와 undefined 할당의 차이를 더 정확히 표현합니다.
TypeScript 근거는 수치 하나를 떼어 보기보다 측정 조건, 비교 대상, 적용 범위를 함께 읽어야 합니다. 짧은 소개 문구보다 공식 문서와 실제 실행 로그를 우선하면 판단 오류를 줄일 수 있습니다.
- TypeScript strict 옵션 – strict 계열의 목적과 업그레이드 영향 확인
- TypeScript exactOptionalPropertyTypes – optional 속성 부재와 undefined 차이 확인
- TypeScript 기본 타입과 unknown – unknown과 any의 사용 차이 확인
TypeScript strict를 켜면 런타임 오류가 모두 없어지나요?
아닙니다. 외부 입력의 실제 값은 별도 실행 시 검증이 필요합니다.
any와 unknown 중 무엇을 써야 하나요?
값을 확인하기 전에는 unknown이 안전합니다. any는 타입 검사를 우회하므로 사용 범위와 제거 계획을 기록하세요.
strict를 한 번에 켜도 되나요?
오류가 적은 프로젝트는 가능하지만, 큰 프로젝트는 기준 빌드 후 오류 유형을 나누고 단계적으로 적용하는 편이 원인 추적에 유리합니다.
optional 속성에 undefined를 넣어도 되나요?
설정과 데이터 계약에 따라 다릅니다. 속성 부재와 undefined가 같은 의미인지 먼저 정하세요.
업그레이드 뒤 새 타입 오류가 생긴 이유는 무엇인가요?
strict 계열에 새 검사가 추가되거나 타입 선언이 바뀔 수 있으므로 컴파일러 버전과 설정 변화부터 분리해 확인하세요.
마무리: 오늘 바로 적용할 순서
TypeScript 고도화는 strict를 켠 사실보다 기준 빌드, 오류 분류, 외부 입력 검증, null·optional 계약, 업그레이드 격리가 더 중요합니다. 오늘은 현재 오류 수를 저장하고 외부 입력 한 곳을 unknown 검증 흐름으로 바꿔 보세요.
TypeScript은 한 문장으로 단정하기보다 확인할 항목을 순서대로 나누는 것이 핵심입니다. 첫 기록을 남기고 다음번 결과와 비교하면 구매, 사용, 보관에서 같은 실수를 반복할 가능성이 낮아집니다.