@aicblock/nserve

NServe 用户使用文档

1. 项目简介

NServe 是一个 Node.js 服务器端开发 CLI 工具，旨在简化 Node.js 服务器应用的开发、构建和部署流程。它提供了代码生成、热重载开发服务器和项目构建等功能，帮助开发者快速搭建和维护 Node.js 服务器应用。

2. 快速开始

您可以使用以下命令创建一个新的 NServe 项目：

使用 NPM:

$ npm create nserve@latest

使用 Yarn:

$ yarn create nserve@latest

使用 PNPM:

$ pnpm create nserve@latest

3. 核心功能

3.1 命令行接口

NServe 提供了三个主要命令：

• nserve serve - 启动开发服务器
• nserve build - 构建项目
• nserve gen - 根据配置文件生成代码

3.2 代码生成

• 路由生成：根据配置文件自动生成 Express 路由
• 模型生成：从 SQL CREATE TABLE 语句生成数据模型

3.3 开发服务器

• 支持 TypeScript 实时编译
• 热重载功能
• 支持环境变量配置

3.4 项目构建

• 使用 esbuild 进行快速构建
• 支持生产环境优化
• 生成可执行的 JavaScript 代码

4. 配置文件

4.1 基本配置

在项目根目录创建 nserve.config.ts 文件：

import { DefineNserveConfig } from '@aicblock/nserve'

export default DefineNserveConfig({
  entry: 'app.ts', // 应用入口文件
  outputDir: 'dist', // 构建输出目录
  sourceDir: 'src', // 源代码目录
  testing: false, // 是否为测试模式
  yamlConfig: {}, // YAML 配置文件内容
  plugins: [], // 自定义插件
  external: [], // 外部依赖
  generateConfig: {
    genDir: 'nserve-config', // 生成配置目录
    routerDir: 'router', // 路由配置目录
    modelDir: 'model', // 模型配置目录
    codePrettier: {
      semi: false, // 是否使用分号
      singleQuote: true, // 是否使用单引号
      trailingComma: 'none' // 尾随逗号配置
    },
    middleware: {} // 中间件配置
  }
})

4.2 路由配置

在 nserve-config/router 目录下创建路由配置文件，例如 user.ts：

import { DefineGenRouter } from '@aicblock/nserve'

export default DefineGenRouter({
  servicePath: '/api/user', // 路由前缀
  serviceHandler: 'user', // 处理逻辑目录
  routers: [
    {
      path: '/list', // 路由路径
      method: 'GET', // HTTP 方法
      name: 'list', // 处理函数名
      middleware: [] // 路由级中间件
    },
    {
      path: '/create',
      method: 'POST',
      name: 'create',
      session: {
        /* session 配置 */
      }
    }
  ],
  middleware: ['auth'] // 全局中间件
})

4.3 模型配置

在 nserve-config/model 目录下创建 SQL 文件，例如 user.sql：

CREATE TABLE `user` (
  `id` INT PRIMARY KEY AUTO_INCREMENT COMMENT '用户ID',
  `username` VARCHAR(50) NOT NULL UNIQUE COMMENT '用户名',
  `password` VARCHAR(255) NOT NULL COMMENT '密码',
  `email` VARCHAR(100) NOT NULL UNIQUE COMMENT '邮箱',
  `created_at` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

5. 命令使用

5.1 启动开发服务器

nserve serve

选项：

• --mode <mode> - 指定运行模式（development/production）
• --config <path> - 指定配置文件路径

5.2 构建项目

nserve build

选项：

• --mode <mode> - 指定构建模式（development/production）
• --config <path> - 指定配置文件路径

5.3 生成代码

nserve gen

选项：

• --config <path> - 指定配置文件路径

6. 项目结构

project/
├── src/                      # 源代码目录
│   ├── handler/             # 路由处理器
│   ├── logic/               # 业务逻辑
│   ├── model/               # 数据模型
│   └── app.ts               # 应用入口
├── nserve-config/           # 生成配置目录
│   ├── router/              # 路由配置
│   └── model/               # 模型 SQL 文件
├── nserve.config.ts         # NServe 配置文件
└── package.json             # 项目配置
└── tsconfig.json             # TypeScript 配置文件

7. 路由生成流程

1. 创建路由配置文件 nserve-config/router/*.ts
2. 运行 nserve gen 命令
3. NServe 会自动生成：
   • 路由处理器文件 src/handler/*.handler.ts
   • 业务逻辑模板文件 src/logic/*/*.logic.ts
   • 路由注册文件 src/handler/router.ts

8. 模型生成流程

1. 创建 SQL 文件 nserve-config/model/*.sql
2. 运行 nserve gen 命令
3. NServe 会自动生成：
   • 数据模型文件 src/model/*.ts
   • 模型索引文件 src/model/index.ts

9. 环境变量

NServe 支持 .env 文件和环境特定的配置文件（如 .env.development、.env.production）。

示例 .env 文件：

# yamlConfig 配置
YAML_CONFIG.APP_CONFIG.PORT=3000
YAML_CONFIG.MYSQL_CONF.host=localhost
YAML_CONFIG.MYSQL_CONF.port=3306
YAML_CONFIG.MYSQL_CONF.user=root
YAML_CONFIG.MYSQL_CONF.password=password
YAML_CONFIG.MYSQL_CONF.database=test

# NServe 配置
AICBLOCK_NSERVE_APP_ENTRY=app.ts

10. 中间件配置

在 nserve.config.ts 中配置全局中间件：

export default DefineNserveConfig({
  generateConfig: {
    middleware: {
      auth: {
        libName: '@/middleware/auth',
        funcName: 'authMiddleware'
      }
    }
  }
})

在路由配置中使用中间件：

export default DefineGenRouter({
  routers: [
    {
      path: '/protected',
      method: 'GET',
      name: 'protected',
      middleware: ['auth']
    }
  ]
})

11. 高级功能

11.1 自定义插件

NServe 支持自定义 esbuild 插件：

export default DefineNserveConfig({
  plugins: [
    {
      name: 'custom-plugin',
      setup(build) {
        // 插件逻辑
      }
    }
  ]
})

11.2 类型定义

NServe 提供了完整的 TypeScript 类型定义，可以在项目中直接使用：

import type { Config, DefineGenRouterConfig } from '@aicblock/nserve'

12. 最佳实践

12.1 项目组织

• 将路由和业务逻辑分离
• 使用模型层抽象数据库操作
• 为不同功能模块创建独立的路由配置文件

12.2 开发流程

1. 创建项目结构
2. 配置 nserve.config.ts
3. 编写路由配置文件
4. 编写 SQL 模型文件
5. 运行 nserve gen 生成代码框架
6. 实现业务逻辑
7. 使用 nserve serve 启动开发服务器进行测试
8. 使用 nserve build 构建生产版本

13. 常见问题

13.1 端口被占用

如果开发服务器端口被占用，可以在 .env 文件中修改 PORT 配置：

PORT=3001

13.2 热重载不生效

确保：

• 源代码目录配置正确
• 入口文件存在且配置正确
• 没有语法错误

13.3 构建失败

检查：

• TypeScript 语法错误
• 依赖是否安装正确
• 配置文件是否正确

15. 贡献

欢迎提交 Issue 和 Pull Request 来改进 NServe。