@aicblock/nserve

!npm
!npm
!NPM

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

NServe 提供了三个主要命令：

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

$3

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

$3

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

$3

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

4. 配置文件

$3

在项目根目录创建 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: {} // 中间件配置
}
})
`

$3

在 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'] // 全局中间件
})
`

$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. 命令使用

$3

`bash
nserve serve
`

选项：

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

$3

`bash
nserve build
`

选项：

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

$3

`bash
nserve gen
`

选项：

- --config - 指定配置文件路径

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. 高级功能

$3

NServe 支持自定义 esbuild 插件：

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

$3

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

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

12. 最佳实践

$3

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

$3

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

13. 常见问题

$3

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

`
PORT=3001
``

$3

确保：

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

$3

检查：

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

15. 贡献

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