TypeScript现代开发实践指南

TypeScript是JavaScript的超集，通过添加静态类型检查，为大型应用开发提供了更好的可维护性、可读性和开发体验。随着前端应用复杂度的增加，TypeScript已成为现代前端开发的标准选择。

核心价值

TypeScript = 类型安全 + 开发体验 + 工程化 + 生态支持

• 🛡️ 类型安全：编译时错误检查，减少运行时错误
• 🔧 开发体验：智能提示、重构支持、导航跳转
• 📦 工程化支持：模块系统、装饰器、编译优化
• 🌐 生态丰富：与主流框架和工具深度集成
• 📚 渐进式采用：可以逐步从JavaScript迁移
• 🎯 团队协作：统一的类型约定，提高代码质量

1. TypeScript类型系统深度解析

1.1 类型系统架构

TypeScript的类型系统是其核心特性，提供了从基础类型到高级类型的完整解决方案。

类型系统特性对比

类型特性	JavaScript	TypeScript	优势	适用场景
静态类型检查	❌	✅	编译时发现错误	大型项目
类型推断	❌	✅	减少类型注解	提升开发效率
接口定义	❌	✅	契约式编程	API设计
泛型支持	❌	✅	类型复用	工具函数
装饰器	实验性	✅	元编程	框架开发
枚举类型	❌	✅	常量管理	状态定义

基础类型系统

基础类型与类型注解

TypeScript基础类型完整示例

typescript

1// 1. 原始类型
2const userName: string = 'John Doe'
3const userAge: number = 30
4const isActive: boolean = true
5const userSymbol: symbol = Symbol('user')
6const userBigInt: bigint = 100n
7
8// 2. 字面量类型
9type Theme = 'light' | 'dark' | 'auto'
10type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE'
11type StatusCode = 200 | 404 | 500
12
13const currentTheme: Theme = 'dark'
14const apiMethod: HttpMethod = 'POST'
15
16// 3. 数组类型
17const numbers: number[] = [1, 2, 3, 4, 5]
18const strings: Array<string> = ['hello', 'world']
19const mixed: (string | number)[] = ['hello', 42, 'world']
20
21// 只读数组
22const readonlyNumbers: readonly number[] = [1, 2, 3]
23const readonlyStrings: ReadonlyArray<string> = ['a', 'b', 'c']
24
25// 4. 元组类型
26type Coordinate = [number, number]
27type NamedCoordinate = [x: number, y: number]
28type OptionalTuple = [string, number?]
29type RestTuple = [string, ...number[]]
30
31const point: Coordinate = [10, 20]
32const namedPoint: NamedCoordinate = [10, 20]
33const optionalPoint: OptionalTuple = ['origin']
34const restPoint: RestTuple = ['point', 1, 2, 3]
35
36// 5. 对象类型
37interface User {
38  readonly id: number
39  name: string
40  email?: string
41  age: number
42  preferences: {
43    theme: Theme
44    notifications: boolean
45  }
46}
47
48type UserUpdate = {
49  name?: string
50  email?: string
51  age?: number
52}
53
54// 索引签名
55interface Dictionary<T> {
56  [key: string]: T
57}
58
59interface NumberDictionary {
60  [index: string]: number
61  length: number // 必须是number类型
62}
63
64// 6. 函数类型
65type AddFunction = (a: number, b: number) => number
66type AsyncFunction<T> = (data: T) => Promise<void>
67type EventHandler<T = Event> = (event: T) => void
68
69const add: AddFunction = (a, b) => a + b
70const processData: AsyncFunction<User> = async (user) => {
71  console.log(`Processing user: ${user.name}`)
72}
73
74// 函数重载
75function createUser(name: string): User
76function createUser(id: number, name: string): User
77function createUser(idOrName: string | number, name?: string): User {
78  if (typeof idOrName === 'string') {
79    return {
80      id: Math.random(),
81      name: idOrName,
82      age: 0,
83      preferences: { theme: 'light', notifications: true }
84    }
85  } else {
86    return {
87      id: idOrName,
88      name: name!,
89      age: 0,
90      preferences: { theme: 'light', notifications: true }
91    }
92  }
93}
94
95// 7. 联合类型和交叉类型
96type StringOrNumber = string | number
97type UserWithTimestamp = User & {
98  createdAt: Date
99  updatedAt: Date
100}
101
102// 判别联合类型
103interface LoadingState {
104  status: 'loading'
105}
106
107interface SuccessState {
108  status: 'success'
109  data: any
110}
111
112interface ErrorState {
113  status: 'error'
114  error: string
115}
116
117type AsyncState = LoadingState | SuccessState | ErrorState
118
119function handleState(state: AsyncState) {
120  switch (state.status) {
121    case 'loading':
122      console.log('Loading...')
123      break
124    case 'success':
125      console.log('Data:', state.data) // TypeScript知道这里有data属性
126      break
127    case 'error':
128      console.log('Error:', state.error) // TypeScript知道这里有error属性
129      break
130  }
131}
132
133// 8. 类型守卫
134function isString(value: unknown): value is string {
135  return typeof value === 'string'
136}
137
138function isUser(obj: any): obj is User {
139  return obj && 
140         typeof obj.id === 'number' &&
141         typeof obj.name === 'string' &&
142         typeof obj.age === 'number'
143}
144
145// 使用类型守卫
146function processValue(value: unknown) {
147  if (isString(value)) {
148    // TypeScript知道value是string类型
149    console.log(value.toUpperCase())
150  }
151  
152  if (isUser(value)) {
153    // TypeScript知道value是User类型
154    console.log(`User: ${value.name}, Age: ${value.age}`)
155  }
156}
157
158// 9. 类型断言
159const userInput = document.getElementById('user-input') as HTMLInputElement
160const apiResponse = JSON.parse('{"name": "John"}') as User
161
162// 非空断言
163function processUser(user: User | null) {
164  // 确定user不为null时使用
165  console.log(user!.name)
166}
167
168// 10. 类型缩窄
169function processStringOrNumber(value: string | number) {
170  if (typeof value === 'string') {
171    // 在这个分支中，TypeScript知道value是string
172    return value.toUpperCase()
173  } else {
174    // 在这个分支中，TypeScript知道value是number
175    return value.toFixed(2)
176  }
177}
178
179// 11. never类型
180function throwError(message: string): never {
181  throw new Error(message)
182}
183
184function exhaustiveCheck(value: never): never {
185  throw new Error(`Unexpected value: ${value}`)
186}
187
188// 在switch语句中使用never确保完整性
189function handleTheme(theme: Theme) {
190  switch (theme) {
191    case 'light':
192      return 'Light theme'
193    case 'dark':
194      return 'Dark theme'
195    case 'auto':
196      return 'Auto theme'
197    default:
198      // 如果添加新的Theme值但忘记处理，TypeScript会报错
199      return exhaustiveCheck(theme)
200  }
201}

接口与类型别名

接口设计与类型别名

接口与类型别名最佳实践

typescript

1// 1. 基础接口定义
2interface BaseEntity {
3  readonly id: string
4  createdAt: Date
5  updatedAt: Date
6}
7
8interface User extends BaseEntity {
9  name: string
10  email: string
11  age?: number
12  avatar?: string
13  status: 'active' | 'inactive' | 'pending'
14}
15
16// 2. 可选属性和只读属性
17interface UserPreferences {
18  readonly userId: string
19  theme?: 'light' | 'dark' | 'auto'
20  language?: string
21  notifications?: {
22    email: boolean
23    push: boolean
24    sms: boolean
25  }
26}
27
28// 3. 索引签名
29interface ApiResponse<T = any> {
30  success: boolean
31  data?: T
32  error?: string
33  meta?: {
34    [key: string]: any
35  }
36}
37
38// 4. 函数接口
39interface EventEmitter {
40  on(event: string, listener: (...args: any[]) => void): void
41  off(event: string, listener: (...args: any[]) => void): void
42  emit(event: string, ...args: any[]): void
43}
44
45interface HttpClient {
46  get<T>(url: string, config?: RequestConfig): Promise<ApiResponse<T>>
47  post<T>(url: string, data?: any, config?: RequestConfig): Promise<ApiResponse<T>>
48  put<T>(url: string, data?: any, config?: RequestConfig): Promise<ApiResponse<T>>
49  delete<T>(url: string, config?: RequestConfig): Promise<ApiResponse<T>>
50}
51
52// 5. 接口继承和组合
53interface Timestamped {
54  createdAt: Date
55  updatedAt: Date
56}
57
58interface Auditable {
59  createdBy: string
60  updatedBy: string
61}
62
63interface Post extends BaseEntity, Auditable {
64  title: string
65  content: string
66  author: User
67  tags: string[]
68  published: boolean
69}
70
71// 6. 类型别名 vs 接口
72// 类型别名 - 适用于联合类型、原始类型、计算类型
73type Status = 'loading' | 'success' | 'error'
74type EventHandler<T> = (event: T) => void
75type DeepReadonly<T> = {
76  readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P]
77}
78
79// 接口 - 适用于对象形状定义、类实现、声明合并
80interface UserService {
81  getUser(id: string): Promise<User>
82  updateUser(id: string, updates: Partial<User>): Promise<User>
83  deleteUser(id: string): Promise<void>
84}
85
86// 7. 声明合并
87interface Window {
88  customProperty: string
89}
90
91interface Window {
92  anotherProperty: number
93}
94
95// 现在Window接口包含两个属性
96
97// 8. 条件类型和映射类型
98type NonNullable<T> = T extends null | undefined ? never : T
99type Partial<T> = {
100  [P in keyof T]?: T[P]
101}
102
103type Required<T> = {
104  [P in keyof T]-?: T[P]
105}
106
107type Pick<T, K extends keyof T> = {
108  [P in K]: T[P]
109}
110
111type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>
112
113// 9. 实用工具类型应用
114type UserCreateInput = Omit<User, 'id' | 'createdAt' | 'updatedAt'>
115type UserUpdateInput = Partial<Pick<User, 'name' | 'email' | 'age' | 'avatar'>>
116type UserPublicInfo = Pick<User, 'id' | 'name' | 'avatar'>
117
118// 10. 高级类型模式
119// 递归类型
120type DeepPartial<T> = {
121  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P]
122}
123
124// 模板字面量类型
125type EventName<T extends string> = `on${Capitalize<T>}`
126type ApiEndpoint<T extends string> = `/api/${T}`
127
128type UserEvents = EventName<'userCreated' | 'userUpdated' | 'userDeleted'>
129// 结果: 'onUserCreated' | 'onUserUpdated' | 'onUserDeleted'
130
131// 11. 品牌类型（Branded Types）
132type UserId = string & { readonly brand: unique symbol }
133type Email = string & { readonly brand: unique symbol }
134
135function createUserId(id: string): UserId {
136  return id as UserId
137}
138
139function createEmail(email: string): Email {
140  if (!email.includes('@')) {
141    throw new Error('Invalid email')
142  }
143  return email as Email
144}
145
146// 12. 类型安全的事件系统
147interface EventMap {
148  'user:created': { user: User }
149  'user:updated': { user: User; changes: Partial<User> }
150  'user:deleted': { userId: string }
151  'system:error': { error: Error; context?: string }
152}
153
154class TypedEventEmitter {
155  private listeners: {
156    [K in keyof EventMap]?: Array<(data: EventMap[K]) => void>
157  } = {}
158
159  on<K extends keyof EventMap>(
160    event: K,
161    listener: (data: EventMap[K]) => void
162  ): void {
163    if (!this.listeners[event]) {
164      this.listeners[event] = []
165    }
166    this.listeners[event]!.push(listener)
167  }
168
169  emit<K extends keyof EventMap>(event: K, data: EventMap[K]): void {
170    const eventListeners = this.listeners[event]
171    if (eventListeners) {
172      eventListeners.forEach(listener => listener(data))
173    }
174  }
175
176  off<K extends keyof EventMap>(
177    event: K,
178    listener: (data: EventMap[K]) => void
179  ): void {
180    const eventListeners = this.listeners[event]
181    if (eventListeners) {
182      const index = eventListeners.indexOf(listener)
183      if (index > -1) {
184        eventListeners.splice(index, 1)
185      }
186    }
187  }
188}
189
190// 使用示例
191const eventEmitter = new TypedEventEmitter()
192
193eventEmitter.on('user:created', (data) => {
194  // data的类型自动推断为 { user: User }
195  console.log(`User created: ${data.user.name}`)
196})
197
198eventEmitter.emit('user:created', {
199  user: {
200    id: '1',
201    name: 'John',
202    email: 'john@example.com',
203    status: 'active',
204    createdAt: new Date(),
205    updatedAt: new Date()
206  }
207})
208
209// 13. API客户端类型安全
210interface ApiEndpoints {
211  'GET /users': {
212    response: User[]
213  }
214  'GET /users/:id': {
215    params: { id: string }
216    response: User
217  }
218  'POST /users': {
219    body: UserCreateInput
220    response: User
221  }
222  'PUT /users/:id': {
223    params: { id: string }
224    body: UserUpdateInput
225    response: User
226  }
227  'DELETE /users/:id': {
228    params: { id: string }
229    response: void
230  }
231}
232
233type ExtractParams<T> = T extends { params: infer P } ? P : never
234type ExtractBody<T> = T extends { body: infer B } ? B : never
235type ExtractResponse<T> = T extends { response: infer R } ? R : never
236
237class TypedApiClient {
238  async request<K extends keyof ApiEndpoints>(
239    endpoint: K,
240    options?: {
241      params?: ExtractParams<ApiEndpoints[K]>
242      body?: ExtractBody<ApiEndpoints[K]>
243    }
244  ): Promise<ExtractResponse<ApiEndpoints[K]>> {
245    // 实际的HTTP请求实现
246    throw new Error('Not implemented')
247  }
248}
249
250// 使用示例
251const apiClient = new TypedApiClient()
252
253// TypeScript会自动推断参数和返回类型
254const user = await apiClient.request('GET /users/:id', {
255  params: { id: '123' }
256}) // user的类型是User
257
258const newUser = await apiClient.request('POST /users', {
259  body: {
260    name: 'John',
261    email: 'john@example.com',
262    status: 'active'
263  }
264}) // newUser的类型是User

泛型系统

泛型编程与类型约束

泛型系统深度应用

typescript

1// 1. 基础泛型
2function identity<T>(arg: T): T {
3  return arg
4}
5
6// 泛型接口
7interface GenericResponse<T> {
8  data: T
9  success: boolean
10  message?: string
11}
12
13// 泛型类
14class GenericRepository<T, K = string> {
15  private items: Map<K, T> = new Map()
16
17  add(key: K, item: T): void {
18    this.items.set(key, item)
19  }
20
21  get(key: K): T | undefined {
22    return this.items.get(key)
23  }
24
25  getAll(): T[] {
26    return Array.from(this.items.values())
27  }
28
29  delete(key: K): boolean {
30    return this.items.delete(key)
31  }
32}
33
34// 2. 泛型约束
35interface Lengthwise {
36  length: number
37}
38
39function loggingIdentity<T extends Lengthwise>(arg: T): T {
40  console.log(arg.length) // 现在我们知道arg有length属性
41  return arg
42}
43
44// 使用类型参数约束
45function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
46  return obj[key]
47}
48
49const person = { name: 'John', age: 30, email: 'john@example.com' }
50const name = getProperty(person, 'name') // string类型
51const age = getProperty(person, 'age')   // number类型
52
53// 3. 条件类型
54type NonNullable<T> = T extends null | undefined ? never : T
55type ReturnType<T> = T extends (...args: any[]) => infer R ? R : any
56type Parameters<T> = T extends (...args: infer P) => any ? P : never
57
58// 自定义条件类型
59type IsArray<T> = T extends any[] ? true : false
60type ArrayElement<T> = T extends (infer U)[] ? U : never
61
62type Test1 = IsArray<string[]>  // true
63type Test2 = IsArray<string>    // false
64type Test3 = ArrayElement<User[]> // User
65
66// 4. 映射类型
67type Readonly<T> = {
68  readonly [P in keyof T]: T[P]
69}
70
71type Partial<T> = {
72  [P in keyof T]?: T[P]
73}
74
75type Nullable<T> = {
76  [P in keyof T]: T[P] | null
77}
78
79// 高级映射类型
80type DeepReadonly<T> = {
81  readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P]
82}
83
84type OptionalKeys<T> = {
85  [K in keyof T]-?: {} extends Pick<T, K> ? K : never
86}[keyof T]
87
88type RequiredKeys<T> = {
89  [K in keyof T]-?: {} extends Pick<T, K> ? never : K
90}[keyof T]
91
92// 5. 实用泛型工具
93// 深度合并类型
94type DeepMerge<T, U> = {
95  [K in keyof T | keyof U]: K extends keyof U
96    ? K extends keyof T
97      ? T[K] extends object
98        ? U[K] extends object
99          ? DeepMerge<T[K], U[K]>
100          : U[K]
101        : U[K]
102      : U[K]
103    : K extends keyof T
104    ? T[K]
105    : never
106}
107
108// 类型安全的对象更新
109function updateObject<T, U extends Partial<T>>(
110  original: T,
111  updates: U
112): T & U {
113  return { ...original, ...updates }
114}
115
116// 6. 高阶函数泛型
117// 函数组合
118function compose<A, B, C>(
119  f: (b: B) => C,
120  g: (a: A) => B
121): (a: A) => C {
122  return (a: A) => f(g(a))
123}
124
125// 管道操作
126function pipe<T>(...fns: Array<(arg: T) => T>): (arg: T) => T {
127  return (arg: T) => fns.reduce((acc, fn) => fn(acc), arg)
128}
129
130// 柯里化
131function curry<A, B, C>(
132  fn: (a: A, b: B) => C
133): (a: A) => (b: B) => C {
134  return (a: A) => (b: B) => fn(a, b)
135}
136
137// 7. 异步泛型模式
138// Promise工具类型
139type PromiseValue<T> = T extends Promise<infer U> ? U : T
140type AwaitedReturnType<T> = T extends (...args: any[]) => Promise<infer R> ? R : never
141
142// 异步数据获取器
143class AsyncDataFetcher<T> {
144  private cache = new Map<string, T>()
145
146  async fetch<K extends keyof T>(
147    key: K,
148    fetcher: () => Promise<T[K]>
149  ): Promise<T[K]> {
150    const cacheKey = String(key)
151    
152    if (this.cache.has(cacheKey)) {
153      return this.cache.get(cacheKey) as T[K]
154    }
155
156    const data = await fetcher()
157    this.cache.set(cacheKey, data as any)
158    return data
159  }
160
161  invalidate<K extends keyof T>(key: K): void {
162    this.cache.delete(String(key))
163  }
164
165  clear(): void {
166    this.cache.clear()
167  }
168}
169
170// 8. 状态管理泛型
171interface State {
172  user: User | null
173  posts: Post[]
174  loading: boolean
175  error: string | null
176}
177
178type Action<T extends keyof State> = {
179  type: T
180  payload: State[T]
181}
182
183type ActionCreator<T extends keyof State> = (payload: State[T]) => Action<T>
184
185function createActionCreator<T extends keyof State>(
186  type: T
187): ActionCreator<T> {
188  return (payload: State[T]) => ({ type, payload })
189}
190
191// 使用示例
192const setUser = createActionCreator('user')
193const setPosts = createActionCreator('posts')
194const setLoading = createActionCreator('loading')
195
196// 9. 表单验证泛型
197type ValidationRule<T> = (value: T) => string | null
198type ValidationRules<T> = {
199  [K in keyof T]?: ValidationRule<T[K]>[]
200}
201
202type ValidationErrors<T> = {
203  [K in keyof T]?: string
204}
205
206class FormValidator<T extends Record<string, any>> {
207  constructor(private rules: ValidationRules<T>) {}
208
209  validate(data: T): ValidationErrors<T> {
210    const errors: ValidationErrors<T> = {}
211
212    for (const key in this.rules) {
213      const fieldRules = this.rules[key]
214      if (fieldRules) {
215        for (const rule of fieldRules) {
216          const error = rule(data[key])
217          if (error) {
218            errors[key] = error
219            break // 只显示第一个错误
220          }
221        }
222      }
223    }
224
225    return errors
226  }
227
228  isValid(data: T): boolean {
229    const errors = this.validate(data)
230    return Object.keys(errors).length === 0
231  }
232}
233
234// 使用示例
235interface UserForm {
236  name: string
237  email: string
238  age: number
239}
240
241const userValidator = new FormValidator<UserForm>({
242  name: [
243    (value) => value.length === 0 ? '姓名不能为空' : null,
244    (value) => value.length < 2 ? '姓名至少2个字符' : null
245  ],
246  email: [
247    (value) => value.length === 0 ? '邮箱不能为空' : null,
248    (value) => !value.includes('@') ? '邮箱格式不正确' : null
249  ],
250  age: [
251    (value) => value < 0 ? '年龄不能为负数' : null,
252    (value) => value > 150 ? '年龄不能超过150' : null
253  ]
254})
255
256// 10. 类型安全的事件总线
257type EventBusEvents = {
258  'user:login': { user: User }
259  'user:logout': { userId: string }
260  'post:created': { post: Post }
261  'post:updated': { post: Post; changes: Partial<Post> }
262}
263
264class TypeSafeEventBus {
265  private listeners: {
266    [K in keyof EventBusEvents]?: Set<(data: EventBusEvents[K]) => void>
267  } = {}
268
269  on<K extends keyof EventBusEvents>(
270    event: K,
271    listener: (data: EventBusEvents[K]) => void
272  ): () => void {
273    if (!this.listeners[event]) {
274      this.listeners[event] = new Set()
275    }
276    
277    this.listeners[event]!.add(listener)
278    
279    // 返回取消订阅函数
280    return () => {
281      this.listeners[event]?.delete(listener)
282    }
283  }
284
285  emit<K extends keyof EventBusEvents>(
286    event: K,
287    data: EventBusEvents[K]
288  ): void {
289    const eventListeners = this.listeners[event]
290    if (eventListeners) {
291      eventListeners.forEach(listener => listener(data))
292    }
293  }
294
295  once<K extends keyof EventBusEvents>(
296    event: K,
297    listener: (data: EventBusEvents[K]) => void
298  ): void {
299    const onceListener = (data: EventBusEvents[K]) => {
300      listener(data)
301      this.listeners[event]?.delete(onceListener)
302    }
303    
304    this.on(event, onceListener)
305  }
306}
307
308// 使用示例
309const eventBus = new TypeSafeEventBus()
310
311const unsubscribe = eventBus.on('user:login', (data) => {
312  console.log(`User ${data.user.name} logged in`)
313})
314
315eventBus.emit('user:login', {
316  user: {
317    id: '1',
318    name: 'John',
319    email: 'john@example.com',
320    status: 'active',
321    createdAt: new Date(),
322    updatedAt: new Date()
323  }
324})
325
326// 取消订阅
327unsubscribe()

2. TypeScript工程化配置

2.1 编译配置与优化

TypeScript的编译配置是项目工程化的重要组成部分，合理的配置可以提升开发体验和构建性能。

编译配置对比

配置项	开发环境	生产环境	说明
target	ES2020	ES2018	编译目标版本
module	ESNext	CommonJS	模块系统
sourceMap	true	false	源码映射
strict	true	true	严格模式
incremental	true	false	增量编译
skipLibCheck	true	true	跳过库检查

配置文件

完整的tsconfig.json配置

tsconfig.json完整配置

json

1{
2  "compilerOptions": {
3    // 基础配置
4    "target": "ES2020",
5    "module": "ESNext",
6    "lib": ["ES2020", "DOM", "DOM.Iterable"],
7    "moduleResolution": "node",
8    "allowJs": true,
9    "checkJs": false,
10    "jsx": "react-jsx",
11    
12    // 输出配置
13    "outDir": "./dist",
14    "rootDir": "./src",
15    "removeComments": true,
16    "noEmit": false,
17    "importHelpers": true,
18    "downlevelIteration": true,
19    "isolatedModules": true,
20    
21    // 源码映射
22    "sourceMap": true,
23    "inlineSourceMap": false,
24    "declarationMap": true,
25    
26    // 声明文件
27    "declaration": true,
28    "declarationDir": "./types",
29    "emitDeclarationOnly": false,
30    
31    // 严格检查
32    "strict": true,
33    "noImplicitAny": true,
34    "strictNullChecks": true,
35    "strictFunctionTypes": true,
36    "strictBindCallApply": true,
37    "strictPropertyInitialization": true,
38    "noImplicitThis": true,
39    "noImplicitReturns": true,
40    "noFallthroughCasesInSwitch": true,
41    "noUncheckedIndexedAccess": true,
42    
43    // 额外检查
44    "noUnusedLocals": true,
45    "noUnusedParameters": true,
46    "exactOptionalPropertyTypes": true,
47    "noImplicitOverride": true,
48    "noPropertyAccessFromIndexSignature": true,
49    
50    // 模块解析
51    "baseUrl": "./",
52    "paths": {
53      "@/*": ["src/*"],
54      "@/components/*": ["src/components/*"],
55      "@/utils/*": ["src/utils/*"],
56      "@/types/*": ["src/types/*"],
57      "@/hooks/*": ["src/hooks/*"],
58      "@/stores/*": ["src/stores/*"],
59      "@/services/*": ["src/services/*"]
60    },
61    "typeRoots": ["./node_modules/@types", "./src/types"],
62    "types": ["node", "jest", "@testing-library/jest-dom"],
63    
64    // 性能优化
65    "incremental": true,
66    "tsBuildInfoFile": "./node_modules/.cache/typescript/tsbuildinfo",
67    "skipLibCheck": true,
68    "skipDefaultLibCheck": true,
69    
70    // 互操作性
71    "esModuleInterop": true,
72    "allowSyntheticDefaultImports": true,
73    "forceConsistentCasingInFileNames": true,
74    "resolveJsonModule": true,
75    
76    // 实验性功能
77    "experimentalDecorators": true,
78    "emitDecoratorMetadata": true,
79    "useDefineForClassFields": true
80  },
81  
82  // 包含和排除
83  "include": [
84    "src/**/*",
85    "tests/**/*",
86    "*.d.ts"
87  ],
88  "exclude": [
89    "node_modules",
90    "dist",
91    "build",
92    "coverage",
93    "**/*.spec.ts",
94    "**/*.test.ts"
95  ],
96  
97  // 项目引用
98  "references": [
99    { "path": "./packages/shared" },
100    { "path": "./packages/utils" }
101  ],
102  
103  // 监听配置
104  "watchOptions": {
105    "watchFile": "useFsEvents",
106    "watchDirectory": "useFsEvents",
107    "fallbackPolling": "dynamicPriority",
108    "synchronousWatchDirectory": true,
109    "excludeDirectories": ["**/node_modules", "dist"]
110  },
111  
112  // TypeScript 4.9+ 配置
113  "compilerOptions": {
114    "moduleDetection": "auto",
115    "allowImportingTsExtensions": false,
116    "allowArbitraryExtensions": false
117  }
118}

环境特定配置

tsconfig.dev.json - 开发环境配置

json

1{
2  "extends": "./tsconfig.json",
3  "compilerOptions": {
4    "target": "ES2022",
5    "module": "ESNext",
6    "sourceMap": true,
7    "incremental": true,
8    "noEmit": true,
9    "preserveWatchOutput": true,
10    
11    // 开发时放宽的检查
12    "noUnusedLocals": false,
13    "noUnusedParameters": false,
14    "skipLibCheck": true
15  },
16  "include": [
17    "src/**/*",
18    "tests/**/*",
19    "vite.config.ts",
20    "vitest.config.ts"
21  ]
22}

tsconfig.build.json - 构建配置

json

1{
2  "extends": "./tsconfig.json",
3  "compilerOptions": {
4    "target": "ES2018",
5    "module": "CommonJS",
6    "sourceMap": false,
7    "incremental": false,
8    "removeComments": true,
9    "declaration": true,
10    "declarationMap": false,
11    
12    // 生产构建优化
13    "noEmitOnError": true,
14    "listEmittedFiles": true,
15    "listFiles": false
16  },
17  "exclude": [
18    "src/**/*.test.ts",
19    "src/**/*.spec.ts",
20    "src/**/*.stories.ts",
21    "tests/**/*"
22  ]
23}

项目结构

TypeScript项目结构最佳实践

项目结构与类型组织

typescript

1// src/types/index.ts - 全局类型定义
2export interface BaseEntity {
3  id: string
4  createdAt: Date
5  updatedAt: Date
6}
7
8export interface User extends BaseEntity {
9  name: string
10  email: string
11  role: UserRole
12  status: UserStatus
13}
14
15export type UserRole = 'admin' | 'user' | 'guest'
16export type UserStatus = 'active' | 'inactive' | 'pending'
17
18// API相关类型
19export interface ApiResponse<T = any> {
20  success: boolean
21  data?: T
22  error?: ApiError
23  meta?: ApiMeta
24}
25
26export interface ApiError {
27  code: string
28  message: string
29  details?: Record<string, any>
30}
31
32export interface ApiMeta {
33  page?: number
34  limit?: number
35  total?: number
36  hasMore?: boolean
37}
38
39// src/types/api.ts - API类型定义
40import { User, ApiResponse } from './index'
41
42export namespace UserAPI {
43  export interface GetUsersRequest {
44    page?: number
45    limit?: number
46    search?: string
47    role?: UserRole
48    status?: UserStatus
49  }
50
51  export interface GetUsersResponse extends ApiResponse<User[]> {
52    meta: {
53      page: number
54      limit: number
55      total: number
56      hasMore: boolean
57    }
58  }
59
60  export interface CreateUserRequest {
61    name: string
62    email: string
63    role: UserRole
64  }
65
66  export interface UpdateUserRequest {
67    name?: string
68    email?: string
69    role?: UserRole
70    status?: UserStatus
71  }
72}
73
74// src/types/components.ts - 组件类型定义
75import { ReactNode, HTMLAttributes } from 'react'
76
77export interface BaseComponentProps {
78  className?: string
79  children?: ReactNode
80  testId?: string
81}
82
83export interface ButtonProps extends BaseComponentProps {
84  variant?: 'primary' | 'secondary' | 'danger'
85  size?: 'small' | 'medium' | 'large'
86  disabled?: boolean
87  loading?: boolean
88  onClick?: () => void
89}
90
91export interface ModalProps extends BaseComponentProps {
92  visible: boolean
93  title?: string
94  width?: number | string
95  closable?: boolean
96  onClose?: () => void
97  onCancel?: () => void
98  onOk?: () => void
99}
100
101// src/utils/types.ts - 工具类型
102export type DeepPartial<T> = {
103  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P]
104}
105
106export type DeepRequired<T> = {
107  [P in keyof T]-?: T[P] extends object ? DeepRequired<T[P]> : T[P]
108}
109
110export type KeysOfType<T, U> = {
111  [K in keyof T]: T[K] extends U ? K : never
112}[keyof T]
113
114export type NonEmptyArray<T> = [T, ...T[]]
115
116export type Prettify<T> = {
117  [K in keyof T]: T[K]
118} & {}
119
120// 函数工具类型
121export type AsyncReturnType<T extends (...args: any) => Promise<any>> = 
122  T extends (...args: any) => Promise<infer R> ? R : any
123
124export type PromiseType<T> = T extends Promise<infer U> ? U : T
125
126// src/services/types.ts - 服务类型定义
127export interface HttpClientConfig {
128  baseURL: string
129  timeout: number
130  headers?: Record<string, string>
131  interceptors?: {
132    request?: (config: any) => any
133    response?: (response: any) => any
134    error?: (error: any) => any
135  }
136}
137
138export interface CacheConfig {
139  ttl: number
140  maxSize: number
141  strategy: 'lru' | 'fifo' | 'lfu'
142}
143
144export interface ServiceConfig {
145  http: HttpClientConfig
146  cache: CacheConfig
147  retry: {
148    attempts: number
149    delay: number
150    backoff: 'linear' | 'exponential'
151  }
152}
153
154// src/hooks/types.ts - Hook类型定义
155export interface UseApiOptions<T> {
156  initialData?: T
157  enabled?: boolean
158  refetchOnWindowFocus?: boolean
159  refetchInterval?: number
160  onSuccess?: (data: T) => void
161  onError?: (error: Error) => void
162}
163
164export interface UseApiResult<T> {
165  data: T | undefined
166  loading: boolean
167  error: Error | null
168  refetch: () => Promise<void>
169  mutate: (data: T) => void
170}
171
172export interface UsePaginationOptions {
173  initialPage?: number
174  initialPageSize?: number
175  total?: number
176}
177
178export interface UsePaginationResult {
179  page: number
180  pageSize: number
181  total: number
182  totalPages: number
183  hasNext: boolean
184  hasPrev: boolean
185  goToPage: (page: number) => void
186  nextPage: () => void
187  prevPage: () => void
188  setPageSize: (size: number) => void
189}
190
191// src/stores/types.ts - 状态管理类型
192export interface RootState {
193  user: UserState
194  app: AppState
195  ui: UIState
196}
197
198export interface UserState {
199  currentUser: User | null
200  loading: boolean
201  error: string | null
202}
203
204export interface AppState {
205  theme: 'light' | 'dark' | 'auto'
206  language: string
207  sidebarCollapsed: boolean
208}
209
210export interface UIState {
211  notifications: Notification[]
212  modals: Modal[]
213  loading: Record<string, boolean>
214}
215
216// 动作类型
217export type UserAction = 
218  | { type: 'USER_LOGIN_START' }
219  | { type: 'USER_LOGIN_SUCCESS'; payload: User }
220  | { type: 'USER_LOGIN_FAILURE'; payload: string }
221  | { type: 'USER_LOGOUT' }
222  | { type: 'USER_UPDATE'; payload: Partial<User> }
223
224// src/constants/types.ts - 常量类型
225export const HTTP_STATUS = {
226  OK: 200,
227  CREATED: 201,
228  BAD_REQUEST: 400,
229  UNAUTHORIZED: 401,
230  FORBIDDEN: 403,
231  NOT_FOUND: 404,
232  INTERNAL_SERVER_ERROR: 500
233} as const
234
235export type HttpStatus = typeof HTTP_STATUS[keyof typeof HTTP_STATUS]
236
237export const USER_ROLES = {
238  ADMIN: 'admin',
239  USER: 'user',
240  GUEST: 'guest'
241} as const
242
243export type UserRole = typeof USER_ROLES[keyof typeof USER_ROLES]
244
245// 环境变量类型
246declare global {
247  namespace NodeJS {
248    interface ProcessEnv {
249      NODE_ENV: 'development' | 'production' | 'test'
250      REACT_APP_API_URL: string
251      REACT_APP_APP_NAME: string
252      REACT_APP_VERSION: string
253    }
254  }
255}
256
257// 扩展第三方库类型
258declare module 'react' {
259  interface HTMLAttributes<T> {
260    'data-testid'?: string
261  }
262}
263
264declare module '*.svg' {
265  const content: React.FunctionComponent<React.SVGAttributes<SVGElement>>
266  export default content
267}
268
269declare module '*.png' {
270  const content: string
271  export default content
272}
273
274declare module '*.jpg' {
275  const content: string
276  export default content
277}

构建工具集成

构建工具与TypeScript集成

Vite + TypeScript配置

typescript

1// vite.config.ts
2import { defineConfig } from 'vite'
3import react from '@vitejs/plugin-react'
4import { resolve } from 'path'
5import dts from 'vite-plugin-dts'
6import { visualizer } from 'rollup-plugin-visualizer'
7
8export default defineConfig({
9  plugins: [
10    react(),
11    
12    // 生成类型声明文件
13    dts({
14      insertTypesEntry: true,
15      include: ['src/**/*'],
16      exclude: ['src/**/*.test.ts', 'src/**/*.spec.ts']
17    }),
18    
19    // 构建分析
20    visualizer({
21      filename: 'dist/stats.html',
22      open: true,
23      gzipSize: true
24    })
25  ],
26  
27  // 路径别名
28  resolve: {
29    alias: {
30      '@': resolve(__dirname, 'src'),
31      '@/components': resolve(__dirname, 'src/components'),
32      '@/utils': resolve(__dirname, 'src/utils'),
33      '@/types': resolve(__dirname, 'src/types'),
34      '@/hooks': resolve(__dirname, 'src/hooks'),
35      '@/stores': resolve(__dirname, 'src/stores'),
36      '@/services': resolve(__dirname, 'src/services')
37    }
38  },
39  
40  // 构建配置
41  build: {
42    target: 'es2018',
43    lib: {
44      entry: resolve(__dirname, 'src/index.ts'),
45      name: 'MyLibrary',
46      formats: ['es', 'cjs', 'umd']
47    },
48    rollupOptions: {
49      external: ['react', 'react-dom'],
50      output: {
51        globals: {
52          react: 'React',
53          'react-dom': 'ReactDOM'
54        }
55      }
56    },
57    sourcemap: true,
58    minify: 'terser',
59    terserOptions: {
60      compress: {
61        drop_console: true,
62        drop_debugger: true
63      }
64    }
65  },
66  
67  // 开发服务器
68  server: {
69    port: 3000,
70    open: true,
71    cors: true
72  },
73  
74  // 环境变量
75  define: {
76    __APP_VERSION__: JSON.stringify(process.env.npm_package_version)
77  }
78})
79
80// webpack.config.ts (如果使用Webpack)
81import path from 'path'
82import { Configuration } from 'webpack'
83import HtmlWebpackPlugin from 'html-webpack-plugin'
84import MiniCssExtractPlugin from 'mini-css-extract-plugin'
85import ForkTsCheckerWebpackPlugin from 'fork-ts-checker-webpack-plugin'
86
87const config: Configuration = {
88  entry: './src/index.tsx',
89  
90  output: {
91    path: path.resolve(__dirname, 'dist'),
92    filename: '[name].[contenthash].js',
93    clean: true
94  },
95  
96  resolve: {
97    extensions: ['.ts', '.tsx', '.js', '.jsx'],
98    alias: {
99      '@': path.resolve(__dirname, 'src'),
100      '@/components': path.resolve(__dirname, 'src/components'),
101      '@/utils': path.resolve(__dirname, 'src/utils'),
102      '@/types': path.resolve(__dirname, 'src/types')
103    }
104  },
105  
106  module: {
107    rules: [
108      {
109        test: /\.tsx?$/,
110        use: [
111          {
112            loader: 'ts-loader',
113            options: {
114              transpileOnly: true, // 类型检查交给ForkTsCheckerWebpackPlugin
115              configFile: 'tsconfig.build.json'
116            }
117          }
118        ],
119        exclude: /node_modules/
120      },
121      {
122        test: /\.css$/,
123        use: [
124          MiniCssExtractPlugin.loader,
125          'css-loader',
126          'postcss-loader'
127        ]
128      }
129    ]
130  },
131  
132  plugins: [
133    new HtmlWebpackPlugin({
134      template: './public/index.html'
135    }),
136    
137    new MiniCssExtractPlugin({
138      filename: '[name].[contenthash].css'
139    }),
140    
141    // TypeScript类型检查
142    new ForkTsCheckerWebpackPlugin({
143      typescript: {
144        configFile: 'tsconfig.build.json'
145      }
146    })
147  ],
148  
149  optimization: {
150    splitChunks: {
151      chunks: 'all',
152      cacheGroups: {
153        vendor: {
154          test: /[\\/]node_modules[\\/]/,
155          name: 'vendors',
156          chunks: 'all'
157        }
158      }
159    }
160  }
161}
162
163export default config
164
165// jest.config.ts - 测试配置
166import type { Config } from 'jest'
167
168const config: Config = {
169  preset: 'ts-jest',
170  testEnvironment: 'jsdom',
171  
172  // 模块解析
173  moduleNameMapping: {
174    '^@/(.*)$': '<rootDir>/src/$1'
175  },
176  
177  // 设置文件
178  setupFilesAfterEnv: ['<rootDir>/src/setupTests.ts'],
179  
180  // 覆盖率配置
181  collectCoverageFrom: [
182    'src/**/*.{ts,tsx}',
183    '!src/**/*.d.ts',
184    '!src/**/*.stories.{ts,tsx}',
185    '!src/index.tsx'
186  ],
187  
188  coverageThreshold: {
189    global: {
190      branches: 80,
191      functions: 80,
192      lines: 80,
193      statements: 80
194    }
195  },
196  
197  // 转换配置
198  transform: {
199    '^.+\\.tsx?$': ['ts-jest', {
200      tsconfig: 'tsconfig.json'
201    }]
202  },
203  
204  // 模块文件扩展名
205  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
206  
207  // 测试匹配模式
208  testMatch: [
209    '<rootDir>/src/**/__tests__/**/*.{ts,tsx}',
210    '<rootDir>/src/**/*.{test,spec}.{ts,tsx}'
211  ]
212}
213
214export default config
215
216// eslint.config.ts - ESLint配置
217import { defineConfig } from 'eslint-define-config'
218
219export default defineConfig({
220  root: true,
221  env: {
222    browser: true,
223    es2020: true,
224    node: true
225  },
226  
227  extends: [
228    'eslint:recommended',
229    '@typescript-eslint/recommended',
230    '@typescript-eslint/recommended-requiring-type-checking',
231    'plugin:react/recommended',
232    'plugin:react-hooks/recommended',
233    'plugin:jsx-a11y/recommended'
234  ],
235  
236  parser: '@typescript-eslint/parser',
237  parserOptions: {
238    ecmaVersion: 'latest',
239    sourceType: 'module',
240    project: ['./tsconfig.json'],
241    tsconfigRootDir: __dirname,
242    ecmaFeatures: {
243      jsx: true
244    }
245  },
246  
247  plugins: [
248    '@typescript-eslint',
249    'react',
250    'react-hooks',
251    'jsx-a11y'
252  ],
253  
254  rules: {
255    // TypeScript规则
256    '@typescript-eslint/no-unused-vars': 'error',
257    '@typescript-eslint/no-explicit-any': 'warn',
258    '@typescript-eslint/explicit-function-return-type': 'off',
259    '@typescript-eslint/explicit-module-boundary-types': 'off',
260    '@typescript-eslint/no-non-null-assertion': 'warn',
261    '@typescript-eslint/prefer-nullish-coalescing': 'error',
262    '@typescript-eslint/prefer-optional-chain': 'error',
263    
264    // React规则
265    'react/react-in-jsx-scope': 'off',
266    'react/prop-types': 'off',
267    'react-hooks/rules-of-hooks': 'error',
268    'react-hooks/exhaustive-deps': 'warn',
269    
270    // 通用规则
271    'no-console': 'warn',
272    'no-debugger': 'error',
273    'prefer-const': 'error',
274    'no-var': 'error'
275  },
276  
277  settings: {
278    react: {
279      version: 'detect'
280    }
281  },
282  
283  ignorePatterns: [
284    'dist',
285    'build',
286    'node_modules',
287    '*.config.js'
288  ]
289})

3. TypeScript最佳实践与模式

3.1 代码组织与架构模式

TypeScript的强类型特性为大型应用的架构设计提供了强有力的支持，合理的代码组织和架构模式至关重要。

架构模式对比

架构模式	适用规模	类型安全	维护成本	学习曲线
MVC	中小型	⭐⭐⭐	⭐⭐	⭐⭐
MVVM	中型	⭐⭐⭐⭐	⭐⭐⭐	⭐⭐⭐
Clean Architecture	大型	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
Hexagonal	大型	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐⭐
Modular Monolith	超大型	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐

3.2 性能优化策略

TypeScript编译器提供了多种优化选项，合理配置可以显著提升编译性能和运行时性能。

编译性能优化检查清单

优化策略	配置项	性能提升	适用场景
增量编译	incremental: true	⭐⭐⭐⭐	开发环境
跳过库检查	skipLibCheck: true	⭐⭐⭐⭐⭐	大型项目
项目引用	references	⭐⭐⭐⭐	多包项目
类型导入	import type	⭐⭐⭐	类型密集项目
路径映射	paths	⭐⭐	深层嵌套项目

TypeScript最佳实践原则

1. 类型优先：优先使用类型而不是any
2. 渐进式采用：从JavaScript逐步迁移到TypeScript
3. 严格模式：启用strict模式获得最佳类型安全
4. 工具集成：充分利用IDE和构建工具的TypeScript支持
5. 性能监控：定期检查编译性能和包大小
6. 团队规范：建立统一的TypeScript编码规范

---

TypeScript作为现代前端开发的重要工具，其强大的类型系统、丰富的语言特性和完善的工具链为大型应用开发提供了坚实的基础。通过掌握TypeScript的核心概念、工程化配置和最佳实践，可以显著提升代码质量、开发效率和团队协作水平。

评论