常见陷阱与最佳实践

// ❌ 返回 any，下游全部失去类型安全
function parseJSON(json: string): any { return JSON.parse(json) }
const data = parseJSON('{"name": "Willow"}')
data.age.toString()  // 💥 运行时爆炸，编译期无报错

// ✅ 返回 unknown，强制调用方做类型收窄
function parseJSON(json: string): unknown { return JSON.parse(json) }
const data = parseJSON('{"name": "Willow"}')
// data.age  // ❌ 编译错误
if (typeof data === 'object' && data !== null && 'name' in data) {
    console.log((data as { name: string }).name)  // ✅ 收窄后安全
}

interface User { name: string; age: number }

// ❌ 断言掩盖字段缺失
const user = { name: "Willow" } as User  // user.age 实际是 undefined

// ❌ 双重断言：完全绕过类型系统
const num = "hello" as unknown as number
num.toFixed(2)  // 💥 运行时爆炸

// ✅ 让 TS 做类型检查
const user: User = { name: "Willow", age: 18 }

// ✅ 用类型守卫替代断言
function isUser(obj: unknown): obj is User {
    return typeof obj === 'object' && obj !== null
        && 'name' in obj && 'age' in obj
}

interface User { name: string; age: number }

// ❌ 直接传字面量——多余属性检查生效
const u: User = { name: "Willow", age: 18, email: "a@b.com" }  // 报错

// ❌ 通过中间变量——检查被绕过，email 被静默丢弃
const temp = { name: "Willow", age: 18, email: "a@b.com" }
const u2: User = temp  // 不报错

// ❌ 函数参数同理
function createUser(u: User) {}
createUser({ name: "W", age: 18, email: "x" })  // 报错
createUser(temp)  // 不报错

// ❌ 非空断言滥用
function getName(user?: User): string {
    return user!.name  // user 是 undefined 时 💥 运行时崩溃
}

// ❌ 未处理 DOM 可空返回值 + 可选属性
const el = document.getElementById('app')
el.innerHTML = 'hello'  // strictNullChecks 下报错
const port = config.database.port  // database 可能为 undefined

// ✅ 类型守卫
function getName(user?: User): string {
    if (!user) throw new Error('user is required')
    return user.name
}

// ✅ 可选链 + 空值合并
const port = config.database?.port ?? 5432
document.getElementById('app')?.setAttribute('data-loaded', 'true')

// ❌ 该用 interface 时用了 type——失去声明合并
type User = { name: string; age: number }
// type User = { email: string }  // ❌ 报错 Duplicate identifier

// ❌ 该用 type 时硬用 interface——不支持联合类型
// interface Status = 'idle' | 'loading'  // 语法错误

// ✅ 对象形状用 interface（可扩展、IDE 友好）
interface User { name: string; age: number }

// ✅ 联合、元组、映射类型用 type
type Status = 'idle' | 'loading' | 'success' | 'error'
type ReadonlyUser = Readonly<User>

// ✅ 需声明合并时用 interface
declare global { interface Window { myLib: MyLibType } }

// ❌ 宽泛签名在前——覆盖了所有具体签名
function format(value: string | number): string
function format(value: string): string     // 永不匹配
function format(value: number): string     // 永不匹配

// ✅ 具体签名在前，实现签名在最后（不暴露）
function format(value: string): string
function format(value: number): string
function format(value: string | number): string {
    return String(value)
}

// ❌ 无约束——无法访问任何属性
function getLength<T>(arr: T): number {
    return arr.length  // ❌ 类型 T 上不存在 length
}

// ❌ 约束过紧——返回值丢失信息
function mergeObj<T extends object>(a: T, b: T): T {
    return { ...a, ...b }  // 返回类型丢失了 b 独有的属性
}

// ✅ 合适的约束 + 多泛型参数
function getLength<T extends { length: number }>(arr: T): number {
    return arr.length
}

function mergeObj<T extends object, U extends object>(a: T, b: U): T & U {
    return { ...a, ...b }
}

function getProperty<T, K extends keyof T>(obj: T, key: K): T[K] {
    return obj[key]
}

// ❌ 普通 enum——编译为 IIFE 对象
enum Color { Red, Green, Blue }

// ❌ const enum——esbuild/Vite 下可能报错
const enum Status { Active = 'active', Inactive = 'inactive' }

// ✅ 推荐：as const + 联合类型（零运行时，零兼容风险）
const Color = { Red: 'red', Green: 'green', Blue: 'blue' } as const
type Color = (typeof Color)[keyof typeof Color]  // 'red' | 'green' | 'blue'

function paint(color: Color) {}
paint(Color.Red)   // ✅ 有枚举的便利
paint('red')       // ✅ 也支持字符串字面量

// ❌ 直接访问 Error 属性——报错
try { riskyOperation() } catch (error) {
    console.log(error.message)  // ❌ unknown 上不存在 message
}

// ❌ 直接断言——不安全
try { riskyOperation() } catch (error) {
    console.log((error as Error).message)  // throw "oops" 时 .message 是 undefined
}

// ✅ 类型收窄
try { riskyOperation() } catch (error) {
    if (error instanceof Error) {
        console.log(error.message)  // ✅ 安全
    } else {
        console.log('Unknown error:', String(error))
    }
}

// ✅ 封装工具函数
function getErrorMessage(error: unknown): string {
    if (error instanceof Error) return error.message
    return String(error)
}

// ❌ 忘记泛型——current 为 null（只读），无法赋值
const ref = useRef(null)

// ✅ DOM ref（初始为 null）
const divRef = useRef<HTMLDivElement>(null)   // current: HTMLDivElement | null

// ✅ 可变值 ref（非空初始值）
const countRef = useRef<number>(0)            // current: number
countRef.current += 1

// ✅ 可变值 ref（初始为 null）
const intervalRef = useRef<number | null>(null)  // current: number | null
intervalRef.current = window.setInterval(tick, 1000)

// ❌ 直接访问——报错
const apiUrl = process.env.API_URL  // ❌ ProcessEnv 上不存在 API_URL

// ❌ 用 as 断言掩盖未设置的情况
const apiUrl = process.env.API_URL as string  // 变量未设置时实际是 undefined

// ✅ 声明扩展（src/types/env.d.ts）
declare namespace NodeJS {
    interface ProcessEnv {
        API_URL: string
        NODE_ENV: 'development' | 'production' | 'test'
        PORT?: string
    }
}

// ✅ Vite 项目（src/vite-env.d.ts）
/// <reference types="vite/client" />
interface ImportMetaEnv {
    readonly VITE_API_URL: string
}

interface User { name: string; age: number }

function renderUser(u: User) {}
renderUser({ name: "W", age: 18, email: "x" })  // ❌ 报错：多余属性

const obj = { name: "W", age: 18, email: "x" }
renderUser(obj)  // ✅ 不报错——email 被静默丢弃

// React 中同理
<UserCard user={{ name: "A", age: 18, extra: true }} />   // ❌ 报错
const userObj = { name: "A", age: 18, extra: true }
<UserCard user={userObj} />                                 // ✅ 不报错