# nserve

**Repository Path**: aiclouddigit/nserve

## Basic Information

- **Project Name**: nserve
- **Description**: NServe 是一个 Node.js 服务器端开发 CLI 工具，旨在简化 Node.js 服务器应用的开发、构建和部署流程
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: master
- **Homepage**: http://nserve.aicblock.cn/
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-07-05
- **Last Updated**: 2026-01-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @aicblock/nserve

![npm](https://img.shields.io/npm/v/@aicblock/nserve)
![npm](https://img.shields.io/npm/dm/@aicblock/nserve)
![NPM](https://img.shields.io/npm/l/@aicblock/nserve)

# NServe 用户使用文档

## 1. 项目简介

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

## 2. 快速开始

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

#### 使用 NPM:

```sh
$ npm create nserve@latest
```

#### 使用 Yarn:

```sh
$ yarn create nserve@latest
```

#### 使用 PNPM:

```sh
$ 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` 文件：

```typescript
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`：

```typescript
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`：

```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 启动开发服务器

```bash
nserve serve
```

选项：

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

### 5.2 构建项目

```bash
nserve build
```

选项：

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

### 5.3 生成代码

```bash
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` 中配置全局中间件：

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

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

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

## 11. 高级功能

### 11.1 自定义插件

NServe 支持自定义 esbuild 插件：

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

### 11.2 类型定义

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

```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。