TypeScript语言基础
编程语言基础与跨语言模型：从 TypeScript 到 JavaScript、Java、Python、C++：TypeScript语言基础
0 子目录18 文档
文档
18TypeScript 官方资料、学习顺序与版本边界TypeScript 官方资料、学习顺序与版本边界 这是一份“入口文档”。它说明资料优先级、TypeScript 7.0 的版本背景，以及遇到网络文章与本知识库不一致时如何验证。 1. 一手资料索引 核心学习资料 TypeScript Documentation：文档总入口。 The TypeScript Handbook：日常语言能力主线。 TSConfig Reference：逐项核对编译器配置。 TypeScript Playgr环境配置与第一个 TypeScript 项目环境配置与第一个 TypeScript 项目 本章从零搭建一个可复现的 Node.js + TypeScript 项目。核心原则是： 项目级依赖、严格配置、类型检查与运行分离 。 1. 准备 Node.js 与包管理器 TypeScript 编译器通过 npm 分发。先安装受支持的 Node.js LTS，并检查命令来源： Windows PowerShell 可用 Get Command node,npm,npx ，macOS/LinTypeScript 运行模型、类型擦除与编译产物TypeScript 运行模型、类型擦除与编译产物 TypeScript 是 JavaScript 的静态类型检查层和工具链，不是独立应用运行时。理解这条边界，可以避免“类型写了为什么线上还出错”的根本误解。 1. 从源码到执行 noEmitOnError 关闭时， tsc 即使报告类型错误也可能输出 JavaScript；需要阻止错误产物时显式开启或让 CI 在非零退出码后停止。 noEmit 则只检查、不生成文件。 2. 类型空间与变量、原始类型、字面量类型与类型推断变量、原始类型、字面量类型与类型推断 TypeScript 的日常使用从 JavaScript 值开始。类型标注应补足推断无法表达的契约，而不是把每个局部变量重复标注一遍。 1. 声明与推断 优先 const ，需要重新绑定时使用 let ，避免 var 的函数作用域和提升陷阱。 const 只禁止变量重新绑定，不会自动冻结对象内部。 2. JavaScript 原始值对应类型 运行时值类别 TypeScript 类型 关键点 字符串 数组、元组、对象、索引签名与只读边界数组、元组、对象、索引签名与只读边界 TypeScript 对象类型描述“值至少有哪些成员”。这是一套结构化模型，不会在运行时创建 schema。 1. 数组与只读数组 readonly number[] 禁止通过该引用修改数组，但原始可变数组若还有别名，仍可被修改： 因此 readonly 是能力限制，不是深冻结或拷贝。 2. 元组 元组适合位置语义稳定、元素少的返回值。字段多或含义可能演进时优先对象，避免调用方记忆下标。 可选与剩余函数签名、重载、this、回调与可调用对象函数签名、重载、this、回调与可调用对象 函数类型是 TypeScript API 设计的核心。好的签名表达输入输出关系，避免靠宽泛联合与断言把责任推给实现者。 1. 参数、返回值与上下文类型 公共函数建议显式写返回类型，以稳定 API 并及时发现实现漂移；短小局部函数可依赖推断。 2. 可选参数、默认参数和剩余参数 可选参数在函数体中是 T undefined 。不要把“调用方可省略”误写成仅允许显式 undefined 。 3. interface、type 与结构化类型系统interface、type 与结构化类型系统 interface 与 type 有大面积重叠，但它们并非互为任意替代。选择标准应来自语义与扩展方式，而不是团队口号。 1. 两种命名对象类型方式 两者都能扩展对象： 2. type 能表达的非对象组合 类型别名能直接命名联合、交叉、元组、函数、原始类型和类型级计算结果。 3. interface 的声明合并 同名接口会合并。这对库的模块增强很有用，对应用领域模型却可能让定义被意外扩展。需联合、交叉、控制流收窄与穷尽检查联合、交叉、控制流收窄与穷尽检查 联合类型表达“多个可能之一”。可靠代码不靠断言选择分支，而是通过运行时证据让控制流分析逐步缩窄。 1. 常见收窄手段 TypeScript 理解 typeof 、 instanceof 、相等比较、真值判断、 in 、赋值、提前返回和部分标准库谓词。 typeof null 陷阱 JavaScript 中 typeof null === "object" ，因此对象检查必须排除 null ： 2. 用户泛型、约束、推断、默认参数与变型泛型、约束、推断、默认参数与变型 泛型用于表达“多个位置共享同一个未知类型”或“输出类型由输入类型决定”。它不是把所有具体类型替换成 <T 。 1. 保留输入输出关系 若改为 unknown unknown ，返回值信息丢失；若改为 any any ，检查也被绕过。泛型的价值是保留关系。 2. 多个类型参数 此例也暴露了标准库动态枚举键会变宽的问题。断言被限制在实现边界，公共签名仍保留 K/V/R 关系。 3. extends 约束 约类、继承、抽象、访问控制与组合类、继承、抽象、访问控制与组合 TypeScript 类建立在 JavaScript 类和原型链之上，并增加静态类型语法。它与 Java/C++ 类表面相似，但运行时模型不同。 1. 字段、构造器与参数属性 参数属性是 TypeScript 简写，会生成实例字段赋值。 private 是 TypeScript 可见性约束；JavaScript balance 才是由运行时强制的私有字段。 2. TypeScript private 与 模块、包、模块解析与声明文件模块、包、模块解析与声明文件 模块问题必须同时满足两个系统：TypeScript 要找到类型，运行时/构建器要找到 JavaScript。只修复编辑器红线而忽略运行时路径，会得到“编译通过、启动失败”。 1. ESM 基础 import type 保证导入只用于类型： 2. 选择模块解析策略 场景 module moduleResolution 重点 现代 Node ESM/CJS NodeNext NodeNext 遵循 packagkeyof、typeof、索引访问与标准工具类型keyof、typeof、索引访问与标准工具类型 类型操作符用于从已有契约推导新契约，减少并行维护。它们只在类型空间计算，不会遍历运行时对象。 1. keyof 若类型具有字符串索引签名， keyof 可能包含 string number ，因为 JavaScript 对象数值键会转为字符串。 2. 类型位置的 typeof 类型 typeof 查询一个值的静态类型；运行时 typeof value 返回字符串标签，二者语法相同但发生阶映射类型、条件类型、模板字面量类型与 infer映射类型、条件类型、模板字面量类型与 infer 高级类型适合表达库 API 中可机械推导的关系。先写清业务真相，再用类型计算消除重复；不要为了“炫技”把简单契约变成递归谜题。 1. 映射类型 映射类型遍历属性键，可用 readonly 、 ? 及 增减修饰符。 键重映射 2. 条件类型 条件类型判断的是类型可赋值关系，不是运行时 if 。 3. infer 提取结构 infer 只能出现在条件类型的 extends 模式中，用来给待提tsconfig、严格模式、项目引用与工程编译tsconfig、严格模式、项目引用与工程编译 tsconfig.json 同时决定文件集合、类型环境、模块解释和生成行为。配置不是“能编译就行”，而是工程契约的一部分。 1. 文件选择 exclude 不是安全边界：被已包含文件导入的模块仍会进入程序。用 npx tsc explainFiles 检查文件为何被纳入。 2. 严格模式族 strict 开启一组更强检查，未来版本可能向该组增加选项，所以升级后出现新诊断是正常的。重要成员包异步、错误边界、DOM 与 Node.js 类型异步、错误边界、DOM 与 Node.js 类型 TypeScript 描述异步值，但 JavaScript 事件循环与 host API 决定实际调度。类型正确不代表超时、取消、并发和错误策略正确。 1. Promise 与 async/await async 函数总返回 Promise 。 response.json() 的静态类型无法证明数据符合 User ，所以仍需 parseUser 。 2. 并发、串行与结果类型 互不依赖的装饰器、JSX、枚举、namespace 与特殊语法边界装饰器、JSX、枚举、namespace 与特殊语法边界 这些特性容易受编译目标、框架或历史配置影响。使用前先确认是 ECMAScript 运行语义、现代 TypeScript 支持，还是 legacy 转换。 1. 现代装饰器与 legacy 装饰器 TypeScript 5.0 起支持符合较新 ECMAScript 提案语义的装饰器；早期 experimentalDecorators 页面描述的是另一套 Stage 2 实现，两者签测试、构建、Lint、发布与 JavaScript 迁移测试、构建、Lint、发布与 JavaScript 迁移 TypeScript 的工程闭环至少包含静态检查、运行测试、风格/缺陷规则、构建产物和消费验证。类型检查只覆盖其中一层。 1. 推荐质量流水线 2. 运行测试与类型测试 运行测试验证实际值与副作用；类型测试验证某调用应通过或应被拒绝。对预期错误可使用 // @ts expect error ，它在错误消失时也会失败，比 @ts ignore 可审计。 3. Lint 与类型检查分TypeScript 综合项目：可靠的配置加载器与类型安全客户端TypeScript 综合项目：可靠的配置加载器与类型安全客户端 本项目把环境、 unknown 解析、可辨识联合、泛型、异步、取消、测试和构建串成完整链路。重点是边界正确，不是堆框架。 1. 目标 实现一个小型 API 客户端： 从环境变量加载并验证配置。 请求 /users/:id ，对 HTTP 与数据错误分类。 支持超时和调用方取消。 不把 any 暴露到领域层。 有运行测试、类型检查和构建门禁。 2. 领域模型与解析器 3.