koa-ts-cli

基于 koa-ts-core 的现代化 TypeScript + Koa 项目脚手架 CLI 工具。

提供了一套完整的工程化解决方案，从项目创建、开发调试、代码生成到文档自动生成，极大地提升 Koa 项目的开发效率。

核心特性

• 🛠 开箱即用: 一键创建基于 TypeScript 的 Koa 项目，内置最佳实践目录结构。
• ⚡️ 极速开发: 内置 ts-node 开发服务器，支持文件变更热重载，监听路径更全面。
• 📝 文档生成: 自动扫描并生成符合 OpenAPI 3.0 标准的文档配置，支持 Bearer JWT 等高级安全配置。
• 🚀 ESM 友好: 内置 jiti 加载器，完美支持 ESM 与 CommonJS 项目，告别模块加载错误。
• 🧩 深度集成: 与 koa-ts-core 无缝配合，提供强大的路由、鉴权、校验能力。
• 🏗 代码生成: 一键生成 Controller (控制器) 和 Validator (校验器) 模板代码。

依赖要求

• Node.js >= 18.0.0
• npm / yarn / pnpm

安装

npm install -g koa-typescript-cli
# 或者
yarn global add koa-typescript-cli
# 或者
pnpm add -g koa-typescript-cli

安装完成后，你将在全局获得 koa-ts-cli 命令。

快速上手

1. 创建项目

使用 create 命令初始化一个新的工程：

koa-ts-cli create my-app

可选参数：

• -n, --npm_type <type>: 指定包管理器 (npm | yarn | pnpm)，默认为 npm。
• -r, --registry <url>: 指定 npm 镜像源 (例如 https://registry.npmmirror.com)。

目录结构预览：

my-app
├── src
│   ├── controller  # 控制器层
│   ├── validate    # 参数校验层
│   └── main.ts     # 应用入口
├── env             # 环境变量配置
├── package.json
└── tsconfig.json

2. 启动开发环境

进入项目目录并启动开发服务器：

cd my-app
koa-ts-cli dev

该命令会自动：

• 启动 TypeScript 编译与运行环境。
• 智能监听 src、env 等核心目录及配置文件的变更，自动重启服务。
• 加载 env/.development.env 环境变量。

3. 生成代码模板

使用 add 命令快速生成业务代码：

# 生成 User 模块的控制器和校验器
koa-ts-cli add user -c controller/api/v1/UserInfo -v validate/api/v1/UserInfo

参数说明：

• -c, --controller <path>: 控制器文件路径 (相对于 src)。
• -v, --validate <path>: 校验器文件路径 (相对于 src)。

生成的代码会自动包含 koa-ts-core 的 @Router 和 @Validate 装饰器模板。

4. 生成接口文档

后端接口变更后，运行以下命令自动生成 Swagger 文档配置：

koa-ts-cli doc

工作原理：

1. 扫描 src/controller 下的所有文件。
2. 解析 koa-ts-core 的 Symbol(route_metadata) 元数据。
3. 提取 API 路径、方法、参数等信息。
4. 在项目根目录生成 doc 文件夹，包含符合 Swagger 规范的文档配置代码。

命令详解

create

创建新项目。

koa-ts-cli create <project_name> [options]

add

添加代码模板。

koa-ts-cli add <template_name> [options]

dev

启动开发服务器。

koa-ts-cli dev

build

构建生产环境代码。

```bash
koa-ts-cli build [options]

可选参数：

• -D, --doc: 自动编译并将 doc/ 目录打包到构建产物中 (需要先手动运行 doc 生成文档)。
• -c, --copy_env: 自动复制 env/ 目录到构建产物中。

会自动执行 tsc 编译，并处理静态资源（如模板文件）的复制。

doc

生成接口文档。适用于使用 koa-ts-core 开发的项目。

koa-ts-cli doc

常见问题

Q: 为什么运行 koa-ts-cli doc 报错 "Cannot read properties of undefined"?

A: 这通常是旧版 CLI 对 ESM 支持不佳导致的。最新版 koa-ts-cli 已内置 jiti 加载器，能够完美兼容 ESM 和 CommonJS 模块，请更新到最新版本即可解决。

Q: 生成的文档在哪里查看？

A: doc 命令仅生成文档配置代码 (在 doc/ 目录下)。你需要启动项目服务，通过 koa-ts-core 内置的 Swagger UI 中间件来访问文档页面 (默认路径 /swagger-ui)。

链接

• koa-ts-core: 核心框架库
• Issues: 问题反馈