Skip to content
Lv1TypeScript进度 13 / 14

第 13 章:真实项目阅读实战 ​

前面 12 章都是零件。这一章讲怎么用这些零件去看懂一个陌生的 TS 仓库——不是逐行读,而是"按类型走"。


学习目标 ​

  • 拿到陌生仓库时,知道先看哪四个文件、按什么顺序看
  • 会用编辑器的"跳转定义 / 找引用 / 悬停"把类型链路走通
  • 能快速读懂组件 props、接口 DTO、状态机这三类最常见的类型
  • 遇到高频类型报错时,有一套固定的诊断路径,而不是靠猜
  • 知道改代码时"先改类型还是先改值"

13.1 先看这四个文件,别急着读代码 ​

顺序很重要,从"这个项目是干什么的"到"代码怎么组织"。

这五步的价值是:每一步都在缩小范围。看完这五步,你已经知道该读哪几个文件,而不是把整个仓库翻一遍。

一、README.md ​

只看三件事:启动方式、技术栈、目录约定。很多项目的 README 里就写着"这是 Vite + React + TS",省掉你自己猜。

二、package.json ​

json
{
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "tsc --noEmit && vite build",
    "typecheck": "tsc --noEmit"
  },
  "dependencies": { "react": "...", "zod": "..." },
  "devDependencies": { "typescript": "...", "vite": "..." }
  }

要看的:

字段判断什么
typemodule 就是 ESM,导入要写后缀
scripts有没有独立的 typecheck;build 里有没有 tsc
dependencies用了哪些框架、状态管理、校验库
devDependencies打包器是 Vite、webpack 还是 tsc 直出

这一步能直接告诉你"这个项目的类型检查在哪一环",后面报错才有地方验证。

三、tsconfig.json ​

json
{
  "compilerOptions": {
    "strict": true,
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "paths": { "@/*": ["src/*"] },
    "noUncheckedIndexedAccess": true
  }
}

重点看四项:

  • strict 开没开(没开的话,很多你觉得"应该报错"的地方不会报);
  • module / moduleResolution(决定导入怎么写);
  • paths(@/ 这类别名指向哪);
  • 有没有 noUncheckedIndexedAccess(决定数组取值是否要判空)。

四、目录结构(只看两层) ​

bash
find src -maxdepth 2 -type d | sort

典型的三种布局:

src/
├── api/          # 接口请求与 DTO
├── components/   # 组件与 props
├── hooks/        # 自定义 hook
├── types/        # 公共类型
├── utils/        # 工具函数
└── main.tsx      # 入口

看到 types/ 或 api/types.ts,直接从那开始——类型文件往往比实现代码更能说明业务模型。


13.2 找到真正的入口 ​

不同框架的入口约定不一样:

技术栈入口文件
通用src/index.ts / src/main.ts
React + Vitesrc/main.tsx
Next.jsapp/page.tsx、pages/index.tsx
Node 服务src/server.ts / src/app.ts / src/index.ts
NestJSsrc/main.ts + src/app.module.ts

从入口往外走,先看它 import 了谁,再看那些文件 import 了谁。只看被引用的,不看的代码先跳过——这是读陌生项目最省时间的策略。

typescript
// src/main.tsx
import { createRoot } from 'react-dom/client'
import App from './App'          // ← 下一步看 App
import './styles/global.css'     // ← 跳过,样式不影响类型

13.3 用编译器当导航仪 ​

TS 最大的隐藏价值不是检查错误,是让你能精确地在类型之间跳转。这四个操作必须形成肌肉记忆:

操作VS Code 快捷键什么时候用
跳转到定义F12 / Ctrl+点击看到一个类型名、变量名,想知道它到底是什么
查找所有引用Shift+F12改一个字段前,先看谁在用
悬停看类型鼠标停留不确定一个复杂表达式推出来是什么类型
重命名符号F2改名时让编译器帮你改全,比全局替换安全

一个标准动作:悬停拆解复杂类型 ​

typescript
const result = await api.get<UserResponse>('/user')

result 到底是什么类型?别猜,悬停上去,编辑器会显示类似:

typescript
const result: {
  code: number
  message: string
  data: { id: string; name: string }
}

看不懂的时候还可以临时写一行:

typescript
type Debug = typeof result   // 悬停在 Debug 上,看完整结构

这行不会进生产代码,纯粹是"把类型打印出来看看"。


13.4 读懂三类核心类型 ​

一个 TS 项目里,80% 的类型集中在三个地方。

一、组件 props ​

typescript
interface ButtonProps {
  variant?: 'primary' | 'ghost'
  size?: 'sm' | 'md' | 'lg'
  disabled?: boolean
  onClick?: () => void
  children: React.ReactNode
}

export function Button({ variant = 'primary', size = 'md', ...rest }: ButtonProps) {
  // ...
}

读的时候关注四点:

  1. 哪些是必填(没有 ?)、哪些有默认值;
  2. 联合字面量有哪些取值(决定了能传什么);
  3. children 和 ReactNode 说明这是个容器组件;
  4. ...rest 和 ComponentProps<'button'> 这类写法,说明它把原生属性透传下去了:
typescript
interface IconButtonProps extends React.ComponentProps<'button'> {
  icon: React.ReactNode
}

看到 extends React.ComponentProps<'button'>,就知道"所有 <button> 原生属性都能传",不用去逐个看。

二、接口 DTO ​

typescript
// api/types.ts
export interface ApiResponse<T> {
  code: number
  message: string
  data: T
}

export interface User {
  id: string
  name: string
  email: string
}

读 DTO 的重点是找"信封"和"内容"的分界:

typescript
api.get<ApiResponse<User>>('/user')   // 信封是 ApiResponse,内容是 User

很多项目的统一请求封装会帮你拆掉信封,返回 User 本身。确认这一点,能省掉大量"多了一层 .data"的调试。

三、状态机(判别式联合) ​

typescript
type RequestState<T> =
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error }

看到这种结构,直接去找消费它的 switch:

typescript
switch (state.status) {
  case 'loading': return <Spinner />
  case 'success': return <Content data={state.data} />
  case 'error': return <ErrorView error={state.error} />
  default: return null
}

这段代码会告诉你 UI 在每种状态下做什么、有哪些状态被处理了。状态机的类型和它的 switch 是一对,一起读效率最高。


13.5 六类高频报错的诊断路径 ​

报错一:Type 'string' is not assignable to type 'number' ​

Type 'string' is not assignable to type 'number'.

诊断顺序:

  1. 悬停看左边的值实际是什么类型(经常是 string | undefined);
  2. 看右边的位置要求什么类型(函数参数、接口字段);
  3. 判断是哪边错了:
    • 数据源就是字符串(表单输入、URL 参数)→ 转换:Number(v),并处理 NaN;
    • 类型标注错了(比如 id 其实一直是字符串)→ 改类型定义,而不是硬转。
typescript
// ❌ 硬转,NaN 会悄悄流下去
const age = Number(input.value)
saveUser({ age })

// ✅ 转换 + 校验
const age = Number(input.value)
if (!Number.isFinite(age)) throw new Error('年龄必须是数字')
saveUser({ age })

报错二:Object is possibly 'null' or 'undefined' ​

'user' is possibly 'null'.

诊断顺序:

  1. 这个值为什么会可能是空?(查来源:find()、localStorage、可选 props、Map.get());
  2. 业务上它应该为空吗?
    • 不应该 → 在源头就保证非空(初始化、抛错、默认值);
    • 应该 → 显式处理(if (!user) return、user?.name ?? '');
  3. 不要用 ! 直接压掉,除非你真的能担保它非空。

报错三:Property 'x' does not exist on type 'Y' ​

Property 'avatar' does not exist on type 'User'.

诊断顺序:

  1. 跳转到 User 的定义,确认有没有这个字段;
  2. 没有 → 是类型定义过时了(接口新增了字段),补上;
  3. 有但拼错了 → 改拼写;
  4. 在联合类型上访问 → 先收窄(第 6 章);
  5. 在 unknown / any 上访问 → 先收窄或补类型。

报错四:Argument of type '{...}' is not assignable to parameter of type 'X' ​

Argument of type '{ id: number; name: string; age: number; }'
is not assignable to parameter of type 'User'.
Object literal may only specify known properties,
and 'age' does not exist in type 'User'.

这就是第 5 章的多余属性检查。诊断顺序:

  1. 读报错最后的 and 'age' does not exist —— 它会直接告诉你哪个字段多余;
  2. 多余字段是拼错 → 改;
  3. 真的需要 → 更新类型定义;
  4. 类型定义在第三方包里 → 用模块扩充(第 12 章)。

如果是"缺少字段",报错会列出缺哪个,照着补。

报错五:Element implicitly has an 'any' type because expression of type 'string' can't be used to index type 'Y' ​

Element implicitly has an 'any' type because expression of type 'string'
can't be used to index type '{ id: string; name: string }'.

原因:你用 obj[someString] 访问对象,但 someString 是宽泛的 string,编译器无法保证它是合法的键。

typescript
// ❌
const key = getKeyFromSomewhere()   // string
user[key]

// ✅ 方案一:收窄键
function isUserKey(k: string): k is keyof User {
  return ['id', 'name'].includes(k)
}
if (isUserKey(key)) user[key]

// ✅ 方案二:用 Record 表达"任意键"
const map: Record<string, string> = { ... }
map[key]

这个报错经常出现在"动态字段名"的场景(表单、表格列配置)。判断标准:这个键的集合是有限的还是无限的——有限用 keyof,无限用 Record。

报错六:Cannot find module 'x' or its corresponding type declarations ​

Cannot find module 'legacy-chart' or its corresponding type declarations.

诊断顺序:

  1. 包装了吗?ls node_modules/legacy-chart;
  2. 是内置模块吗?@types/node 装了吗;
  3. 是路径别名吗?tsconfig.paths 和打包器 alias 都配了吗;
  4. 都没有类型 → 自己写声明(第 12 章);
  5. 只在测试里报 → 检查 tsconfig 的 include 有没有覆盖测试目录。

还有一个"看起来像类型问题"的报错 ​

Type 'X' is not assignable to type 'Y'.
Two types have separate declarations of a private property 'foo'.

这种报错通常意味着同一个库被装了两份(比如依赖树里有两个版本的 @types/react)。先查:

bash
npm ls @types/react

不是类型写错了,是依赖重复了,删掉多余的那份即可。


13.6 一次完整的链路演练 ​

假设要改"用户头像上传"这个功能,代码在一个陌生仓库里。

typescript
// 1. 从 UI 找到入口组件
// src/components/UserCard.tsx
function UserCard({ user }: { user: User }) {
  return <Avatar src={user.avatar} />
}
typescript
// 2. F12 跳到 Avatar
// src/components/Avatar.tsx
interface AvatarProps {
  src?: string
  size?: number
  onUpload?: (file: File) => Promise<string>
}
typescript
// 3. 找 onUpload 的实现(Shift+F12 查找引用)
// src/hooks/useAvatarUpload.ts
async function upload(file: File): Promise<string> {
  const form = new FormData()
  form.append('file', file)
  const res = await api.post<ApiResponse<{ url: string }>>('/upload', form)
  return res.data.url
}
typescript
// 4. 悬停看 api.post 的返回类型,确认信封结构
// ApiResponse<{ url: string }> → data: { url: string }

四步下来,整条链路的类型就清楚了:组件 props → hook 实现 → 请求封装 → 响应结构。不需要读完整仓库,只需要读被这条链引用到的文件。

这就是"按类型读代码"的意思:类型是路标,顺着路标走,不迷路。


13.7 改代码时的顺序 ​

一个很实用的习惯:先改类型,再改值。

typescript
// 需求:User 新增一个 phone 字段
interface User {
  id: string
  name: string
  phone: string   // 先加类型
}

保存的瞬间,所有构造 User 对象的地方都会报错,编译器会把"需要补 phone 的地方"全部列出来。顺着报错一个个补,不会漏。

反过来,先到处加 phone、最后才改类型,你会漏掉那些"应该加但没报错"的地方。

同理,删除字段、改名、改类型都从类型定义开始。这是 TS 相对 JS 最实际的收益:编译器替你做了"影响面分析"。


13.8 常见误区 ​

误区一:先从头到尾读一遍源码。 → 大项目几千个文件,读完也不知道重点。按第 13.1 的四步走,只读被引用到的部分。

误区二:报错就用 as any 消掉。 → 报错是信息,不是噪音。每一类报错都对应一个真实问题(13.5 的表)。

误区三:! 非空断言能解决"可能为空"。 → 它只是让编译器闭嘴,运行时该崩还是崩。

误区四:报错在第三方库里,说明是库的问题。 → 先看是不是自己用错了类型参数。确认是库的问题,再用 skipLibCheck 或扩充声明处理,不要直接改 node_modules。

误区五:类型定义和实现对不上时,先改实现。 → 先确认哪个才是"契约"。类型定义是接口约定,改它意味着改约定,要想清楚。


本章小结 ​

要点说明
阅读顺序README → package.json → tsconfig → 目录结构 → 入口
抓手types/、api/ 目录最能说明业务模型
导航四招跳转定义、查找引用、悬停看类型、重命名
三类核心类型组件 props、接口 DTO、判别式状态机
报错诊断先定位哪边类型错,再决定是改数据还是改类型
多余属性报错报错文本会直接指出多余字段名
索引报错键有限用 keyof,键无限用 Record
两份类型声明查依赖重复,不是类型写错
改代码顺序先改类型定义,让编译器列出所有影响点

下一章预告 ​

最后一章把前面所有内容收成一份可执行的习惯清单:类型放哪、什么时候该断言、边界怎么校验、团队怎么统一,以及一张随时能翻的速查表。

👉 第 14 章:最佳实践与速查

本文阅读--次|全站访问--次|访客--人