any Is a Contagious Hole
The semantics of any are not "I do not know" but "turn off type checking here". Once a function returns any, inference degrades along the entire call chain: downstream variables become any, arguments stop being validated, renames no longer resolve, and refactoring turns fully manual.
If any exists only to work around a library missing type declarations, the right move is to build a narrow interface that fences the any at the boundary rather than letting it into business logic. Once inside, removal cost becomes exponential, because nobody can enumerate all affected call sites.
The usual degradation path is: one any, then any[] and Promise<any>, and finally an entire data flow with no protection. A quick test: if replacing any with unknown immediately explodes into a hundred errors, that chain lost type safety long ago.
// 反例：把 unknown 丢进业务层
function parse(input: string): any {
return JSON.parse(input)
}
// 正例：边界处收窄，内部保持类型安全
type Config = { port: number; host: string }
function parseConfig(input: string): Config {
const raw: unknown = JSON.parse(input)
if (typeof raw !== "object" || raw === null) throw new TypeError("config must be an object")
const port = (raw as Record<string, unknown>).port
const host = (raw as Record<string, unknown>).host
if (typeof port !== "number" || typeof host !== "string") {
throw new TypeError("config.port must be number and config.host must be string")
}
return { port, host }
}Discriminated Unions: Modeling the State Machine in the Type
When an object has several shapes (loading, success, failure), optional fields explode combinatorially: what if loading and error are both true? A discriminated union gives each branch a literal tag, so the compiler verifies that branches are exhaustive and that fields are not read in the wrong branch.
The biggest payoff is exhaustiveness checking on switch. Once you enumerate every tag of the union, omitting one branch makes a never assertion fail to compile. Adding a new state then produces a compile error listing every switch that needs updating, instead of a runtime surprise.
Put the never assertion in the default branch as const _exhaustive: never = state, not inside each case. Written per-case, an assertion narrows to {} and quietly stops protecting anything.
type RequestState =
| { status: "idle" }
| { status: "loading"; startedAt: number }
| { status: "success"; data: string }
| { status: "error"; message: string }
function render(state: RequestState): string {
switch (state.status) {
case "idle":
return "尚未开始"
case "loading":
return `已耗时 ${Date.now() - state.startedAt}ms`
case "success":
return state.data
case "error":
return `失败：${state.message}`
default: {
const _exhaustive: never = state
return _exhaustive
}
}
}
// 新增 { status: "cancelled" } 后，所有遗漏分支的 switch 都会编译报错Generic Constraints: Making an API State Its Real Requirements
A bare <T> is <T> plus a hidden any: property access inside the function compiles fine, but callers may pass a primitive. Writing T extends Record<string, unknown> is only the start — the real payoff is tying the constraint to the return type so T's capabilities propagate outward.
Three patterns recur in practice: constraint plus default (a usable starting point for callers), constraint plus index signature (arbitrary keys but controlled value types), and conditional types mapping input to output (like ReturnType or a framework MaybePromise<T>). The third is the most abused because it easily destroys compile times.
The value of constraints is early failure. A well-constrained generic rejects bad calls at compile time, stopping errors at the boundary; an unconstrained one defers them to runtime, sometimes to production.
type Mapper<T extends Record<string, unknown>> = {
keys: () => Array<keyof T>
get<K extends keyof T>(key: K): T[K] | undefined
set<K extends keyof T>(key: K, value: T[K]): Mapper<T>
}
function createMapper<T extends Record<string, unknown> = { id: string }>(initial: T): Mapper<T> {
const store = new Map<keyof T, T[keyof T]>(Object.entries(initial) as Array<[keyof T, T[keyof T]]>)
return {
keys: () => Array.from(store.keys()),
get: (key) => store.get(key),
set: (key, value) => {
store.set(key, value)
return createMapper(Object.fromEntries(store) as T)
},
}
}
// 传入 number 会立刻报错：Mapper<number> 不满足 Record<string, unknown>Why Narrowing Fails: Five Common Breakpoints
First: narrowing an optional property with if (obj.key) while forgetting the undefined branch. Second: using typeof or a bare truthiness check on an array, since TypeScript auto-narrows only a limited set of forms. Third and most subtle: TS does not carry a branch across statements for an already-declared union variable, so an explicit assertion or a fresh check is required.
Fourth: let versus const. TypeScript assumes a let holding a union may be reassigned between function calls, so it refuses to keep the narrowing; switching to const, or binding a new const inside the branch, lets narrowing through.
Fifth: mixing imported type and interface so structural identity breaks, and @ts-expect-error silently burying real errors. Use a fixed debugging order: confirm the binding is const, confirm the discriminant is a literal type (not string), and only then reach for as.
type Box = { kind: "a"; a: number } | { kind: "b"; b: string }
// 失败写法：kind 声明成 string，无法收窄
function bad(box: { kind: string }) {
if (box.kind === "a") {
// 这里 box.a 不存在，因为 kind 不是字面量类型
}
}
// 正确写法：用 as 收窄到联合类型
function good(box: Box) {
if (box.kind === "a") {
return box.a + 1
}
return box.b.length
}
// 排查三连：const 了吗？kind 是字面量吗？分支赋值过吗？Wiring Type Constraints into the Engineering Loop
Type design only survives contact with reality through three hard settings: full strict: true, noUncheckedIndexedAccess: true so array and index access admits undefined, and making @typescript-eslint/no-explicit-any and ban-ts-comment errors so neither any nor @ts-ignore slips in quietly.
The second key is controlling what crosses the public API boundary. Internal code may use assertions freely, but any type reused across packages should be an explicitly declared interface. Never export typeof response from a backend payload — internal field changes then break every downstream consumer with no compile-time signal.
Finally use satisfies for bidirectional checking: the object must satisfy the target type while its inferred literal types are preserved. For route tables and event maps that need both correctness and concrete keys, satisfies beats as const because it does not lie on your behalf.
// tsconfig.json 关键项
{
"compilerOptions": {
"strict": true,
"noUncheckedIndexedAccess": true,
"noImplicitOverride": true,
"exactOptionalPropertyTypes": true,
"verbatimModuleSyntax": true
}
}
// 路由表：satisfies 同时保证键完整与字面量推断
const routes = {
home: { title: "首页", auth: false },
admin: { title: "管理", auth: true },
} satisfies Record<string, { title: string; auth: boolean }>
type RouteKey = keyof typeof routes // "home" | "admin"，不丢失具体键