tsoa入门教程：5分钟搭建你的第一个TypeScript API服务

tsoa是一个强大的工具，能帮助开发者快速构建符合OpenAPI规范的REST APIs，它结合了TypeScript的类型安全特性与Node.js的高效性能，让API开发变得简单而可靠。通过tsoa，你可以轻松定义接口、处理请求和生成文档，极大地提升开发效率。

📦 快速安装tsoa

要开始使用tsoa，首先需要安装相关的依赖包。打开你的终端，执行以下命令：

npm install tsoa @tsoa/runtime

如果你使用yarn作为包管理工具，也可以运行：

yarn add tsoa @tsoa/runtime

🔨 创建你的第一个控制器

在项目中创建一个控制器文件，比如src/controllers/userController.ts。控制器是tsoa的核心，用于定义API的路由和处理逻辑。以下是一个简单的示例：

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

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

@Controller('/users')
export class UserController {
  private users: User[] = [
    { id: '1', name: 'John Doe', email: '[e-mail]' },
    { id: '2', name: 'Jane Smith', email: '[e-mail]' }
  ];

  @Get('/')
  public async getUsers(): Promise<User[]> {
    return this.users;
  }

  @Get('/{id}')
  public async getUser(@Path() id: string): Promise<User | undefined> {
    return this.users.find(user => user.id === id);
  }

  @Post('/')
  public async createUser(@Body() user: Omit<User, 'id'>): Promise<User> {
    const newUser = { ...user, id: (this.users.length + 1).toString() };
    this.users.push(newUser);
    return newUser;
  }
}

在上面的代码中，我们使用@Controller装饰器定义了一个用户控制器，其基础路由为/users。然后通过@Get和@Post装饰器分别定义了获取所有用户、获取单个用户和创建用户的接口。

⚙️ 配置tsoa

接下来，需要创建tsoa的配置文件tsoa.json，放在项目的根目录下。配置文件用于指定控制器的位置、输出目录等信息：

{
  "entryFile": "src/server.ts",
  "noImplicitAdditionalProperties": "throw-on-extras",
  "controllerPathGlobs": ["src/controllers/**/*.ts"],
  "spec": {
    "outputDirectory": "dist",
    "specVersion": 3
  },
  "routes": {
    "routesDir": "src/routes"
  }
}

🚀 生成路由和Swagger文档

配置完成后，运行以下命令生成路由文件和Swagger文档：

npx tsoa generate

这个命令会根据控制器中的定义，自动生成路由处理代码和符合OpenAPI规范的Swagger文档。生成的路由文件会放在src/routes目录下，Swagger文档则会输出到dist目录。

🌟 启动你的API服务

最后，创建一个服务器入口文件src/server.ts，并添加以下代码：

import express from 'express';
import { RegisterRoutes } from './routes/routes';

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

RegisterRoutes(app);

const port = 3000;
app.listen(port, () => {
  console.log(`Server is running on port ${port}`);
});

现在，你可以通过以下命令启动服务器：

node dist/server.js

打开浏览器，访问http://localhost:3000/api-docs，你将看到自动生成的Swagger文档，可以在其中测试你的API接口。

📝 总结

通过tsoa，你可以在短短5分钟内搭建起一个功能完善的TypeScript API服务。它不仅提供了类型安全的开发体验，还能自动生成API文档，让你的开发过程更加高效和便捷。如果你想深入了解tsoa的更多功能，可以查看项目中的相关源码，比如packages/cli/src/metadataGeneration/controllerGenerator.ts等文件，探索其内部实现机制。

希望本教程能帮助你快速入门tsoa，享受TypeScript API开发的乐趣！ 🎉