# node_example **Repository Path**: caoerlei/node_example ## Basic Information - **Project Name**: node_example - **Description**: 基于 TypeScript 的 Node.js Express 框架项目，采用分层架构设计，遵循完整的项目开发规范，提供 RESTful API 服务。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-01-04 - **Last Updated**: 2026-02-06 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Node.js Express 框架项目 基于 TypeScript 的 Node.js Express 框架项目，采用分层架构设计，遵循完整的项目开发规范，提供 RESTful API 服务。 ## 项目特性 - ✅ **分层架构**：采用 Controller → Service → Repository 三层架构，职责清晰，易于维护 - ✅ **类型安全**：全面使用 TypeScript，严格类型检查，提升代码质量 - ✅ **安全防护**：集成 Helmet、CORS、限流等安全中间件，保障 API 安全 - ✅ **参数验证**：使用 Joi 进行请求参数验证，确保数据有效性 - ✅ **错误处理**：统一的错误处理机制，规范的错误响应格式 - ✅ **日志记录**：完整的日志记录系统，支持不同日志级别 - ✅ **数据库连接池**：MySQL 连接池管理，优化数据库性能 - ✅ **优雅关闭**：支持进程信号处理，实现优雅关闭 - ✅ **代码规范**：遵循统一的代码风格和注释规范 ## 项目结构 ``` project-root/ ├── src/ │ ├── app.ts # Express 应用入口 │ ├── server.ts # 服务器启动文件 │ ├── config/ # 配置文件 │ │ ├── database.ts # 数据库配置 │ │ ├── env.ts # 环境变量配置 │ │ └── constants.ts # 常量配置 │ ├── routes/ # 路由定义 │ │ ├── index.ts # 路由入口 │ │ └── modules/ # 模块路由 │ │ ├── user.routes.ts │ │ └── auth.routes.ts │ ├── controllers/ # 控制器层 │ │ └── modules/ │ │ ├── user.controller.ts │ │ └── auth.controller.ts │ ├── services/ # 服务层（业务逻辑） │ │ └── modules/ │ │ ├── user.service.ts │ │ └── auth.service.ts │ ├── models/ # 数据模型 │ │ └── modules/ │ │ ├── user.model.ts │ │ └── auth.model.ts │ ├── repositories/ # 数据访问层 │ │ └── modules/ │ │ ├── user.repository.ts │ │ └── auth.repository.ts │ ├── middleware/ # 中间件 │ │ ├── auth.middleware.ts │ │ ├── error.middleware.ts │ │ ├── validation.middleware.ts │ │ └── logger.middleware.ts │ ├── utils/ # 工具函数 │ │ ├── logger.ts │ │ ├── validator.ts │ │ ├── encrypt.ts │ │ └── response.ts │ ├── types/ # 类型定义 │ │ ├── express.d.ts # Express 类型扩展 │ │ ├── api.types.ts # API 类型定义 │ │ └── common.types.ts # 通用类型定义 │ ├── validators/ # 验证器 │ │ └── schemas/ │ │ ├── user.schema.ts │ │ └── auth.schema.ts │ └── tests/ # 测试文件 │ ├── unit/ │ ├── integration/ │ └── e2e/ ├── .env # 环境变量（不提交到版本控制） ├── .env.example # 环境变量示例 ├── package.json ├── tsconfig.json └── README.md ``` ### 目录说明 #### 根目录文件 - **`app.ts`**：Express 应用入口文件，负责创建 Express 实例、配置全局中间件、注册路由等 - **`server.ts`**：服务器启动文件，负责启动 HTTP 服务器、处理进程信号、优雅关闭等 #### config/ - 配置目录 - **`database.ts`**：数据库连接配置，包括连接池配置、连接参数等 - **`env.ts`**：环境变量配置，统一加载和验证环境变量，提供类型安全的配置对象 - **`constants.ts`**：项目常量定义，包括错误码、状态码、业务常量等 #### routes/ - 路由目录 - **`index.ts`**：路由入口文件，统一注册所有模块的路由 - **`modules/`**：模块路由文件，按业务模块划分路由，定义路由路径和 HTTP 方法的映射关系 #### controllers/ - 控制器目录 - **`modules/`**：控制器文件，处理 HTTP 请求和响应，调用服务层处理业务逻辑，不包含业务逻辑 #### services/ - 服务层目录 - **`modules/`**：服务文件，实现业务逻辑、数据验证和转换、调用 Repository 层，不直接操作数据库 #### models/ - 数据模型目录 - **`modules/`**：模型文件，定义数据结构和类型，使用 TypeScript 接口或类型定义 #### repositories/ - 数据访问层目录 - **`modules/`**：Repository 文件，封装数据库操作（CRUD），提供统一的数据访问接口，不包含业务逻辑 #### middleware/ - 中间件目录 - **`auth.middleware.ts`**：认证中间件，验证用户身份（JWT Token 等） - **`error.middleware.ts`**：错误处理中间件，统一处理异常并返回错误响应 - **`validation.middleware.ts`**：参数验证中间件，验证请求参数的有效性 - **`logger.middleware.ts`**：日志中间件，记录请求日志 #### utils/ - 工具函数目录 - **`logger.ts`**：日志工具，封装日志记录功能 - **`validator.ts`**：验证工具，提供通用的验证函数 - **`encrypt.ts`**：加密工具，提供密码加密/解密功能 - **`response.ts`**：响应工具，统一格式化 API 响应 #### types/ - 类型定义目录 - **`express.d.ts`**：Express 类型扩展，扩展 Request、Response 等类型 - **`api.types.ts`**：API 相关类型定义，包括请求/响应类型 - **`common.types.ts`**：通用类型定义 #### validators/ - 验证器目录 - **`schemas/`**：验证模式文件，定义请求参数的验证规则（如 Joi、Zod schema） #### tests/ - 测试目录 - **`unit/`**：单元测试文件 - **`integration/`**：集成测试文件 - **`e2e/`**：端到端测试文件 #### 其他根目录文件 - **`.env`**：环境变量文件（不提交到版本控制） - **`.env.example`**：环境变量示例文件 - **`package.json`**：项目依赖和脚本配置 - **`tsconfig.json`**：TypeScript 编译配置 - **`README.md`**：项目说明文档 ## 快速开始 ### 安装依赖 ```bash npm install ``` ### 配置环境变量 创建 `.env` 文件，并根据实际情况配置以下环境变量： ```bash # 服务器配置 NODE_ENV=development PORT=3000 HOST=0.0.0.0 # 数据库配置 DATABASE_HOST=localhost DATABASE_PORT=3306 DATABASE_USER=root DATABASE_PASSWORD=your_password DATABASE_NAME=your_database DATABASE_POOL_SIZE=10 # JWT 配置 JWT_SECRET=your_jwt_secret_key JWT_EXPIRES_IN=7d # Redis 配置（可选） REDIS_HOST=localhost REDIS_PORT=6379 # 日志配置 LOG_LEVEL=info # CORS 配置（可选，生产环境建议配置） ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001 ``` ### 运行开发服务器 ```bash npm run dev ``` ### 构建项目 ```bash npm run build ``` ### 运行生产服务器 ```bash npm start ``` ### 运行测试 ```bash npm test ``` ### 代码格式化 ```bash npm run format ``` ## 开发规范 本项目遵循完整的开发规范，详见项目规范文档。 主要规范包括： - 项目结构规范 - 代码风格规范 - TypeScript 类型规范 - 路由规范 - 中间件规范 - 控制器规范 - 服务层规范 - 数据访问层规范 - 错误处理规范 - API 设计规范 - 安全规范 - 性能优化规范 - 日志规范 - 函数注释规范 - 测试规范 - 环境配置规范 ## 技术栈 ### 核心框架 - **运行时**: Node.js - **框架**: Express.js - **语言**: TypeScript - **数据库**: MySQL (mysql2) ### 安全与认证 - **认证**: JWT (jsonwebtoken) - **密码加密**: bcrypt - **安全中间件**: Helmet（设置安全 HTTP 头） - **跨域**: CORS - **限流**: express-rate-limit ### 数据验证 - **验证库**: Joi（请求参数验证） ### 日志与监控 - **HTTP 日志**: morgan - **自定义日志**: Winston（结构化日志） ### 性能优化 - **响应压缩**: compression - **连接池**: MySQL 连接池管理 ### 开发工具 - **测试框架**: Jest + Supertest - **代码格式化**: Prettier - **开发服务器**: ts-node-dev（热重载） ## 核心依赖 ### 生产依赖 - `express` - Web 框架 - `cors` - 跨域资源共享 - `helmet` - 安全 HTTP 头 - `compression` - 响应压缩 - `express-rate-limit` - API 限流 - `dotenv` - 环境变量管理 - `morgan` - HTTP 请求日志 - `bcrypt` - 密码加密 - `jsonwebtoken` - JWT 认证 - `joi` - 数据验证 - `mysql2` - MySQL 数据库驱动 - `body-parser` - 请求体解析 - `cookie-parser` - Cookie 解析 ### 开发依赖 - `typescript` - TypeScript 编译器 - `ts-node-dev` - TypeScript 开发服务器 - `@types/*` - TypeScript 类型定义 - `jest` - 测试框架 - `supertest` - HTTP 断言库 - `prettier` - 代码格式化工具 ## 项目架构 本项目采用经典的三层架构设计： ``` Controller 层（控制器） ↓ Service 层（业务逻辑） ↓ Repository 层（数据访问） ↓ Database（数据库） ``` ### 数据流转 1. **请求进入** → 路由（Routes） 2. **参数验证** → 验证中间件（Validation Middleware） 3. **业务处理** → 控制器（Controller） 4. **逻辑处理** → 服务层（Service） 5. **数据访问** → 仓库层（Repository） 6. **返回响应** → 统一响应格式 ## 注意事项 1. **环境变量**：确保在生产环境中正确配置所有必需的环境变量 2. **数据库**：启动前确保 MySQL 服务已启动，并创建相应的数据库 3. **安全**：生产环境务必修改默认的 JWT_SECRET 和数据库密码 4. **日志**：生产环境建议配置日志轮转，避免日志文件过大 5. **限流**：根据实际业务需求调整 API 限流配置 ## 许可证 MIT