Ts.ED框架从v6迁移到v7的完整指南

Ts.ED框架从v6迁移到v7的完整指南

tsed :triangular_ruler: Ts.ED is a Node.js and TypeScript framework on top of Express to write your application with TypeScript (or ES6). It provides a lot of decorators and guideline to make your code more readable and less error-prone. ⭐️ Star to support our work! 项目地址: https://gitcode.com/gh_mirrors/ts/tsed

前言

Ts.ED是一个基于Express和TypeScript构建的现代化Web框架，提供了丰富的装饰器和MVC架构支持。随着v7版本的发布，框架进行了多项重大改进和优化。本文将详细介绍从v6迁移到v7的关键变化和具体步骤。

核心变更概览

1. 虚拟路由器系统

v7版本引入了全新的虚拟路由器，取代了原有的Express和Koa路由器实现。这一变化带来了以下优势：

• 更简单的框架集成（支持Fastify、Hapi等）
• 统一的API设计
• 更好的性能表现

迁移影响：

• 直接访问底层路由器的方法（如callback()和getRouter()）已被移除
• 需要检查自定义路由逻辑是否依赖Express/Koa特定API

2. 组件扫描机制重构

v6中的componentsScan配置已被弃用，改为使用barrelsby工具：

// package.json示例
{
  "scripts": {
    "build": "yarn run barrels && yarn run tsc",
    "barrels": "barrelsby --config .barrelsby.json"
  }
}

优势：

• 解决动态导入的性能问题
• 兼容Webpack等打包工具
• 提高生产环境安全性

3. 模板引擎升级

从Consolidate迁移到@tsed/engines，支持更灵活的引擎扩展：

@ViewEngine("pug", { requires: ["pug"] })
export class PugEngine extends Engine {
  protected $compile(template: string, options: any) {
    return this.engine.compile(template, options);
  }
}

重要API变更

1. 路由处理规则

v7不再允许为同一路径注册多个处理程序：

// v6允许，v7将报错
@Controller("/")
class MyCtrl {
  @Get("/path") handler1() {}
  @Get("/path") handler2() {} 
}

2. JSON映射安全增强

jsonMapper.disableUnsecureConstructor默认值改为true，防止原型污染攻击：

class UnsafeModel {
  constructor(obj: any = {}) {
    Object.assign(this, obj); // 潜在安全风险
  }
}

3. 服务重构

ConverterService被移除，改用函数式API：

// 新写法
import { serialize, deserialize } from "@tsed/json-mapper";

const data = serialize(obj, { type: MyModel });
const model = deserialize(raw, { type: MyModel });

模块调整

1. 缓存模块

缓存装饰器需要单独导入：

import { UseCache } from "@tsed/platform-cache"; // 不再从common导出

2. 异步上下文

@tsed/async-hook-context功能已集成到核心模块：

import { InjectContext, runInContext } from "@tsed/di";

迁移步骤建议

1. 更新依赖：确保所有@tsed/*包版本统一为v7
2. 路由检查：审查自定义路由逻辑
3. 组件扫描：配置barrelsby替代componentsScan
4. API替换：更新ConverterService等废弃API
5. 安全验证：检查模型构造函数安全性
6. 测试覆盖：确保所有功能正常

常见问题解决方案

Q：如何保留动态导入功能？ A：安装@tsed/components-scan并修改启动逻辑：

const scannedProviders = await importProviders({
  mount: { "/rest": [__dirname + "/**/controllers/**/*.ts"] }
});

Q：模板引擎不兼容怎么办？ A：参考官方文档实现自定义引擎适配器，或提交issue获取支持

总结

Ts.ED v7通过架构优化带来了更好的性能、安全性和可维护性。虽然迁移需要一定工作量，但遵循本文指南可以平稳过渡。建议开发者充分利用新特性，如虚拟路由器和改进的模板引擎系统，构建更健壮的应用程序。

tsed :triangular_ruler: Ts.ED is a Node.js and TypeScript framework on top of Express to write your application with TypeScript (or ES6). It provides a lot of decorators and guideline to make your code more readable and less error-prone. ⭐️ Star to support our work! 项目地址: https://gitcode.com/gh_mirrors/ts/tsed