typescript

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

TypeScript

TypeScript 핸드북 기반 타입 정의 및 베스트 프랙티스. 기본 문법·타입 조작·유틸리티 타입 상세는 references/ 및 Handbook 참고.

基于TypeScript手册的类型定义及最佳实践。基础语法、类型操作、工具类型的详细内容请参考references/和Handbook。

기본 원칙

基本原则

1. 타입 추론 활용

1. 利用类型推断

불필요한 어노테이션 생략. 변경 시 이중 수정 부담 감소, 추론이 더 정확한 경우 많음.

typescript

// ❌
const name: string = "John";
const user: { name: string; age: number } = { name: "John", age: 30 };

// ✅
const name = "John";
const user = { name: "John", age: 30 };

省略不必要的注解，减少修改时的双重负担，很多时候推断结果更准确。

typescript

// ❌
const name: string = "John";
const user: { name: string; age: number } = { name: "John", age: 30 };

// ✅
const name = "John";
const user = { name: "John", age: 30 };

2. 명시적 반환 타입

2. 显式返回类型

함수 계약 명확화, 반환 타입 오변경 방지. 공개 API·복잡한 로직에서 필수.

typescript

function calculateTotal(items: Item[]): number {
  return items.reduce((sum, item) => sum + item.price, 0);
}
async function fetchUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}

明确函数契约，防止返回类型被误改。公开API、复杂逻辑中必须使用。

typescript

function calculateTotal(items: Item[]): number {
  return items.reduce((sum, item) => sum + item.price, 0);
}
async function fetchUser(id: string): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  return res.json();
}

3. any 사용 금지

3. 禁止使用any

타입 안전성·자동완성 무효화.

unknown

+ 타입 가드 또는 구체 타입 사용.

typescript

// ❌
function process(data: any) {
  return data.value;
}

// ✅
function process(data: unknown): number {
  if (typeof data === "object" && data !== null && "value" in data)
    return (data as { value: number }).value;
  throw new Error("Invalid data");
}

会使类型安全性、自动补全失效。应使用

unknown

+类型守卫或具体类型。

typescript

// ❌
function process(data: any) {
  return data.value;
}

// ✅
function process(data: unknown): number {
  if (typeof data === "object" && data !== null && "value" in data)
    return (data as { value: number }).value;
  throw new Error("Invalid data");
}

함수 · 제네릭

函数 · 泛型

함수: 인자·반환 타입 명시. 오버로드 시 구현 시그니처는 유니온으로.

제네릭:

K extends keyof T

등 제약 명시.

getProperty<T, K extends keyof T>(obj: T, key: K): T[K]

패턴 활용.

函数：显式声明参数、返回类型。重载时实现签名使用联合类型。

泛型：明确

、

K extends keyof T

等约束。使用

getProperty<T, K extends keyof T>(obj: T, key: K): T[K]

模式。

타입 가드

类型守卫

```
typeof
```
,
```
instanceof
```
,
```
in
```
으로 분기 후 타입 좁히기
복잡한 검사는 사용자 정의 가드
```
(value): value is T
```
사용

템플릿:
assets/types.guards.ts

使用
```
typeof
```
、
```
instanceof
```
、
```
in
```
进行分支后收窄类型
复杂检查使用自定义守卫
```
(value): value is T
```

模板：

assets/types.guards.ts

tsconfig

프로젝트 성격에 맞는 tsconfig를 사용
타입 안정성을 해치지 않는 선에서만 옵션을 조정
앱/서버/라이브러리는 설정 파일을 분리
타입 에러 회피 목적의 옵션 완화 금지

템플릿:

```
assets/tsconfig.nextjs.ts
```
```
assets/tsconfig.node.ts
```
```
assets/tsconfig.react.ts
```

使用符合项目性质的tsconfig
仅在不损害类型稳定性的前提下调整选项
应用/服务器/库需分离配置文件
禁止为规避类型错误而放宽选项

模板:

```
assets/tsconfig.nextjs.ts
```
```
assets/tsconfig.node.ts
```
```
assets/tsconfig.react.ts
```

이벤트 타입

事件类型

DOM / React 이벤트는 내장 타입 사용
커스텀 이벤트만 별도 타입 정의
이벤트 재정의 금지

템플릿:
assets/types.events.ts

DOM/React事件使用内置类型
仅自定义事件需单独定义类型
禁止重定义事件

模板：

assets/types.events.ts

유틸리티 타입

工具类型

TypeScript 내장 유틸리티 타입은 그대로 사용
커스텀 유틸리티 타입만 정의

템플릿:
assets/types.utils.ts

直接使用TypeScript内置工具类型
仅定义自定义工具类型

模板：

assets/types.utils.ts

실전 패턴

实战模式

interface 우선: 객체 계약·확장은
```
interface
```
, 유니온/인터섹션은
```
type
```
. API 설명은 명사형으로 작성 (
```
/** 비활성화 상태 */
```
).
as const
: 리터럴·객체 불변 보존.
```
typeof obj[keyof typeof obj]
```
로 이넘처럼 활용.

브랜드 타입:

type UserId = string & { readonly brand: unique symbol }

로 동일 원시 타입 구분.

타입 단언 최소화:
```
as
```
대신 타입 가드.
제네릭 제약:
```
T extends object
```
등 명시.

优先使用interface：对象契约、扩展使用
```
interface
```
，联合/交叉类型使用
```
type
```
。API说明使用名词形式（如
```
/** 禁用状态 */
```
）。
as const
：保留字面量、对象的不可变性。通过
```
typeof obj[keyof typeof obj]
```
像枚举一样使用。

品牌类型：使用

type UserId = string & { readonly brand: unique symbol }

区分相同原始类型。

最小化类型断言：用类型守卫替代
```
as
```
。
泛型约束：明确
```
T extends object
```
等约束。

타입 에러 해결

类型错误解决

에러	대응
`Type 'X' is not assignable to type 'Y'`	타입 가드로 분기 후 할당
`Property 'X' does not exist on type 'Y'`	타입 확장 또는 `optional`
`Object is possibly 'null' or 'undefined'`	`if (x == null)` / `?.` / `??`
`Argument of type 'X' is not assignable to parameter of type 'Y'`	제네릭 `T[]` 또는 오버로드
`Type 'X' cannot be used as an index type`	`keyof typeof obj` 사용

디버깅: 호버로 추론 확인, 가드·제네릭·유틸리티 타입으로 해결 후

as

는 최후 수단.

错误	对应解决方法
`Type 'X' is not assignable to type 'Y'`	通过类型守卫分支后赋值
`Property 'X' does not exist on type 'Y'`	类型扩展或设置为 `optional`
`Object is possibly 'null' or 'undefined'`	使用 `if (x == null)` / `?.` / `??`
`Argument of type 'X' is not assignable to parameter of type 'Y'`	使用泛型 `T[]` 或重载
`Type 'X' cannot be used as an index type`	使用 `keyof typeof obj`

调试：通过悬停查看推断结果，优先用守卫、泛型、工具类型解决，

as

作为最后手段。

참고

参考

이 문서들은 규칙이 아니라 참고용, 판단 기준은 각 skill 문서를 우선

TypeScript Handbook - TypeScript 공식 개념·타입 시스템 레퍼런스
Playground - 타입 동작 실험 및 예제 검증용

本文档为参考而非规则，判断标准优先遵循各skill文档

TypeScript Handbook - TypeScript官方概念、类型系统参考
Playground - 用于实验类型行为及验证示例