Ts.ED 项目从 v7 迁移到 v8 的完整指南

Ts.ED 项目从 v7 迁移到 v8 的完整指南

前言

Ts.ED 是一个基于 Express 和 TypeScript 构建的企业级 Node.js 框架。随着 v8 版本的发布，框架在依赖注入、模块系统和性能优化等方面都带来了重大改进。本文将详细介绍如何将现有项目从 v7 版本平滑迁移到 v8 版本。

核心变更概览

v8 版本主要带来了以下重要变化：

1. 全局依赖注入：现在可以在代码的任何位置访问注入器实例
2. ECMAScript 模块(ESM)支持：完全移除了对 CommonJS 的支持
3. Apollo Server v4 支持：更新了 GraphQL 集成
4. 日志系统优化：重新设计了请求日志记录机制
5. 代码体积优化：通过模块重构减少了运行时大小

迁移前的准备工作

1. 更新现有依赖

首先确保所有 Ts.ED v7 相关依赖都已更新到最新版本：

npm update @tsed/common @tsed/di @tsed/schema

2. 配置 TypeScript 编译器选项

在 tsconfig.json 中必须设置：

{
  "compilerOptions": {
    "useDefineForClassFields": false
  }
}

这个选项对于确保装饰器正常工作至关重要。

3. 配置 SWC (如使用)

如果你使用 SWC 作为编译器，在 .swcrc 中同样需要设置：

{
  "jsc": {
    "transform": {
      "useDefineForClassFields": false
    }
  }
}

4. 配置获取方式变更

v8 移除了配置对象的代理访问方式，需要改用 get() 方法：

// v7 方式 (已废弃)
console.log(configuration.prop);

// v8 方式
console.log(configuration.get("prop"));

迁移到 ESM 模块系统

v8 版本完全移除了对 CommonJS 的支持，必须迁移到 ESM 模块系统。

1. 修改 package.json

{
  "type": "module"
}

2. 更新 TypeScript 配置

{
  "compilerOptions": {
    "module": "NodeNext",
    "moduleResolution": "NodeNext"
  }
}

3. 修改导入语句

所有导入语句需要添加 .js 扩展名：

// 修改前
import { MyService } from "./services/MyService";

// 修改后
import { MyService } from "./services/MyService.js";

4. JSON 文件导入

ESM 下导入 JSON 文件需要使用断言语法：

import config from "./config.json" assert { type: "json" };

依赖注入系统改进

v8 提供了全新的依赖注入 API，可以在任何地方访问注入器。

传统方式 (仍然支持)

import { Injectable, Inject } from "@tsed/di";

@Injectable()
class MyService {
  @Inject()
  private repository: MyRepository;
}

新函数式 API

import { injectable, inject } from "@tsed/di";

class MyService {
  private repository = inject(MyRepository);
}

injectable(MyService);

全局访问注入器

现在可以在任何地方获取服务实例：

import { inject } from "@tsed/di";

const myService = inject(MyService);

日志系统升级

v8 改进了请求日志记录机制：

1. 移除自动导入的 @tsed/platform-log-middleware
2. 引入更高效的 @tsed/platform-log-request

迁移步骤

1. 安装新包：

npm install @tsed/platform-log-request
npm uninstall @tsed/platform-log-middleware

2. 在服务器配置中启用：

import "@tsed/platform-log-request";

@Configuration({
  logger: {
    logRequest: true,
    alterLog: (level, data, $ctx) => {
      // 自定义日志格式
      return data;
    }
  }
})
export class Server {}

性能优化

v8 通过模块重构显著减少了代码体积：

1. @tsed/common 现在只是一个轻量级的重新导出模块
2. 核心功能被拆分到专门的包中

建议将 @tsed/common 替换为 @tsed/platform-http：

npm uninstall @tsed/common
npm install @tsed/platform-http

然后根据需要从特定包导入功能：

// 替代从 @tsed/common 导入
import { PlatformTest } from "@tsed/platform-http/testing";
import { Get } from "@tsed/schema";
import { Injectable } from "@tsed/di";

迁移检查清单

1. [ ] 更新所有依赖到 v8 版本
2. [ ] 配置 useDefineForClassFields: false
3. [ ] 迁移到 ESM 模块系统
4. [ ] 更新配置访问方式使用 get()
5. [ ] 更新日志系统
6. [ ] 优化导入语句
7. [ ] 测试所有功能

常见问题解决

1. 类属性未正确初始化

确保所有相关配置中 useDefineForClassFields 设为 false。

2. 模块导入错误

检查所有导入语句是否添加了正确的扩展名，并确保 type: "module" 已设置。

3. 测试框架问题

更新测试配置，确保测试运行器支持 ESM：

{
  "scripts": {
    "test": "NODE_OPTIONS=--experimental-vm-modules jest"
  }
}

结语

Ts.ED v8 带来了许多令人兴奋的改进，虽然迁移过程可能需要一些工作，但这些变化将为你的应用带来更好的性能、更清晰的代码结构和更现代化的模块支持。按照本文指南逐步进行迁移，可以确保平稳过渡到新版本。

如果在迁移过程中遇到任何问题，建议查阅官方文档或社区支持渠道获取帮助。