TypeScript 在 Node.js 中的应用

1. 为什么在 Node.js 中使用 TypeScript？

Node.js 作为 JavaScript 的运行时环境，结合 TypeScript 的静态类型检查能力，可以显著提升后端代码的健壮性和可维护性。以下是主要优势：

  • 类型安全：减少运行时类型错误（如 undefined 或 null 的意外行为）。
  • 更好的工具支持：代码补全、接口文档提示、重构安全性。
  • 渐进式迁移：允许逐步将现有 JavaScript 项目迁移到 TypeScript。

2. 初始化 Node.js + TypeScript 项目

步骤 1：创建项目

mkdir node-ts-project
cd node-ts-project
npm init -y

步骤 2：安装依赖

npm install typescript ts-node @types/node --save-dev

步骤 3：初始化 TypeScript 配置

npx tsc --init

生成的 tsconfig.json 需调整以下关键配置：

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "CommonJS",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  }
}

3. 编写 TypeScript Node.js 代码

示例：HTTP 服务器

// src/server.ts
import http from 'http';

interface RequestData {
  url: string;
  method: string;
}

const server = http.createServer((req, res) => {
  const requestData: RequestData = {
    url: req.url || '/',
    method: req.method || 'GET'
  };

  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify(requestData));
});

server.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

运行开发环境

使用 ts-node 直接执行：

npx ts-node src/server.ts

4. 结合常用 Node.js 生态

Express 应用示例

安装依赖：

npm install express @types/express

编写类型化路由：

// src/app.ts
import express, { Request, Response } from 'express';

const app = express();
app.use(express.json());

interface User {
  id: number;
  name: string;
}

let users: User[] = [];

app.post('/users', (req: Request, res: Response) => {
  const newUser: User = req.body;
  users.push(newUser);
  res.status(201).json(newUser);
});

app.listen(3000, () => {
  console.log('Express server started');
});

5. 构建与部署

编译为 JavaScript

npx tsc

生成的文件会输出到 dist/ 目录。

生产环境运行

node dist/server.js

使用 PM2 进程管理

npm install pm2 -g
pm2 start dist/server.js

6. 常见问题与解决方案

问题场景解决方案
第三方库缺少类型定义安装 @types/库名 或手动声明类型
动态导入模块类型错误使用 import(...).then() 并断言类型
process.env 类型不安全扩展 NodeJS.ProcessEnv 接口

7. 进阶实践

使用 Decorators 实现路由控制器

import 'reflect-metadata';
import { Controller, Get, Post } from './decorators';

@Controller('/api')
class UserController {
  @Get('/users')
  getUsers() {
    return [{ id: 1, name: 'Alice' }];
  }
}

数据库集成（以 TypeORM 为例）

import { Entity, PrimaryGeneratedColumn, Column } from 'typeorm';

@Entity()
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  name: string;
}

提示：Node.js + TypeScript 的最佳实践是逐步迁移现有项目，优先为核心模块添加类型，再逐步覆盖边缘逻辑。

Last Updated::