SQL 背景的读代码地图¶

如果你已经会 Java、Scala 和 SQL，读 TypeScript（TS）代码时往往不会卡在「语法像不像 C」上，而是卡在：它到底在描述类型，还是在描述运行时的 JavaScript 行为。把这条线划清，再配合下面这张「盲点地图」，遇到陌生代码时你能较快判断该往哪个方向查。

1. 先建立整体认识：TS 是什么、不是什么¶

维度	一句话
定位	TS 是 JavaScript（JS）的超集：合法 JS 几乎总是合法 TS；多出来的是静态类型标注与一些语法糖。
编译	常见流程是 `tsc` 把 `.ts` 编译成 `.js`（目标 ES 版本可配），类型在编译后全部擦除，运行时只有 JS。
类型系统	结构化类型（structural typing）：主要看「形状」是否兼容，而不是像 Java 那样看「是否声明过继承关系」。
执行环境	与 JVM 不同：浏览器或 Node 里是单线程事件循环 + 异步回调/Promise；没有「线程模型」的默认心智（Web Worker 等是例外）。

因此：看不懂某段 TS，要么是不会 TS 类型写法，要么是底层 JS 语义（异步、this、原型、模块加载）不熟。先判断是哪一种，能省很多时间。

2. 与 Java / Scala / SQL 的框架式对照¶

下面用你熟悉的语言当「锚」，只抓高频差异，不求穷尽。

2.1 与 Java¶

概念	Java	TypeScript
类型是否名义	名义类型：类名、接口名决定赋值是否合法	结构类型：`{ x: number }` 可赋给「只要也有 number 型 x」的目标
接口	主要是契约，实现类要 `implements`	`interface` 多半只参与类型检查，编译后不存在
泛型擦除	JVM 擦除泛型，反射里弱	TS 类型整体擦除，运行时没有 `List<String>` 这种区分
空安全	有明确的引用类型与 `Optional` 等习惯	默认 `strictNullChecks` 关闭时 `null`/`undefined` 很松；团队常开严格空检查
模块	`package` + classpath	文件即模块（ESM `import`/`export` 或 CommonJS），路径解析依赖工具链（Node / bundler）
并发	线程、线程池、`synchronized`	单线程 + `async`/`await`、`Promise`；没有与 synchronized 对等的内置锁

读代码提示： 在 Java 里你会先看「类层次与接口」；在 TS 里更要先看 对象的字段形状 和 函数参数/返回值标注，类继承反而不是主战场。

2.2 与 Scala¶

概念	Scala	TypeScript
代数数据类型	`sealed trait` + `case class` 很常用	用联合类型 `A \\| B` + 字面量类型 `"ok" \\| "err"` + `discriminated union`（可辨识联合）模拟
模式匹配	`match` 强大	没有同等级的 `match`；常用 `switch` + 类型收窄（narrowing）或第三方库
隐式 / 上下文	`implicit`、`given`	没有隐式参数；偶尔见「类型体操」里的条件类型，那是类型层面技巧，不是运行时隐式
高阶类型	较自然	有泛型与条件类型 `infer`，表达力不弱但语法与错误信息更「绕」
可变 / 不可变	习惯上区分 `val`/`var`	`const`/`let`；对象/数组默认可变，不可变要靠习惯或库（如 Immer）
集合	丰富不可变集合	主要是数组 `T[]` 和 Map/Set；没有与 Scala 集合库对等的标准库

读代码提示： 看到 type X = A | B 且每个分支有共同字段（如 kind），按 Scala 里 ADT + 穷举分支 的心智去读会顺畅很多。

2.3 与 SQL¶

SQL 声明式、集合导向；TS/JS 是命令式/函数式混合、引用类型 + 异步顺序。

心智	SQL	TypeScript
数据形态	表 = 行集合	数组 `Row[]`、对象 `{ col: value }`；ORM/查询构建器再包一层类型
空值	`NULL` 三值逻辑	`null` 与 `undefined` 并存，语义略有差别（「未赋值」vs「空」）
连接 / 子查询	`JOIN`、`IN`	常见是 `map`/`filter`/`flatMap`（`flatMap` 常写作 `arr.flatMap` 或链式）
异步	引擎内部并行，你写一句 `SELECT`	显式 `async` 函数返回 `Promise<T>`；I/O 几乎总是异步

读代码提示： 若代码在拼「类似 SQL 的管道」，重点看 中间类型（每个 map 输出什么）和 是否 await 了 Promise——漏 await 是高频 bug，类型有时还不会报错。

3. 一张「盲点地图」：看不懂时先归类¶

读陌生 TS 文件时，可以按下面顺序自问；每一类都对应「该去查什么文档」。

3.1 语法层（多半是 TS 类型特性）¶

interface 与 type 交错 — 多数场景等价；type 更适合联合、交叉、映射类型。
| 与 & — 联合「几选一」、交叉「要同时满足」；交叉类类型若冲突可能得到 never。
as 断言 — 告诉编译器「相信我」，可能绕过检查；和 Scala 的 asInstanceOf 一样要警惕。
keyof、typeof、infer、映射类型 { [K in keyof T]: ... } — 全是编译期逻辑，用于库的类型推导，读不懂时搜「TypeScript utility types / conditional types」。
泛型默认值与约束 <T extends U = V> — 接近 Java/Scala 泛型上界，但结合结构类型时更灵活。

3.2 语义层（多半是 JavaScript 运行时）¶

this 指向 — 普通函数 vs 箭头函数；回调里丢了 this 很常见。
== vs === — 团队规范通常强制 ===；看到 == 要警觉类型强制转换。
真假值（truthy/falsy） — 0、""、null、undefined 等在 if (...) 里行为与 Java 的布尔装箱不同。
?? 与 ?. — 空值合并、可选链；和「短路逻辑」一起出现时要分清「只跳过 null/undefined」还是「跳过一切 falsy」。
数组/对象是引用 — 拷贝默认浅拷贝；类比 Java 里引用赋值。
Promise / async-await — async 函数一定返回 Promise；错误用 try/catch 包 await 或 .catch。

3.3 工程层（多半是工具链，不是语言核心）¶

import 路径 — 有无 .js 后缀、paths 别名、"type": "module" 等，决定运行与编译是否一致。
.d.ts — 只有类型声明、无实现；常为第三方库或「Ambient 声明」。
enum — TS 的 enum 有编译产物与数字枚举坑；现代风格有时更偏向 字面量联合 + as const。

4. 最小可读示例：把「结构类型 + 联合 + 收窄」串起来¶

下面这段没有类层次，却是业务代码里极高频的模式（接近 Scala 的 ADT + match 的弱化版）：

type Result =
  | { ok: true; value: number }
  | { ok: false; error: string };

function handle(r: Result): string {
  if (r.ok) {
    // 此处 r 被收窄为 { ok: true; value: number }
    return `got ${r.value}`;
  }
  return `err: ${r.error}`;
}

读不懂时：先看 type/interface 定义，再看 if/switch 如何根据共有字面量字段（这里的 ok）分支——这是「可辨识联合」。

5. 建议的学习顺序（只为「读懂代码」，不为背 API）¶

ES 现代语法：箭头函数、const/let、解构、模板字符串、展开运算符。
Promise 与 async/await：否则任何 Node/前端 I/O 代码都会糊成一片。
strict 系列编译选项（尤其 strictNullChecks）：对齐你对空值的直觉。
泛型 + 泛型约束：和你已有的 Java/Scala 泛型经验直接迁移。
联合类型与类型收窄：这是 TS 的「日常 ADT」。
模块与工程：import/export、tsconfig、你所在仓库用的打包器（Vite/Webpack 等）各解决什么问题。

6. 小结¶

TS = JS + 编译期类型；运行时行为请用 JS 的心智读。
相对 Java：更偏形状而非名义；相对 Scala：少模式匹配与标准不可变集合，多用联合类型与数组操作；相对 SQL：从「声明式集合」回到「引用 + 异步顺序」，盯紧 Promise 与数据形状。
遇到晦涩代码：先判断是「类型体操」还是「JS 语义 / 异步」，再查对应小节，能系统缩小盲点范围。

若你后续固定读某一套栈（例如 React + Zod，或 NestJS），可以在上述基础上只加深该栈的「类型与运行时交界」——那是从「能读懂」到「能写得稳」的下一层。