2. 类型系统与运行时效率的平衡2.1 编译期的心智负担换来的运行时收益以前写纯 JavaScript 接口的时候有一种痛叫“联调靠自觉”。后端接口返回什么结构前端同事根本没地方看只能靠口头约定或者翻 Swagger。用 TypeScript 之后接口定义就是代码本身Controller 的入参类型和返回类型直接暴露给调用方谁改了接口签名编译期立刻报错根本不给你运行时出错的机会。而且更重要的一点是TypeScript 的类型是被编译掉的运行时没有额外开销。它不像某些框架的运行时校验那样要维护一套独立的 schema也不像 Java 的反射那样影响性能。所以你在开发阶段享受类型检查的红利部署之后跑的还是纯 JavaScript性能上没有任何牺牲。这就是我一直坚持“编译期多做点事运行时少踩点坑”的原因。2.2 类型体操做多了会走火入魔但这里必须泼一盆冷水。很多初学者看完一些所谓的“高级类型技巧”之后容易陷入类型体操的泥潭。明明一个接口定义能写明白的事非要搞一个复杂的工具类型推来推去最后类型倒是写得天花乱坠可实际业务逻辑一跑就出问题。我的建议是类型复杂度和业务重要性成正比。工具函数、公共类型可以写得稍微复杂一些但业务代码里的类型尽量直白。你再怎么搞类型安全也替代不了单元测试和集成测试。类型只是辅助工具不是业务逻辑本身。见过太多人为了一个类型定义纠结一个下午产出的代码还是跑不通这种投入产出比简直灾难。2.3 什么时候用 any什么时候严格禁 any团队里经常吵 any 的问题。很多人喜欢一刀切禁止 any。但我个人觉得完全禁止和完全放开都不可取。第三方库类型定义不全的时候用 any 加上注释说明原因比花半天手写类型定义要务实。数据来自外部 API你无法保证结构的时候先定义 unknown 再做收窄而不是直接 any 吞掉。以前我遇到过这种坑某个前辈的代码里到处 any后来那个接口的数据结构变了代码静默出错线上数据全乱。排查了两天才发现是类型没兜住。所以后来我给自己定了一个规矩业务核心路径上不允许 any边界场景和第三方兼容场景可以使用但是要写注释并且要在 Code Review 里说明理由。3. 从零搭建一个可维护的 TS Node.js 工程3.1 初始化项目的基础配置我习惯从最小工程开始搭不引入太多框架概念。先用 npm init 初始化然后装 TypeScript、ts-node、types/node再配置 tsconfig.json。一个相对稳妥的基础配置长这样{ compilerOptions: { target: ES2020, module: CommonJS, lib: [ES2020], outDir: ./dist, rootDir: ./src, strict: true, esModuleInterop: true, skipLibCheck: true, forceConsistentCasingInFileNames: true, resolveJsonModule: true }, include: [src/**/*], exclude: [node_modules, dist] }几个关键点target 设成 ES2020是因为 Node.js 12 以上对 ES2020 的语法基本都支持得很好也不用担心 async/await、可选链这些特性跑不动。strict 一定开不开 strict 就没有意义了。它会强制你处理 null 和 undefined 的情况一开始觉得烦后面真香。outDir 和 rootDir 分开编译产物和源码彻底隔离避免手滑改了 dist 里的文件。3.2 开发与构建脚本的差异化配置开发环境的脚本用一个 ts-node 跑源码生产环境的用 tsc 编译后跑 dist。我一般在 package.json 里这样配置{ scripts: { dev: ts-node src/index.ts, build: tsc -p tsconfig.json, start: node dist/index.js } }实际开发的时候我还会加 nodemon 监听文件变化npm install -D nodemon然后 dev 脚本改成dev: nodemon --exec ts-node src/index.ts这样每次保存文件就会自动重启服务开发效率提升非常明显。但注意生产环境千万不要用 ts-node 跑因为 ts-node 每次启动都要做一次类型检查和编译内存和启动时间都不可控跑线上服务纯属自找麻烦。3.3 目录结构这样分改起来不迷路我见过不少 Node 项目所有代码堆在一个文件夹里路由、模型、服务、工具函数全混着。项目小的时候无所谓一旦业务多起来改一个功能要摸半天才知道文件在哪。我常用的分层结构是这样的src/ ├── app.ts # 应用入口组装中间件和路由 ├── server.ts # HTTP 服务启动 ├── routes/ # 路由定义只做参数校验和分发 ├── controllers/ # 控制层处理请求和响应 ├── services/ # 业务逻辑层核心业务都在这里 ├── models/ # 数据模型和数据访问 ├── middlewares/ # 中间件鉴权、日志、错误处理 ├── utils/ # 工具函数 └── types/ # 全局类型定义路由层不要写具体业务Controller 里也不要堆一堆 SQLService 层才是业务逻辑的主战场。这样的分层有个好处你想换数据库的时候只需要改 models 层你想加权限校验的时候只需要动 middlewares你想加一个功能的时候优先去 services 里找对应的模块。项目规模大了之后这种清晰的边界能省很多事。4. Express 与 TS 的搭配细节4.1 路由和控制器怎么写才顺手用 Express 写接口的时候路由文件只做一件事把 URL 映射到 Controller 的方法上。比如一个用户相关的路由import { Router } from express; import { UserController } from ../controllers/user.controller; const router Router(); router.get(/users, UserController.list); router.get(/users/:id, UserController.detail); router.post(/users, UserController.create); router.put(/users/:id, UserController.update); router.delete(/users/:id, UserController.remove); export default router;Controller 的写法import { Request, Response } from express; export class UserController { static async list(req: Request, res: Response) { const users await UserService.getAll(); res.json({ code: 0, data: users }); } static async detail(req: Request, res: Response) { const { id } req.params; const user await UserService.getById(Number(id)); res.json({ code: 0, data: user }); } }这里有个很关键的点Controller 里拿到 req.params 和 req.body 的一定是 any 类型因为 Express 本身没有做运行时校验。TS 只能约束你写代码时的类型约束不了 HTTP 请求里真正传过来的东西。所以参数校验必须单独做。4.2 参数校验的两种常见方案项目简单的时候我习惯手写校验函数几个字段很快就能写完。但一旦接口多起来手写校验代码会膨胀得非常厉害而且容易漏。后来我给项目引入了一个轻量校验库Zod。它不是框架只是一个 schema 校验器跟 TypeScript 的类型系统融合得特别好。你可以定义import { z } from zod; const createUserSchema z.object({ name: z.string().min(1).max(20), age: z.number().int().min(0).max(150), email: z.string().email(), }); type CreateUserInput z.infertypeof createUserSchema;然后在校验中间件里用const parsed createUserSchema.safeParse(req.body); if (!parsed.success) { return res.status(400).json({ code: 1, message: 参数校验失败, errors: parsed.error.errors }); } req.body parsed.data;Zod 最香的地方在于 z.infer 可以直接从 schema 推导出 TypeScript 类型不用维护两份类型定义schema 和类型天然一致。用了 Zod 之后我在 Controller 里拿到的 req.body 就放心多了因为已经经过运行时校验类型是可靠的。4.3 错误处理中间件别偷懒Express 的错误处理中间件很多人会忽略。不写的话任何异常都会导致程序崩溃或者默认的 500 页面前端拿到的信息完全没有可读性。我的错误处理写在一个专门的中间件里import { Request, Response, NextFunction } from express; export function errorHandler(err: Error, req: Request, res: Response, next: NextFunction) { console.error([${new Date().toISOString()}] ${req.method} ${req.url}, err); const status (err as any).status || 500; const message status 500 ? 服务器内部错误 : err.message; res.status(status).json({ code: status, message }); }注意这种错误处理中间件一定要放在所有路由的后面注册不然路由抛出的异常根本走不到这里。还要记得在异步控制器里用 express-async-errors 或者自己写一个 wrapper否则 async 函数里的 rejection 不会被 Express 捕获。要么每个 Controller 包一层 try-catch要么引入工具库统一处理我选择后者代码干净很多。5. 数据持久化与类型同步5.1 ORM 和查询构建器的选择Node.js 生态里的数据库方案很多原生的 mysql2 直连、Knex 查询构建器、TypeORM、Prisma 我都试过。原生驱动最灵活但写 SQL 容易出错而且类型全靠手写。Knex 比原生省心一点但类型支持一般。TypeORM 功能很强但装饰器那一套跟 TypeScript 的 class 绑定有点重复杂查询写起来反而不顺手。我现在用得最多的是 Prisma。原因有三个schema 定义即数据模型生成的 client 类型完全和数据库表结构对应。不需要手写 migration改 schema 之后直接 prisma migrate dev 就能生成和执行迁移脚本。类型推导非常精确查询结果从数据库出来后就是带类型的对象。5.2 Prisma schema 定义的小技巧Prisma 的 schema 文件长这样datasource db { provider postgresql url env(DATABASE_URL) } generator client { provider prisma-client-js } model User { id Int id default(autoincrement()) name String email String unique age Int? posts Post[] createdAt DateTime default(now()) updatedAt DateTime updatedAt } model Post { id Int id default(autoincrement()) title String body String author User relation(fields: [authorId], references: [id]) authorId Int }这里有个容易踩坑的地方关联字段要同时写到两个模型里一个地方漏了prisma generate 的时候就会报错。改 schema 之后记得跑一遍 prisma format它会把缩进和字段顺序统一好不然团队协作容易冲突。生成 client 之后业务代码里的类型就这么来的不会再出现“数据库表结构改了代码里还在用旧字段名”的尴尬。5.3 事务与并发的类型安全写数据持久化的时候事务是很常见的需求。Prisma 的交互式事务返回类型也能自动推导。比如const result await prisma.$transaction(async (tx) { const user await tx.user.create({ data: { name: 张三, email: zhangsanexample.com } }); const post await tx.post.create({ data: { title: 第一篇文章, body: 内容, authorId: user.id }, }); return { user, post }; });result 的类型就是 { user: User, post: Post }不需要手动声明。这对后端开发体验的提升非常明显数据库层面的事务逻辑直接用类型来保证一致性编译不通过就能提前发现调用错字段的问题。6. 日志、配置与环境管理6.1 环境变量加载别再手写了很多 Node 项目老板教新人用 dotenv 手动加载 .env 文件但实际上更省心的是直接用 Node.js 官方支持的 --env-file 参数或者用 dotenv-cli 配合 cross-env 来做。我自己的做法比较简单开发环境下用 dotenv 加载 .env.local 文件生产环境把环境变量交给容器平台注入。这里有个安全相关的提醒.env 文件千万不要提交到 Git 仓库。我见过不止一次有人把数据库密码、API 密钥直接提交上去了后续造成的损失完全不可控。建议在 .gitignore 里写上 .env、.env.local并且提供一个 .env.example 模板里面只放变量名和示例值。6.2 结构化日志比 console.log 好用十倍到项目后期console.log 真的是杯水车薪。你看一堆字符串日志根本看不出来问题在哪特别是接口并发一上来日志全混在一起。我后面换成了 pino它输出的是 JSON 结构日志每个请求可以打上 requestId链路分析省太多事了。import pino from pino; const logger pino({ level: process.env.NODE_ENV production ? info : debug, base: { pid: process.pid }, timestamp: pino.stdTimeFunctions.isoTime, });然后每个请求进来的时候生成一个 requestId加进 logger 的 bindings 中app.use((req, res, next) { req.id crypto.randomUUID(); logger.child({ requestId: req.id }); next(); });这样一来日志里每一行都能对应到具体的请求排错的时候 grep 一下 requestId 就能把一条请求链上的所有日志捞出来效率高得不是一点半点。6.3 本地开发和生产配置差异别硬编码需要注意的是本地开发环境和生产环境的配置一定会不一样。数据库地址、Redis 地址、日志级别、第三方服务的密钥统统都应该通过环境变量控制而不是写在代码里。一个常见做法是写一个 config 文件统一读取const envConfig { development: { databaseUrl: process.env.DATABASE_URL_DEV || , logLevel: debug, }, production: { databaseUrl: process.env.DATABASE_URL_PROD || , logLevel: info, }, }; export const config envConfig[process.env.NODE_ENV ?? development];这样各种环境切换起来就很顺手不会出现本地跑得好好的上线就白屏的情况。7. 项目上线前必须做的事7.1 构建产物检查上线部署前我会先跑 npm run build检查 dist 目录有没有生成完整。很多新手会忽略 tsconfig 里 include 的路径问题导致编译后缺文件线上跑起来直接模块找不到。还有一个坑是如果代码里用到了某个依赖的 ESM 版本而 tsconfig 的 module 是 CommonJS编译后 require 的时候可能出现不兼容这种情况要提前测。7.2 进程管理和崩溃恢复Node.js 进程挂了怎么办直接用裸 node 启动不是一个可靠方案。我一般用 PM2 管理进程。pm2 start dist/index.js --name my-app --max-memory-restart 300M它会做这么几件事进程崩溃后自动重启。你可以看 pm2 logs 实时查看输出。搭配 pm2 scale 可以做简单的多实例扩展。不过要说清楚PM2 不是万能的。它解决的是进程级稳定性解决不了应用本身的逻辑错误。代码有问题的时候重启 100 次也一样报错。PM2 只是让服务在偶发崩溃的场景下自动恢复而不是兜底业务的正确性。7.3 接口健康检查和监控我给项目加了一个简单的 /health 接口返回服务的进程状态、数据库连通性、内存使用情况。这个接口配合监控平台能很快定位是应用挂了还是数据库挂了。app.get(/health, async (_req, res) { try { await prisma.$queryRawSELECT 1; res.json({ status: ok, uptime: process.uptime(), memory: process.memoryUsage(), db: connected, }); } catch { res.status(500).json({ status: degraded, db: disconnected }); } });别小看这个接口线上出了问题的时候它能帮你快速判断“到底是服务的问题还是数据库的问题”省掉很多无意义的排查时间。8. 常见问题与排查技巧实录8.1 “无法找到模块”的路径问题TypeScript 项目经常遇到一个报错Cannot find module ./xxx。排除掉拼写错误之外最常见原因是 tsconfig 里没有开启 baseUrl 和 paths或者用了别名但没有配置对应的模块解析。如果你在代码里写的是相对路径那还好但如果你用了 / 这种别名就需要在 tsconfig 里配置{ compilerOptions: { baseUrl: ., paths: { /*: [src/*] } } }同时运行的时候也要保证运行时能解析到别名。ts-node 会读 tsconfig 的 paths但编译后的 dist 目录不一定能正确解析这时候往往需要额外的模块解析工具或者改用相对路径。我个人的建议是中小型项目干脆直接用相对路径别为了省几个字符引入一套别名机制坑比收益多。8.2 定义了接口却调用不到还有一个经常出现的问题在类型文件里定义了一大堆 interface但业务代码里怎么 import 都不对。大概率是忘了在类型文件中加 export。TypeScript 的类型声明如果不导出默认是全局可见的但有时候和模块系统混在一起就变得乱七八糟。最简单的原则是所有类型定义文件都当作普通模块来写每个类型都显式 export然后在业务代码里显式 import。这样不会出现“全局污染 找不到定义”的诡异问题。8.3 调试技巧别只会 console.log很多时候排查问题靠 console.log 也行但效率确实低。我在项目里加了 ts-node 配合 inspector 的调试方式。node --inspect-brk -r ts-node/register src/index.ts然后用 Chrome DevTools 连上断点调试。这样你能看到每个中间变量在某个时刻的值调用栈一目了然尤其是在排 Query 相关的 bug 时比一遍遍打日志强太多了。8.4 依赖版本不一致的连锁反应Node 生态的依赖版本问题很让人头疼。有时候两天前还好好的跑了个 npm install 之后项目就崩了。最常见的原因就是依赖升级了大版本API 变了。我的做法是锁版本文件package-lock.json 一定提交到 Git 里解析依赖的时候严格按 lockfile 走。另外一个经验是对于关键依赖升级的时候不要直接在 package.json 里写到最新版而是先在干净环境里单独验证一下。9. 这一路踩过来的坑和心得9.1 别把 TypeScript 当成银弹用了 TypeScript 之后代码确实稳定很多但它不会自动帮你写好业务逻辑。类型只能保证这一层的代码调用关系是自洽的保证不了业务流程正确。我见过很多团队花了大力气搭类型体系结果业务逻辑该错还是错。所以类型重要但测试更重要尤其是核心链路的集成测试。9.2 从 JavaScript 迁移到 TypeScript 的节奏如果你现在手里有一个遗留的 JavaScript 项目想迁移到 TypeScript我建议不要一步到位全部 rewrite。最稳妥的路线是先把 tsconfig 允许 js 文件开启 checkJs: false新增文件用 TS。然后慢慢把基础的 utils 和 models 层转成 TS。最后再把所有文件改造成 TS开严格模式。这个过程可能要持续几周甚至一两个月但不会因为“大爆炸式重构”导致项目长期处于不可用状态。9.3 为团队制定一套简单的类型规范最后给个建议代码规范不一定要长篇大论但要有一条主线公共类型和接口定义集中在专门的文件里命名用清楚的 PascalCase 和 Domain 词汇。比如 UserInfo、CreateOrderReq、OrderDetailResp一目了然。团队里如果有新人加入他看一眼类型文件就能明白整个系统的业务对象结构这比看一堆业务代码要高效得多。我在实际项目里发现真正让 TypeScript 价值发挥出来的不是某个复杂的泛型技巧而是整个团队能不能形成一致的思维习惯写代码之前先定义好类型接口变了先改类型定义业务层面先想清楚数据结构再想逻辑怎么写。这套习惯养成了代码质量自然就上去了。这个方向后续还可以继续向外扩展比如给你的服务加上单元测试、集成测试流水线把 CI/CD 跑起来让类型检查和测试一起在每次提交的时候自动跑那项目的稳定性和可维护性就会再上一个台阶了。
