---
name: TypeScript & Naming
description: TypeScript & 네이밍 원칙. any 금지, snake_case 변환, 네이밍 컨벤션, type import 분리, if문 중괄호.
type: coding-standard
category: typescript-naming
---

> 출처: 팀 공통 원칙 문서 `principles/` 2026-07-03 발췌. 원칙 개정은 원본(팀 공통 문서) 먼저, 이 사본은 따라간다.

# TypeScript & 네이밍

## P-015 any 타입 금지

`as any`, `as unknown as T`, `@ts-ignore` 정당한 이유 없이 금지.
타입 단언은 코드 냄새다. 타입을 숨기지 말고 고쳐라.

해결 순서:

1. 타입 가드
2. 제네릭
3. 유니온 타입 + 타입 좁히기
4. Zod 스키마 검증
5. 팀원에게 묻기

```typescript
// ❌
const data = response as any;
const user = response as unknown as User;

// ✅ 타입 가드
function isUser(value: unknown): value is User {
  return typeof value === 'object' && value !== null && 'id' in value;
}
if (isUser(response)) {
  /* response는 User */
}
```

## P-016 snake_case → camelCase API 경계 변환

서버 응답이 snake_case여도 클라이언트 코드는 camelCase를 사용한다.
`change-case` 라이브러리로 API 경계에서 변환한다 (`humps` 사용 금지 — archived).

```typescript
// ❌ snake_case가 컴포넌트 코드까지 침투
interface Post {
  author_name: string;
  published_at: Date;
}
console.log(res.data.author_name);

// ✅ API 경계에서 변환
import { camelCase, snakeCase } from 'change-case/keys';

export const requestInterceptor = (config) => {
  config.data = snakeCase(config.data);
  return config;
};
export const responseInterceptor = (response) => {
  return Promise.resolve(camelCase(response.data));
};
```

## P-017 네이밍 컨벤션

| 대상                                    | 규칙              | 예시                             |
| --------------------------------------- | ----------------- | -------------------------------- |
| 변수, 함수, 파라미터                    | camelCase         | `getUserProfile`                 |
| 컴포넌트, 타입, 인터페이스, 클래스      | PascalCase        | `ProfileCard`                    |
| 상수, 열거형 멤버                       | UPPER_SNAKE_CASE  | `MAX_FILE_SIZE`                  |
| 슬라이스 폴더                           | kebab-case        | `user-profile`                   |
| Props 인터페이스 (내부용, export 안 함) | `interface Props` | `interface Props { id: number }` |

## P-018 타입 전용 import 분리

타입 전용 import는 `import type`으로 분리한다.
번들러가 타입 import를 제거하는 데 도움이 되고, 순환 의존성 문제를 방지한다.

```typescript
// ❌
import { User, formatDate } from './types';

// ✅
import type { User } from './types';
import { formatDate } from './utils';
```

## P-019 if문에 항상 중괄호 사용

early return을 포함한 모든 if문에 중괄호를 사용한다.
중괄호 없는 if문은 줄 추가 시 버그를 만든다.

```typescript
// ❌
if (isValid) return;
if (isLoading) return null;

// ✅
if (isValid) {
  return;
}
if (isLoading) {
  return null;
}
```