# express-template

**Repository Path**: alexsummerwps/express-template

## Basic Information

- **Project Name**: express-template
- **Description**: Express项目工业级框架
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-04
- **Last Updated**: 2026-05-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 工业级 Express 项目模板说明文档

欢迎使用这套工业级 Express 框架模板！这套模板不仅是一个简单的服务器，它采用了大厂主流的 **分层架构 (Layered Architecture)**，结合了现代化的开发工具链（Zod, Swagger, ESLint 9+），确保代码结构清晰、易于扩展，并且足够健壮。

---

## 📁 目录结构：文件都放在哪？

就像一个组织良好的工厂，不同的零件放在不同的车间：

```text
src/
  ├── config/          # 【配置中心】使用 Zod 进行环境变量校验，统一管理全局配置
  ├── loaders/         # 【启动模块】负责数据库、Express、Swagger 等组件的解耦加载
  ├── models/          # 【数据模型】定义 Mongoose Schema 和业务实体结构
  ├── services/        # 【业务逻辑】核心业务处理层，负责数据加工与复杂逻辑
  ├── controllers/     # 【控制器】处理 HTTP 请求，调用 Service 并返回标准响应
  ├── routes/          # 【路由系统】定义 API 路径，采用模块化组织
  ├── middlewares/     # 【中间件】包含 JWT 鉴权、统一错误处理、限流保护等
  └── utils/           # 【工具集】包含日志记录器 (Winston)、AppError 类、响应处理器
app.js                 # 【应用入口】整个程序的启动总开关
.env                   # 【秘密文件】存放数据库密码、JWT 秘钥等敏感信息（见 .env.example）
```

---

## 🛠️ 核心架构与请求流转

当一个用户访问 API 时，请求会经历以下标准化流程：

1.  **Request ID**: 每个请求被分配一个唯一的 UUID，用于全链路追踪。
2.  **Routes (路牌)**: 在 `src/routes` 中按版本（如 `/api/v1`）进行挂载。
3.  **Middlewares (安检)**:
    - **Security**: `helmet` (安全头), `cors` (跨域), `rateLimit` (限流)。
    - **Auth**: `authMiddleware.js` 验证 JWT 令牌。
4.  **Controllers (接待员)**: 解析 `req.body` 或 `req.params`。
5.  **Services (工人)**: 执行业务逻辑。
6.  **Models (数据库)**: 存取数据。
7.  **Response (回复)**: 通过 `responseHandler.js` 返回格式统一的 JSON。

---

## 🌟 亮点功能

### 1. 强类型配置校验 (Zod)
项目启动时会使用 `zod` 严格检查 `.env` 文件。如果缺少关键配置（如 `JWT_SECRET`），程序会立即报错并退出，避免运行时出现不可预期的错误。

### 2. 自动化的 API 文档 (Swagger)
内置 Swagger UI。启动项目后访问 `/api-docs` 即可查看所有接口定义、参数说明并直接进行接口测试。

### 3. 全局异常处理与异步支持
集成 `express-async-errors`，你不再需要为每个异步 Controller 编写 `try-catch`。配合 `AppError` 类，只需 `throw` 即可返回规范的错误响应。

### 4. 生产级日志系统 (Winston)
日志不仅会在控制台彩色打印，还会根据日期自动切分文件并保存到 `logs/` 目录，支持不同的日志级别控制。

### 5. 现代化 Lint 规范
配置了 **ESLint 9+ (Flat Config)** 和 Prettier，确保团队代码风格高度一致，并自动处理 Peer Dependencies 冲突。

---

## ⚙️ 环境要求

1.  **Node.js 版本**: `>=18.16.0` (推荐 LTS)。
2.  **MongoDB**: 确保有可用的数据库连接字符串（本地或 Atlas）。

---

## 🚀 快速开始

### 1. 安装依赖
```bash
npm install
```

### 2. 配置环境
复制 `.env.example` 并重命名为 `.env`，填入你的配置信息：
```bash
cp .env.example .env
```

### 3. 启动项目
- **开发模式** (带热更新): `npm run dev`
- **生产模式**: `npm start`
- **代码规范检查**: `npm run lint`

---

## 📝 开发新功能的标准步骤（以“订单 Order”为例）：

1.  **Model**: 在 `src/models/orderModel.js` 定义 Schema。
2.  **Service**: 在 `src/services/orderService.js` 实现逻辑。
3.  **Controller**: 在 `src/controllers/orderController.js` 调用服务。
4.  **Route**: 在 `src/routes/orderRoutes.js` 导出路由，并在 `src/routes/index.js` 挂载。
5.  **Docs**: 在路由文件中添加 Swagger 注释，访问 `/api-docs` 查看。

---

## 🛡️ API 安全与健康
- **限流**: 每个 IP 每小时限制 100 次请求。
- **健康检查**: 访问 `GET /api/v1/health` 获取服务状态。
- **优雅退出**: 监听 `SIGTERM` 信号，确保在进程关闭前完成所有进行中的数据库操作。