# node-serve

**Repository Path**: wlhong/node-serve

## Basic Information

- **Project Name**: node-serve
- **Description**: node服务器模板
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-24
- **Last Updated**: 2025-12-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Node Serve

一个基于 Koa2 开发的通用 Node.js 服务器项目模板。

## 功能特性

- **Web 框架**: 使用 Koa2，轻量且灵活。
- **路由管理**: 集成 @koa/router。
- **参数解析**: 集成 koa-bodyparser。
- **跨域支持**: 集成 @koa/cors。
- **开发体验**: 使用 nodemon 实现热重载。
- **API 文档**: 集成 Swagger/OpenAPI，支持导入 Apifox。
- **模块化**: 包含用户(Users)和产品(Products)两个示例模块。
- **请求日志**: 使用 Winston + 按日滚动记录所有请求，便于调试与监控。
- **数据库**: 支持 MongoDB 连接配置与初始化。

## 目录结构

```
node-serve/
├── src/
│   ├── config/          # 配置文件 (Swagger配置等)
│   ├── controllers/     # 控制器 (业务逻辑，按模块分目录)
│   │   ├── home/
│   │   │   └── index.js
│   │   ├── user/
│   │   │   └── index.js
│   │   └── product/
│   │       └── index.js
│   │   └── wechat/
│   │       └── index.js
│   ├── middlewares/     # 中间件
│   │   └── requestLogger.js # 请求日志中间件
│   ├── routes/          # 路由定义
│   │   ├── users.js     # 用户模块路由
│   │   └── products.js  # 产品模块路由
│   ├── utils/           # 工具函数
│   └── app.js           # 应用入口
├── package.json
└── README.md
```

## 快速开始

### 安装依赖

```bash
npm install
```

### 启动开发服务器

```bash
npm run dev
```

- 服务器地址: `http://localhost:3000`
- API 文档地址: `http://localhost:3000/swagger`
  - OpenAPI JSON: `http://localhost:3000/swagger.json`

### 使用 nodemon 热重载

- 本项目已经集成 `nodemon`，并在 `nodemon.json` 中配置了监听目录与忽略项。
- 开发模式启动后，修改 `src` 目录下的代码将自动重启服务。
- 配置文件：`nodemon.json`
- 启动脚本：`package.json:8` 的 `dev` 脚本。

### 生产环境运行

```bash
npm start
```

## API 模块说明

### 用户模块 (User)
- `POST /users/login`: 用户登录
- `GET /users/:id`: 获取用户信息

### 产品模块 (Product)
- `GET /products`: 获取产品列表
- `GET /products/:id`: 获取产品详情

## 引入 Apifox

本项目已生成符合 OpenAPI 3.0 规范的 API 文档，可以轻松导入 Apifox 进行调试和管理。

1. **启动项目**
   确保项目正在运行 (`npm run dev`)。

2. **获取 OpenAPI JSON**
   - 在线 URL：`/swagger.json`
   - 本地文件：`public/openapi.json`
   - 文档由 `swagger-jsdoc` 自动生成，扫描 `src/routes/*.js` 中的 `@swagger` 注释。

3. **导入 Apifox**
   - 打开 Apifox
   - 创建或进入项目
   - 点击左侧 "项目设置" -> "导入数据"
   - 选择 "OpenAPI (Swagger)"
   - 方式选择 "URL 导入" (如果有暴露 JSON URL) 或 "手动导入" (复制 Swagger UI 页面上的 JSON 内容)
   - 即可看到生成的接口文档并进行调试。

## 请求日志模块

- 日志文件目录：`logs/`
- 日志文件按日生成：`access-YYYY-MM-DD.log`
- 错误日志按日生成：`error-YYYY-MM-DD.log`
- 配置项：
  - `ENABLE_REQUEST_LOG` 环境变量控制开关，默认开启。
  - `LOG_DIR` 环境变量指定日志目录，默认 `logs/`。
- 日志格式：单行 JSON，包含 `ts`、`id`、`method`、`url`、`status`、`duration`、`ip`、`ua`、`query`、`body` 等字段，敏感字段（如 `password`、`token`）自动脱敏。
- 实现：`src/utils/logger.js` 基于 `winston` 与 `winston-daily-rotate-file`，中间件位于 `src/middlewares/requestLogger.js`。

## 数据库配置 (MongoDB)

- 环境变量：
  - `MONGO_ENABLE` 是否启用，默认 `false`
  - `MONGO_URI` 连接字符串，如 `mongodb://user:pass@localhost:27017`
  - `MONGO_DB` 数据库名，如 `app`
- 配置项位置：`src/config/index.js`
- 连接工具：`src/db/mongo.js`，应用入口初始化：`src/app.js`
- 使用建议：开发可关闭，生产开启并提供正确的连接字符串与库名。