TSOA快速入门指南

项目简介

TSOA（Type-Driven Server Object）是一个基于TypeScript的框架，集成了OpenAPI编译器，专为构建Node.js服务端应用设计。它支持Express、Hapi、Koa等主流Web框架，并天生支持类型安全，能够自动生成并保持最新的OpenAPI规范。

1. 项目目录结构及介绍

TSOA项目通常遵循标准的Node.js应用程序结构，但具体布局可能会依据开发者实践和偏好有所不同。以下是采用TSOA的一般项目结构示例：

my-tsoa-project/
│
├── src                     # 源代码目录
│   ├── controllers         # 控制器存放位置，定义API逻辑
│   │   └── exampleController.ts
│   ├── models              # 数据模型定义，与API相关的数据结构
│   │   └── exampleModel.ts
│   ├── index.ts            # 入口文件或启动服务的引导文件
│
├── tsconfig.json           # TypeScript配置文件
├── tsoa.config.js          # TSOA特定的配置文件
├── package.json            # 包含依赖管理与脚本命令
├── swagger.doc             # 自动生成的OpenAPI文档（可选）
│
└── ...

• src: 应用程序的主要源码所在目录。
  • controllers: 包含处理HTTP请求的控制器类。
  • models: 定义业务逻辑中的数据结构。
• tsconfig.json: 配置TypeScript编译选项。
• tsoa.config.js: TSOA框架特有配置，如路由、错误处理等。
• package.json: 包括npm脚本和项目依赖，常用于定义启动命令和服务配置。

2. 项目的启动文件介绍

在TSOA项目中，启动文件通常是src/index.ts。这个文件作为应用的入口点，负责初始化服务、注册中间件、加载路由等关键任务。一个基本的启动流程可能包括导入Express实例、配置TSOA路由器、监听特定端口等步骤。例如：

import express from 'express';
import * as tsoa from '@tsoa/runtime';
import { Router } from '@tsoa/router';

const app = express();
const router = new Router();

// 自动注册所有控制器
router.RegisterControllers(__dirname);

app.use('/', router.resolve());
app.listen(3000, () => {
    console.log('Server is running at http://localhost:3000');
});

3. 项目的配置文件介绍

tsconfig.json

此文件是TypeScript编译时的配置，控制编译行为。基础配置可能包括允许JS文件、设置目标ES版本、启用严格类型检查等。示例：

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "es6",
    "declaration": true,
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

tsoa.config.js

虽然示例中提到了.js配置文件，但实际上，配置可以以.js或.ts形式存在。该文件用于定制TSOA的行为，例如修改路由前缀、更改OpenAPI文档输出路径等。一个基础配置案例可能是这样的：

module.exports = {
    mode: 'file',
    routePath: './routes', // 如果自定义路由存放路径，应指向正确的位置
    controllerPathGlob: './src/controllers/**/*.ts', // 控制器文件的匹配规则
};

确保上述配置根据实际项目需求进行调整。通过精心安排这些核心组件，可以有效管理和开发高质量的API服务。