NSV - Nitro Server Scaffold

基于 Nitro 的后端项目脚手架 CLI 工具，一键生成开箱即用的 Node.js 服务端项目。

特性

• 基于 Nitro（UnJS 生态）构建，自动文件路由、HMR 开发体验
• 内置 MySQL 连接池与便捷查询方法（query / queryOne / execute）
• 统一 API 响应格式（success / fail / paginated）与错误码体系
• 请求参数校验（validateBody / validateQuery）
• CORS 中间件、请求日志与耗时追踪
• 分级日志系统（控制台 + 按日归档文件）
• Docker 多阶段构建 + docker-compose 一键部署
• 健康检查端点 /api/health

安装

全局安装（推荐）：

npm install -g @knox.zhang/nsv

免安装直接使用：

npx @knox.zhang/nsv init my-project

使用

# 交互式创建项目
nsv init

# 指定项目名称
nsv init my-server

CLI 会引导你输入项目名称和描述，然后自动生成项目结构并初始化 Git 仓库。

生成的项目结构

my-server/
├── server.ts              # 请求生命周期（日志、耗时记录）
├── nitro.config.ts        # Nitro 配置（运行时数据库配置、关闭钩子）
├── vite.config.ts         # Vite + Nitro 插件
├── tsconfig.json          # TypeScript 配置（含路径别名）
├── Dockerfile             # 多阶段构建
├── docker-compose.yml     # App + MySQL 编排
├── .env.example           # 环境变量模板
├── mapper/
│   ├── pool.ts            # MySQL 连接池管理
│   └── mysql.ts           # 便捷查询方法
├── middleware/
│   └── cors.ts            # CORS 中间件
├── routes/
│   └── api/
│       ├── hello.get.ts   # 示例接口
│       └── health.get.ts  # 健康检查
├── service/
│   ├── handler.ts         # defineApiHandler 统一封装
│   ├── logger.ts          # 分级日志
│   └── response.ts        # 统一响应格式
├── script/                # 构建后处理脚本
└── types/
    └── index.ts           # ErrorCode、分页类型等

开发

# 安装依赖
pnpm install

# 启动开发服务器（HMR）
pnpm dev

# 构建
pnpm build

# 预览构建产物
pnpm preview

# 类型检查
pnpm typecheck

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | DB_HOST | MySQL 主机 | localhost | | DB_PORT | MySQL 端口 | 3306 | | DB_USER | MySQL 用户名 | - | | DB_PASSWORD | MySQL 密码 | - | | DB_DATABASE | 数据库名 | - | | LOG_LEVEL | 日志级别 (debug/info/warn/error) | info | | LOG_DIR | 日志文件目录 | logs |

Docker 部署

# 创建 .env 文件并填写数据库配置
cp .env.example .env

# 构建并启动
docker compose up -d

# 查看日志
docker compose logs -f app

docker-compose.yml 包含 App 和 MySQL 两个服务，App 依赖 MySQL 健康检查通过后才启动。

API 示例

统一响应格式

{
  "code": 0,
  "message": "ok",
  "data": { ... }
}

使用 defineApiHandler

import { defineApiHandler } from "../../service/handler";

export default defineApiHandler(
  async (event) => {
    return { items: [] };
  },
  {
    validateBody: (body) => {
      if (!body.name) return { success: false, errors: ["name is required"] };
      return { success: true };
    },
  }
);

数据库查询

import { query, queryOne, execute } from "../mapper/mysql";

// 查询列表
const users = await query<RowDataPacket[]>("SELECT * FROM users WHERE status = ?", [1]);

// 查询单行
const user = await queryOne<RowDataPacket[]>("SELECT * FROM users WHERE id = ?", [id]);

// 写操作
const result = await execute("INSERT INTO users (name) VALUES (?)", ["test"]);

错误码

| 错误码 | 说明 | HTTP 状态码 | |--------|------|-------------| | 0 | 成功 | 200 | | -1 | 未知错误 | 500 | | 1001 | 参数校验错误 | 400 | | 1002 | 资源不存在 | 404 | | 1003 | 未授权 | 401 | | 1004 | 禁止访问 | 403 | | 2001 | 数据库连接错误 | 503 | | 2002 | 数据库查询错误 | 500 |

发布

pnpm release

该命令会编译 CLI 代码、构建模板文件并发布到 npm。

License

MIT