tsoa：TypeScript 驱动的高效 OpenAPI 规范生成框架

tsoa：TypeScript 驱动的高效 OpenAPI 规范生成框架

【免费下载链接】tsoa Build OpenAPI-compliant REST APIs using TypeScript and Node 项目地址: https://gitcode.com/gh_mirrors/ts/tsoa

痛点：API 文档与实现的双重维护困境

你是否曾为 API 文档与代码实现不同步而烦恼？传统的 API 开发流程中，开发人员需要手动编写和维护 OpenAPI（Swagger）规范，这往往导致：

• 📝 文档滞后：代码更新后文档忘记更新
• 🔄 一致性难题：手动维护容易出错，接口描述与实际实现不符
• ⏰ 时间浪费：重复劳动，开发效率低下
• 🐛 调试困难：缺乏准确的请求/响应示例

tsoa（TypeScript OpenAPI）正是为解决这些问题而生！它让你用 TypeScript 类型作为 API 的单一生效源，自动生成符合 OpenAPI 规范的文档和路由。

tsoa 核心优势：一次编写，多处受益

🚀 自动化文档生成

import { Route, Get, Post, Body, Query, Path } from '@tsoa/runtime';

/**
 * 用户管理控制器
 * @summary 用户相关操作接口
 */
@Route('users')
export class UsersController {
  /**
   * 获取用户列表
   * @param page 页码
   * @param limit 每页数量
   */
  @Get()
  public async getUsers(
    @Query() page: number = 1,
    @Query() limit: number = 10
  ): Promise<User[]> {
    // 业务逻辑
    return userService.getUsers(page, limit);
  }

  /**
   * 创建新用户
   * @param userData 用户数据
   */
  @Post()
  public async createUser(@Body() userData: CreateUserDto): Promise<User> {
    return userService.createUser(userData);
  }
}

📊 类型安全的请求验证

tsoa 自动基于 TypeScript 类型生成验证逻辑：

🔧 多框架支持

tsoa 支持主流 Node.js 框架：

框架	支持状态	特性
Express	✅ 完全支持	中间件集成、路由生成
Koa	✅ 完全支持	上下文处理、中间件链
Hapi	✅ 完全支持	插件体系、生命周期

实战教程：从零构建 tsoa 项目

环境准备

# 创建项目目录
mkdir my-tsoa-app
cd my-tsoa-app

# 初始化项目
npm init -y

# 安装依赖
npm install tsoa express @types/express
npm install -D typescript @types/node

项目结构规划

my-tsoa-app/
├── src/
│   ├── controllers/     # 控制器层
│   ├── models/         # 数据模型
│   ├── services/       # 业务逻辑
│   └── app.ts         # 应用入口
├── tsoa.json          # tsoa 配置
└── package.json

配置 tsoa

创建 tsoa.json 配置文件：

{
  "entryFile": "src/app.ts",
  "noImplicitAdditionalProperties": "throw-on-extras",
  "controllerPathGlobs": ["src/controllers/**/*.ts"],
  "spec": {
    "outputDirectory": "build",
    "specVersion": 3,
    "basePath": "/api",
    "securityDefinitions": {
      "bearer": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "routes": {
    "routesDir": "build",
    "middleware": "express"
  }
}

定义数据模型

// src/models/user.ts
export interface User {
  id: number;
  name: string;
  email: string;
  createdAt: Date;
  updatedAt: Date;
}

export interface CreateUserDto {
  /**
   * @minLength 2
   * @maxLength 50
   * @example "张三"
   */
  name: string;
  
  /**
   * @format email
   * @example "user@example.com"
   */
  email: string;
  
  /**
   * @minLength 6
   * @format password
   * @example "password123"
   */
  password: string;
}

实现业务控制器

// src/controllers/userController.ts
import { Route, Get, Post, Put, Delete, Body, Query, Path } from '@tsoa/runtime';
import { User, CreateUserDto } from '../models/user';
import { userService } from '../services/userService';

/**
 * 用户管理 API
 * @tags Users
 */
@Route('users')
export class UserController {
  /**
   * 获取用户列表
   * @summary 分页查询用户列表
   * @isInt page
   * @minimum page 1
   * @default page 1
   * @isInt limit
   * @minimum limit 1
   * @maximum limit 100
   * @default limit 10
   */
  @Get()
  public async getUsers(
    @Query() page: number = 1,
    @Query() limit: number = 10
  ): Promise<{ data: User[]; total: number }> {
    return userService.getUsers(page, limit);
  }

  /**
   * 获取用户详情
   * @param userId 用户ID
   */
  @Get('{userId}')
  public async getUser(@Path() userId: number): Promise<User> {
    return userService.getUserById(userId);
  }

  /**
   * 创建用户
   * @param userData 用户创建数据
   */
  @Post()
  public async createUser(@Body() userData: CreateUserDto): Promise<User> {
    return userService.createUser(userData);
  }
}

应用入口配置

// src/app.ts
import express from 'express';
import { RegisterRoutes } from '../build/routes';
import swaggerUi from 'swagger-ui-express';
import * as swaggerDocument from '../build/swagger.json';

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

// 注册 tsoa 生成的路由
RegisterRoutes(app);

// 提供 Swagger UI
app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(swaggerDocument));

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Server running on http://localhost:${PORT}`);
  console.log(`API Docs: http://localhost:${PORT}/api-docs`);
});

构建和运行脚本

在 package.json 中添加脚本：

{
  "scripts": {
    "build": "tsoa spec-and-routes",
    "start": "npm run build && node build/app.js",
    "dev": "npm run build && nodemon build/app.js"
  }
}

高级特性详解

1. 参数验证与装饰器

tsoa 支持丰富的参数验证装饰器：

@Post('complex')
public async complexEndpoint(
  @Path() id: number,
  @Query() search: string,
  @Body() data: ComplexDto,
  @Header('Authorization') auth: string,
  @Request() req: express.Request
): Promise<Response> {
  // 业务逻辑
}

2. 响应处理与状态码

import { Res, TsoaResponse } from '@tsoa/runtime';

@Get('{id}')
public async getUser(
  @Path() id: number,
  @Res() notFoundResponse: TsoaResponse<404, { error: string }>
): Promise<User> {
  const user = await userService.getUserById(id);
  if (!user) {
    return notFoundResponse(404, { error: 'User not found' });
  }
  return user;
}

3. 安全认证集成

@Post('secure')
@Security('bearer')
public async secureEndpoint(@Request() req: express.Request): Promise<string> {
  // JWT 令牌已通过验证
  return 'Secure data';
}

最佳实践指南

🏗️ 项目结构优化

🔍 调试技巧

1. 生成详细日志：设置 TSOA_DEBUG=true 环境变量
2. 验证配置：使用 tsoa spec 只生成文档验证配置
3. 路由测试：利用生成的 OpenAPI 文档进行接口测试

⚡ 性能优化

• 使用 noImplicitAdditionalProperties: "throw-on-extras" 严格模式
• 合理使用缓存减少重复验证
• 批量处理路由生成

常见问题解决方案

❗ 类型解析问题

// 使用 @tsoaModel 装饰器解决循环引用
/**
 * @tsoaModel
 */
export interface User {
  id: number;
  friends: User[]; // 循环引用
}

🔄 版本兼容性

确保 tsoa 版本与 TypeScript 版本兼容：

tsoa 版本	TypeScript 版本	Node.js 版本
4.x	4.0+	14+
3.x	3.7+	12+

🛠️ 自定义模板

创建自定义路由模板：

// custom-template.hbs
import { Router } from 'express';

【免费下载链接】tsoa Build OpenAPI-compliant REST APIs using TypeScript and Node 项目地址: https://gitcode.com/gh_mirrors/ts/tsoa