# express-knex

**Repository Path**: wangpy/express-knex

## Basic Information

- **Project Name**: express-knex
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-26
- **Last Updated**: 2025-10-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Express + Knex Application

一个基于 Express.js 和 Knex.js 构建的现代化 Node.js 应用程序，采用大厂级别的项目架构和最佳实践。

## 🚀 特性

- **模块化架构**: 清晰的模块划分，易于维护和扩展
- **数据库集成**: 使用 Knex.js 进行数据库操作和迁移管理
- **身份验证**: JWT 基础的用户认证和授权系统
- **数据验证**: 使用 Joi 进行严格的数据验证
- **错误处理**: 全局错误处理和标准化的错误响应
- **安全性**: 集成多种安全中间件
- **测试覆盖**: Jest 单元测试和集成测试
- **代码规范**: ESLint 代码检查和格式化
- **Docker 支持**: 完整的容器化部署方案

## 📁 项目结构

```
src/
├── app.js                      # 应用主文件
├── server.js                   # 服务器启动文件
├── config/                     # 配置文件
│   └── index.js
├── database/                   # 数据库相关
│   ├── connection.js           # 数据库连接
│   ├── migrations/             # 数据库迁移文件
│   └── seeds/                  # 数据库种子文件
├── middleware/                 # 中间件
│   ├── auth.js                 # 认证中间件
│   ├── error-handler.js        # 错误处理中间件
│   ├── not-found-handler.js    # 404处理中间件
│   └── validation.js           # 验证中间件
├── modules/                    # 业务模块
│   └── user/                   # 用户模块
│       ├── user.controller.js  # 控制器
│       ├── user.service.js     # 业务逻辑
│       ├── user.model.js       # 数据模型
│       ├── user.validation.js  # 数据验证
│       └── __tests__/          # 测试文件
├── routes/                     # 路由定义
│   └── index.js
└── utils/                      # 工具函数
    ├── logger.js               # 日志工具
    └── response-formatter.js   # 响应格式化
```

## 🛠️ 安装和设置

### 1. 克隆项目并安装依赖

```bash
npm install
```

### 2. 环境配置

复制环境变量文件并配置：

```bash
cp .env.example .env
```

编辑 `.env` 文件，配置数据库连接等信息。

### 3. 数据库设置

运行数据库迁移：

```bash
npm run migrate:latest
```

运行种子数据：

```bash
npm run seed:run
```

### 4. 启动应用

开发环境：

```bash
npm run dev
```

生产环境：

```bash
npm start
```

## 🐳 Docker 部署

### 快速启动（推荐使用 npm 脚本）

开发环境：
```bash
# 启动开发环境（包含热重载）
npm run docker:dev

# 查看日志
npm run docker:dev:logs

# 停止开发环境
npm run docker:dev:down
```

生产环境：
```bash
# 启动生产环境
npm run docker:prod

# 查看日志
npm run docker:prod:logs

# 停止生产环境
npm run docker:prod:down
```

### 数据库操作

```bash
# 运行数据库迁移
npm run db:migrate

# 运行种子数据
npm run db:seed

# 重置数据库（回滚 + 迁移 + 种子数据）
npm run db:reset
```

### 其他常用命令

```bash
# 查看容器状态
npm run docker:ps

# 重启服务
npm run docker:restart

# 构建镜像
npm run docker:build

# 清理未使用的镜像和容器
npm run docker:clean

# 查看应用日志
npm run logs
```

### Docker 服务地址

**开发环境**:
- 应用服务: http://localhost:3000
- MySQL: localhost:3307
- Redis: localhost:6380

**生产环境**:
- 应用入口: http://localhost (Nginx)
- 直接访问: http://localhost:3000
- MySQL: localhost:3306
- Redis: localhost:6379

详细的 Docker 配置和使用说明请查看 [docs/DOCKER.md](./docs/DOCKER.md)

## 🚀 生产环境部署

### 环境变量配置

生产环境需要创建 `.env` 文件：

```bash
# 复制环境配置模板
cp .env.example .env

# 修改必要的配置项
vi .env
```

⚠️ **安全警告**：生产环境必须修改以下配置：
- `DB_PASSWORD`: 数据库密码
- `JWT_SECRET`: JWT密钥（至少32位随机字符）
- `REDIS_PASSWORD`: Redis密码

### PM2 部署（推荐）

```bash
# 快速部署
./scripts/deploy.sh setup    # 初始化环境
./scripts/deploy.sh deploy   # 部署应用

# 管理命令
./scripts/deploy.sh status   # 查看状态
./scripts/deploy.sh logs     # 查看日志
./scripts/deploy.sh restart  # 重启应用
./scripts/deploy.sh backup   # 备份数据库
```

### 手动部署

```bash
# 1. 安装依赖
npm ci --only=production

# 2. 运行数据库迁移
npm run migrate:latest

# 3. 启动应用
npm run pm2:start
```

详细的部署指南请查看 [docs/DEPLOYMENT.md](./docs/DEPLOYMENT.md)
```

## 📝 API 文档

### 用户认证

#### 注册用户
```http
POST /api/v1/users/register
Content-Type: application/json

{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "Password123",
  "firstName": "John",
  "lastName": "Doe"
}
```

#### 用户登录
```http
POST /api/v1/users/login
Content-Type: application/json

{
  "email": "john@example.com",
  "password": "Password123"
}
```

#### 获取用户资料
```http
GET /api/v1/users/profile
Authorization: Bearer <token>
```

### 用户管理 (管理员权限)

#### 获取所有用户
```http
GET /api/v1/users?page=1&limit=10&status=active
Authorization: Bearer <admin_token>
```

#### 获取指定用户
```http
GET /api/v1/users/:id
Authorization: Bearer <admin_token>
```

#### 更新用户
```http
PUT /api/v1/users/:id
Authorization: Bearer <admin_token>
Content-Type: application/json

{
  "status": "inactive"
}
```

#### 删除用户
```http
DELETE /api/v1/users/:id
Authorization: Bearer <admin_token>
```

## 🧪 测试

运行所有测试：

```bash
npm test
```

运行测试并监听变化：

```bash
npm run test:watch
```

## 🔧 开发工具

### 代码检查

```bash
npm run lint
```

### 代码格式化

```bash
npm run lint:fix
```

### 数据库操作

```bash
# 运行最新迁移
npm run migrate:latest

# 回滚迁移
npm run migrate:rollback

# 运行种子数据
npm run seed:run
```

## 🐳 Docker 管理命令

```bash
# 开发环境
./scripts/docker-manager.sh dev-up        # 启动开发环境
./scripts/docker-manager.sh dev-down      # 停止开发环境
./scripts/docker-manager.sh dev-logs      # 查看开发环境日志

# 生产环境
./scripts/docker-manager.sh prod-up       # 启动生产环境
./scripts/docker-manager.sh prod-down     # 停止生产环境
./scripts/docker-manager.sh prod-logs     # 查看生产环境日志

# 工具命令
./scripts/docker-manager.sh build         # 构建应用镜像
./scripts/docker-manager.sh clean         # 清理未使用的镜像和容器
./scripts/docker-manager.sh db-backup     # 备份数据库
./scripts/docker-manager.sh migrate       # 运行数据库迁移
./scripts/docker-manager.sh seed          # 运行种子数据
```

## 🏗️ 架构设计

### 分层架构

- **Controller Layer**: 处理 HTTP 请求和响应
- **Service Layer**: 业务逻辑处理
- **Model Layer**: 数据访问层
- **Middleware Layer**: 中间件处理

### 设计原则

- **单一职责**: 每个模块只负责一个功能
- **依赖注入**: 降低模块间耦合
- **错误处理**: 统一的错误处理机制
- **数据验证**: 严格的输入验证
- **安全性**: 多层安全防护

## 🔒 安全特性

- JWT 身份验证
- 密码哈希加密
- 输入数据验证
- SQL 注入防护
- CORS 跨域保护
- Helmet 安全头
- 请求大小限制

## 📊 监控和日志

- 结构化日志记录
- 错误跟踪
- 性能监控
- 健康检查端点

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 推送到分支
5. 创建 Pull Request

## 📄 许可证

MIT License