TypeScript 日常开发最佳实践

这套教程围绕当前 Node.js / TypeScript / Express / Sequelize 学习工程展开，重点不是列出全部语法，而是解释：为什么报错、TS 推断了什么、业务应该选择哪种处理。

学习顺序

第一阶段：理解推断与配置派生

1. 类型推断、字面量与 as const
2. typeof、keyof 与索引访问
3. 类型标注、as 与 satisfies

这一阶段解决：为什么 const 数组仍是 string[]，(typeof 配置)[number] 到底表示什么，Customer 字段数组里的长类型如何逐层阅读。

第二阶段：输入契约、返回路径与收窄

1. Pick、Omit 与常用工具类型
2. null、undefined、可选属性与默认值
3. 函数返回值、void 与 never
4. 类型收窄、守卫与断言函数

这一阶段解决：类型重复怎么复用、为什么可选字段赋 undefined 报错、if 里的 return 为什么仍不足、如何处理关联未加载。

第三阶段：泛型、异步与工程边界

1. 泛型入门：表达类型关系
2. Promise、await 与函数类型派生
3. Express 与 Sequelize 的类型边界
4. 类型组织、import type 与项目配置
5. 常见报错排查与日常速查表

这一阶段解决：泛型为什么不校验 JSON、如何复用返回类型、模型/输入/DTO 为什么不能全部合并，以及类型应该放在哪里。

针对当前困惑的最短路线

01 → 02 → 03 → 04 → 06 → 07。可选值查 05，异步查 09，Express/Sequelize 查 10，目录组织查 11，报错查 12。

保留的专题：process.env 的 string | undefined 问题。该文中的 DATABASE/HOST 等为教学变量名，当前 db.ts 使用 DB_NAME/DB_HOST 等实际配置名。

示例与配置约定

• 当前安装的 TypeScript 为 5.9.3；package.json 的版本范围与具体安装版本不是同一个概念。
• 以当前 tsconfig 的 strict、noUncheckedIndexedAccess、exactOptionalPropertyTypes 为基础；不修改配置。
• 当前 noImplicitReturns 未启用，但显式函数返回契约仍会检查缺失返回路径。
• 数据库字段和 Model 列名继续使用 snake_case；示例不会改动业务实现。
• 普通 import/export 仍按 CommonJS 编译，import type 不要求迁移 ESM。
• 文中的“错误示例”故意不能通过检查，请不要整段复制进服务。多个示例会复用前文定义；标为片段的代码需放回对应上下文。
• 对固定配置的推断、闭包收窄、第三方库声明，版本可能影响细节。先查看编辑器实际类型，再结合教程解释。

每章怎样练习？

先预测变量类型
  → 查看编辑器悬停信息
  → 运行类型检查
  → 观察真实运行值
  → 改一个输入/分支，确认两层行为
  → 解释自己选择的契约

日常检查项目：

npx tsc --noEmit

小练习放进项目中一个独立临时 .ts 文件时，先加 export {}; 使它成为模块，避免不同练习同名变量造成冲突。不要提交未完成的错误示例。

直接执行 tsc 某文件.ts 通常不会按项目 tsconfig 加载所有配置；若结果与项目不同，先核对检查方式。此系列不新增依赖，不要求改变 ts-node 启动方式。

与 Sequelize 教程的分工

本系列解释语言、类型与程序边界；Sequelize 实务系列 解释查询、SQL、事务、锁及数据库行为。

例如 reload 漏 await 涉及异步顺序，漏 transaction 涉及数据库可见性，两者不能只靠一种类型写法解决。

学完后的目标

能够解释 as const / satisfies / as 的区别；从受控配置派生类型；用工具类型复用真正相同的契约；处理 null/undefined；覆盖函数返回路径；写可信的守卫；明确运行时验证与静态检查的边界，并保持代码易读。