# express-next-app **Repository Path**: qimxu/express-next-app ## Basic Information - **Project Name**: express-next-app - **Description**: express + next 的服务端渲染全栈项目模版 - **Primary Language**: TypeScript - **License**: MIT - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-03-27 - **Last Updated**: 2026-03-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Express Next App 基于 **Express.js + Next.js 16** 的全栈应用模板，采用统一端口架构（单端口 3000），前后端共享服务器。 ## 技术栈 ### 后端 - **Express.js** - 极简、灵活的 Node.js Web 应用框架 - **MySQL2** - 高性能 MySQL 客户端（原生 SQL + 连接池） - **Knex.js** - SQL 查询构建器（仅用于迁移和种子） - **Redis (ioredis)** - 缓存与会话存储、Token 黑名单 - **JWT (jose)** - 无状态认证，双 Token 机制 - **Zod** - 运行时数据验证 - **Winston + DailyRotateFile** - 结构化日志记录与轮转 - **Helmet + CORS** - 安全中间件 - **express-rate-limit** - API 限流保护 ### 前端 - **Next.js 16** - React 全栈框架，Turbopack 极速构建 - **React 19** - UI 库 - **TypeScript** - 类型安全 - **Tailwind CSS** - 原子化 CSS - **next-intl** - 国际化路由与翻译 - **Lucide React** - 图标库 ### 开发工具 - **ESLint 9** - 代码检查（Flat Config 格式） - **Prettier** - 代码格式化 - **Husky + lint-staged** - Git 提交前检查 - **Jest + ts-jest** - 单元测试 - **Nodemon + ts-node** - 开发热重载 ## 快速开始 ### 1. 克隆项目 ```bash git clone https://github.com/Qimxu/express-next-app.git cd express-next-app ``` ### 2. 安装依赖 ```bash npm install ``` ### 3. 配置环境变量 ```bash cp .env.example .env # 编辑 .env 文件配置数据库等信息（开发环境可保持默认） ``` ### 4. 创建数据库 ```bash # 创建数据库 mysql -u root -p -e "CREATE DATABASE express_next_app CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;" # 运行迁移 npm run migrate ``` ### 5. 启动开发服务器 ```bash npm run dev ``` 应用将在 http://localhost:3000 启动，前后端共用此端口： - API 路由: `http://localhost:3000/api/*` - Next.js 页面: `http://localhost:3000/*` - 健康检查: `http://localhost:3000/health` ### 6. 构建生产版本 ```bash npm run build npm start ``` ## 项目结构 ``` express-next-app/ ├── app/ # Next.js 前端 (App Router) │ ├── [locale]/ # 国际化路由 (en, zh) │ ├── api/ # Next.js API 路由 │ ├── layout.tsx # 根布局 │ └── page.tsx # 首页 ├── src/ # 后端源码 │ ├── core/ # 核心功能 │ │ ├── config/ # 配置加载 (YAML) │ │ ├── router/ # 路由加载器 │ │ ├── types/ # 全局类型定义 │ │ └── utils/ # 工具函数 │ │ ├── database.ts # MySQL 连接池 │ │ ├── logger.ts # Winston 日志 │ │ └── redis.ts # Redis 客户端 │ ├── middlewares/ # Express 中间件 │ │ ├── auth.middleware.ts │ │ ├── error.middleware.ts │ │ ├── rate-limit.middleware.ts │ │ ├── security.middleware.ts │ │ └── validation.middleware.ts │ └── modules/ # 业务模块 │ ├── auth/ # 认证模块 │ │ ├── auth.controller.ts │ │ ├── auth.service.ts │ │ └── auth.types.ts │ └── users/ # 用户模块 │ ├── users.controller.ts │ ├── users.service.ts │ └── dto/ ├── config/ # YAML 配置文件 │ ├── app.config.development.yaml │ ├── app.config.production.yaml │ └── app.config.test.yaml ├── messages/ # i18n 翻译文件 │ ├── en.json │ └── zh.json ├── migrations/ # 数据库迁移 ├── seeds/ # 数据库种子 ├── docs/ # 项目文档 │ ├── API.md # API 接口文档 │ ├── ARCHITECTURE.md # 架构设计文档 │ └── DEPLOYMENT.md # 部署指南 ├── test/ # 测试文件 │ └── test-utils.ts ├── i18n.config.ts # 国际化配置 ├── eslint.config.mjs # ESLint Flat 配置 ├── next.config.ts # Next.js 配置 ├── tsconfig.json # TypeScript 配置 (前端) ├── tsconfig.server.json # TypeScript 配置 (后端) └── package.json ``` ## 文档 | 文档 | 说明 | | ----------------------------------------- | -------------------------------------- | | [API.md](./docs/API.md) | 完整的 API 接口文档，包含请求/响应示例 | | [ARCHITECTURE.md](./docs/ARCHITECTURE.md) | 项目架构设计、模块说明、扩展指南 | | [DEPLOYMENT.md](./docs/DEPLOYMENT.md) | Docker、手动部署、生产环境配置指南 | ## 环境变量 | 变量名 | 说明 | 默认值 | | -------------------- | ------------ | ------------------ | | `NODE_ENV` | 运行环境 | `development` | | `PORT` | 服务器端口 | `3000` | | `DB_HOST` | 数据库主机 | `localhost` | | `DB_PORT` | 数据库端口 | `3306` | | `DB_USERNAME` | 数据库用户名 | `root` | | `DB_PASSWORD` | 数据库密码 | - | | `DB_DATABASE` | 数据库名 | `express_next_app` | | `REDIS_HOST` | Redis 主机 | `localhost` | | `REDIS_PORT` | Redis 端口 | `6379` | | `JWT_SECRET` | JWT 签名密钥 | - | | `JWT_REFRESH_SECRET` | JWT 刷新密钥 | - | ## 可用脚本 | 脚本 | 说明 | | -------------------------- | -------------------------------- | | `npm run dev` | 启动开发服务器（统一端口 3000） | | `npm run build` | 构建生产版本（Next.js + Server） | | `npm start` | 启动生产服务器 | | `npm test` | 运行单元测试 | | `npm run test:coverage` | 运行测试并生成覆盖率报告 | | `npm run migrate` | 执行数据库迁移 | | `npm run migrate:rollback` | 回滚数据库迁移 | | `npm run seed` | 运行数据库种子 | | `npm run lint` | 运行 ESLint 检查 | | `npm run lint:fix` | 自动修复 ESLint 问题 | | `npm run format` | 使用 Prettier 格式化代码 | ## API 文档 ### 认证模块 | 方法 | 路径 | 描述 | | ------ | --------------------------- | ----------------- | | `POST` | `/api/auth/login` | 用户登录 | | `POST` | `/api/auth/register` | 用户注册 | | `POST` | `/api/auth/refresh` | 刷新 Access Token | | `POST` | `/api/auth/logout` | 用户登出 | | `POST` | `/api/auth/forgot-password` | 忘记密码 | | `POST` | `/api/auth/reset-password` | 重置密码 | ### 用户模块 | 方法 | 路径 | 描述 | | -------- | -------------------- | -------------------------- | | `GET` | `/api/users/profile` | 获取当前用户信息（需认证） | | `GET` | `/api/users` | 获取用户列表（需认证） | | `GET` | `/api/users/:id` | 获取指定用户（需认证） | | `POST` | `/api/users` | 创建用户（需认证） | | `PATCH` | `/api/users/:id` | 更新用户（需认证） | | `DELETE` | `/api/users/:id` | 删除用户（需认证） | ### 系统端点 | 方法 | 路径 | 描述 | | ----- | --------- | -------- | | `GET` | `/health` | 健康检查 | ## 核心特性 - ✅ **统一端口架构** - Express + Next.js 共用 3000 端口，简化部署 - ✅ **完整的用户认证系统** - 注册/登录/刷新令牌/登出 - ✅ **JWT 双 Token 机制** - Access Token + Refresh Token，安全可靠 - ✅ **Redis Token 黑名单** - 支持安全登出和令牌吊销 - ✅ **密码重置功能** - 通过邮件链接重置密码 - ✅ **基于角色的权限控制（RBAC）** - 管理员/用户角色分离 - ✅ **API 限流保护** - 基于 express-rate-limit 的防刷保护 - ✅ **输入数据验证** - Zod 运行时类型检查 - ✅ **统一错误处理** - 全局错误中间件，标准化错误响应 - ✅ **结构化日志** - Winston 日志，生产环境自动轮转 - ✅ **国际化支持（i18n）** - 中英文无缝切换 - ✅ **TypeScript 全栈** - 前后端类型安全 - ✅ **Git 提交检查** - Husky + lint-staged 确保代码质量 - ✅ **单元测试** - Jest 测试框架 ## 数据库迁移 ```bash # 创建新迁移 npx knex migrate:make migration_name # 执行所有待运行迁移 npm run migrate # 回滚最后一次迁移 npm run migrate:rollback # 运行种子文件 npm run seed ``` ## 测试 ```bash # 运行所有测试 npm test # 监视模式 npm run test:watch # 生成覆盖率报告 npm run test:coverage ``` ## 提交规范 本项目使用 Husky 和 lint-staged 在提交前自动检查代码： ```bash # 提交时会自动执行 eslint --fix prettier --write ``` 建议提交信息格式： - `feat: 新功能` - `fix: 修复问题` - `docs: 文档更新` - `style: 代码格式（不影响功能）` - `refactor: 重构` - `test: 测试相关` - `chore: 构建/工具相关` ## 设计规范 本项目遵循专业的设计规范： - **字体**: DM Sans, Sora（避免使用 Inter） - **颜色**: Express 绿色系 + Next 蓝色系，使用 OKLCH 色彩空间 - **间距**: 8px 基础间距系统 - **动效**: `cubic-bezier(0.16, 1, 0.3, 1)` 缓动函数 - **无障碍**: 完整的 focus 状态、语义化 HTML、支持 `prefers-reduced-motion` ## 生产部署 ### Docker 部署 ```bash # 构建镜像 docker build -t express-next-app . # 运行容器 docker run -p 3000:3000 --env-file .env express-next-app ``` ### 手动部署 1. 安装依赖：`npm ci --production` 2. 构建：`npm run build` 3. 配置环境变量 4. 启动：`npm start` ## 许可证 MIT © Qimxu