# node-koa-template

**Repository Path**: Luomenghao/node-koa-template

## Basic Information

- **Project Name**: node-koa-template
- **Description**: nodejs koa模板
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-12
- **Last Updated**: 2026-05-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Nodejs

## README

# Koa + TypeScript 模板项目

基于 Koa + TypeScript + TypeORM 的后端服务模板，内置完整的项目架构、中间件体系和业务模块示例（认证、用户、文件管理）。

## 技术栈

| 类别 | 技术 |
|------|------|
| 框架 | Koa + @koa/router |
| 语言 | TypeScript |
| 数据库 | MySQL + TypeORM |
| 缓存 | Redis (ioredis) |
| 认证 | JWT (jsonwebtoken) + bcryptjs |
| 日志 | 自定义 Logger（按日期/级别分目录、控制台彩色输出） |
| 异常处理 | 层次化异常体系（HttpException 基类 + 14 种异常 + 标准化错误码） |
| 配置管理 | dotenv（多层环境变量加载） |
| 签名验证 | HMAC-SHA256 接口签名（防篡改 + 防重放） |
| 请求校验 | DTO 验证 + BaseDto 基类 |
| 响应格式 | 统一 `{ code, data, message }` 响应包装 |
| 跨域 | @koa/cors |
| 文件上传 | koa-body (multipart/form-data) |
| 静态文件 | koa-static |
| UUID | 实体主键生成 |

## 项目结构

```
node-koa-template/
├── .env                      # 本地环境变量（优先级最高，不提交 Git）
├── .env.development          # 开发环境配置
├── .env.production           # 生产环境配置
├── .env.example              # 环境变量模板
├── database/                 # 数据库相关
│   ├── README.md
│   ├── init.sql              # 一键初始化脚本
│   ├── schemas/              # 表结构定义
│   ├── seeds/                # 种子数据
│   └── migrations/           # 数据库迁移（预留）
├── src/
│   ├── main.ts               # 应用入口
│   ├── app.ts                # Koa 实例创建 & 中间件编排
│   ├── router.ts             # 路由注册入口
│   ├── config/               # 项目配置
│   │   ├── index.ts          # 配置统一出口
│   │   ├── env.ts            # 环境变量加载
│   │   ├── app.config.ts     # 应用基础配置
│   │   ├── database.config.ts# 数据库配置
│   │   ├── jwt.config.ts     # JWT 配置
│   │   ├── redis.config.ts   # Redis 配置
│   │   ├── oss.config.ts     # OSS 配置（预留）
│   │   └── signature.config.ts # 签名验证配置
│   ├── bootstrap/            # 启动引导
│   │   ├── index.ts          # 统一初始化入口
│   │   └── database.ts       # 数据库连接初始化
│   ├── core/                 # 核心服务
│   │   └── signature/        # 签名服务
│   │       ├── index.ts
│   │       └── signature.service.ts
│   ├── common/               # 公共组件
│   │   ├── db/
│   │   │   ├── database.ts   # TypeORM 数据源
│   │   │   └── typeorm-logger.ts # TypeORM 日志适配
│   │   ├── exceptions/       # 异常体系
│   │   │   ├── index.ts
│   │   │   ├── error-codes.ts
│   │   │   ├── base.exception.ts
│   │   │   ├── bad-request.exception.ts
│   │   │   ├── parameter.exception.ts
│   │   │   ├── unauthorized.exception.ts
│   │   │   ├── authentication.exception.ts
│   │   │   ├── forbidden.exception.ts
│   │   │   ├── permission.exception.ts
│   │   │   ├── not-found.exception.ts
│   │   │   ├── conflict.exception.ts
│   │   │   ├── internal-server-error.exception.ts
│   │   │   ├── service.exception.ts
│   │   │   └── signature.exception.ts
│   │   ├── logger/           # 日志系统
│   │   │   ├── index.ts
│   │   │   ├── logger.ts
│   │   │   ├── logger.config.ts
│   │   │   └── request-logger.middleware.ts
│   │   ├── middlewares/      # 中间件
│   │   │   ├── error.middleware.ts
│   │   │   ├── response.middleware.ts
│   │   │   ├── dto.middleware.ts
│   │   │   └── signature.middleware.ts
│   │   ├── redis/            # Redis 客户端
│   │   │   ├── index.ts
│   │   │   ├── redis.client.ts
│   │   │   └── redis.service.ts
│   │   └── utils/
│   │       └── validate.ts
│   ├── shared/               # 共享基类
│   │   └── base/
│   │       ├── base.entity.ts
│   │       └── base.dto.ts
│   └── modules/              # 业务模块
│       ├── auth/             # 认证模块
│       │   ├── auth.routes.ts
│       │   ├── auth.controller.ts
│       │   ├── auth.service.ts
│       │   ├── dto/
│       │   ├── interfaces/
│       │   ├── enums/
│       │   └── constants/
│       ├── user/             # 用户模块
│       │   ├── user.routes.ts
│       │   ├── user.controller.ts
│       │   ├── user.service.ts
│       │   ├── entities/
│       │   ├── dto/
│       │   ├── interfaces/
│       │   ├── enums/
│       │   └── constants/
│       └── file/             # 文件管理模块
│           ├── file.routes.ts
│           ├── file.controller.ts
│           ├── file.service.ts
│           ├── entities/
│           ├── dto/
│           ├── interfaces/
│           ├── enums/
│           ├── constants/
│           └── validators/
├── logs/                     # 日志输出目录
│   └── YYYY-MM-DD/
│       ├── error/
│       ├── warn/
│       ├── info/
│       └── debug/
├── uploads/                  # 文件上传目录
│   └── YYYY/MM/DD/
├── tmp/                      # 临时文件目录
├── dist/                     # 编译输出
├── package.json
├── tsconfig.json
└── README.md
```

## 核心特性

### 1. 中间件执行顺序

```
1. errorMiddleware      → 最外层，捕获所有异常
2. requestLogger        → 请求日志（开始 + 结束 + 耗时）
3. responseMiddleware   → 统一 { code, data, message } 响应包装
4. cors                 → 跨域处理
5. koaBody              → 请求体解析 / 文件上传
6. signatureMiddleware  → 接口签名验证（HMAC-SHA256）
7. koa-static           → 静态文件服务
8. router               → 业务路由
```

### 2. 统一异常处理

基于 `HttpException` 抽象基类，内置多种标准异常类型：

| 异常类 | HTTP 状态码 | 错误码 | 说明 |
|---|---|---|---|
| BadRequestException | 400 | 40000 | 请求参数错误 |
| ParameterException | 400 | 40001 | 参数格式错误 |
| UnauthorizedException | 401 | 40100 | 未授权 |
| AuthenticationException | 401 | 40101 | 认证失败 |
| SignatureErrorException | 401 | 40102 | 签名错误 |
| SignatureExpiredException | 401 | 40103 | 签名过期 |
| SignatureMissingException | 401 | 40104 | 签名缺失 |
| SignatureReplayException | 401 | 40105 | 签名重放 |
| ForbiddenException | 403 | 40300 | 禁止访问 |
| PermissionException | 403 | 40301 | 权限不足 |
| NotFoundException | 404 | 40400 | 资源不存在 |
| ConflictException | 409 | 40900 | 资源冲突 |
| InternalServerErrorException | 500 | 50000 | 服务器内部错误 |
| ServiceException | 500 | 50001 | 服务异常 |

### 3. 统一响应格式

所有成功响应均被包装为：

```json
{
  "code": 10000,
  "data": {},
  "message": "操作成功"
}
```

### 4. 接口签名验证

支持 HMAC-SHA256 签名验证，防止接口被篡改和重放攻击：

- 签名算法：`HMAC-SHA256(timestamp + nonce + sortedQueryString + sortedBodyString)`
- 通过 `X-Signature`、`X-Timestamp`、`X-Nonce` 请求头传递签名参数
- 支持时间戳容忍度配置，防止重放攻击
- 支持路径白名单，可排除健康检查等接口
- 通过 `SIGNATURE_ENABLED` 环境变量控制开关

### 5. DTO 验证

通过 `BaseDto` 基类提供声明式的请求参数验证能力，配合 `validate` 工具函数（`required`、`range`、`length` 等）进行参数校验。

### 6. 实体基类 (BaseEntity)

所有数据库实体继承 `BaseEntity`，自动获得：

- `id`: UUID 主键
- `isLock`: 锁定状态（0/1）
- `isDelete`: 软删除标记（0/1）
- `createdBy` / `createdAt`: 创建人/创建时间
- `updatedBy` / `updatedAt`: 更新人/更新时间

### 7. 日志系统

自定义 Logger：

- 支持 `debug`、`info`、`warn`、`error` 四个级别
- 按日期 + 级别分目录输出日志文件
- 控制台彩色输出
- 请求日志中间件自动记录请求方法、路径、耗时、状态码
- 可通过 `LOG_LEVEL` 环境变量控制日志级别

## 快速开始

### 安装依赖

```bash
npm install
```

### 环境配置

```bash
# 复制环境变量模板
cp .env.example .env.development
```

环境变量加载优先级：`.env.${NODE_ENV}.local` > `.env.${NODE_ENV}` > `.env`

### 配置项说明

```env
# 服务配置
PORT=3000
NODE_ENV=development

# 数据库配置
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=
DB_DATABASE=kb_printer_develop

# 文件上传配置
UPLOAD_DIR=./uploads
MAX_FILE_SIZE=10485760
ALLOWED_IMAGE_TYPES=image/jpeg,image/png,image/gif,image/webp

# 日志配置
LOG_LEVEL=info
LOG_DIR=logs

# JWT 配置
JWT_SECRET=your-jwt-secret-key
JWT_EXPIRES_IN=7d

# Redis 配置
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_DB=0

# 签名验证配置
SIGNATURE_ENABLED=true
SIGNATURE_SECRET=your-signature-secret-key-change-in-production
SIGNATURE_TIMESTAMP_TOLERANCE=300
SIGNATURE_WHITELIST=/api/health
SIGNATURE_HEADER_SIGNATURE=X-Signature
SIGNATURE_HEADER_TIMESTAMP=X-Timestamp
SIGNATURE_HEADER_NONCE=X-Nonce
```

### 数据库初始化

```bash
# 一键初始化
mysql -u root -p < database/init.sql
```

### 运行

```bash
# 开发模式（热重载）
npm run dev

# 生产模式（编译后运行）
npm run build
npm start
```

## API 文档

### 健康检查

```
GET /api/health
```

### 认证模块

#### 用户注册

```
POST /api/auth/register
Content-Type: application/json

{
  "username": "admin",
  "password": "123456",
  "nickname": "管理员",
  "email": "admin@example.com",
  "phone": "13800138000"
}
```

#### 用户登录

```
POST /api/auth/login
Content-Type: application/json

{
  "username": "admin",
  "password": "123456"
}
```

响应：

```json
{
  "code": 10000,
  "data": {
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "expiresIn": 7200
  },
  "message": "操作成功"
}
```

### 用户模块

#### 创建用户

```
POST /api/user
Content-Type: application/json

{
  "username": "user001",
  "password": "123456",
  "nickname": "用户001"
}
```

#### 获取用户列表

```
GET /api/user/list?page=1&pageSize=20&keyword=admin&status=active
```

#### 获取用户详情

```
GET /api/user/:id
```

#### 更新用户

```
PUT /api/user/:id
Content-Type: application/json

{
  "nickname": "新昵称",
  "email": "new@example.com"
}
```

#### 删除用户

```
DELETE /api/user/:id
```

### 文件模块

#### 上传文件

```
POST /api/file/upload
Content-Type: multipart/form-data

file: [选择文件]
```

#### 获取文件列表

```
GET /api/file/list?page=1&pageSize=20&fileType=image
```

#### 获取文件详情

```
GET /api/file/:id
```

#### 删除文件

```
DELETE /api/file/:id
```

## 公共组件说明

| 组件 | 路径 | 说明 |
|------|------|------|
| 异常体系 | [src/common/exceptions/](src/common/exceptions/) | 层次化异常，14 种标准异常 + 错误码 |
| 日志系统 | [src/common/logger/](src/common/logger/) | 按日期分目录，支持多级别，控制台彩色输出 |
| 中间件 | [src/common/middlewares/](src/common/middlewares/) | 异常捕获、响应包装、DTO 验证、签名验证 |
| Redis | [src/common/redis/](src/common/redis/) | ioredis 客户端封装，提供常用操作 |
| 数据库 | [src/common/db/](src/common/db/) | TypeORM 数据源配置 |
| 验证工具 | [src/common/utils/](src/common/utils/) | required、range、length 等验证函数 |
| 签名服务 | [src/core/signature/](src/core/signature/) | HMAC-SHA256 签名生成与验证 |

## 业务模块说明

| 模块 | 路径 | 功能 |
|------|------|------|
| 认证 | [src/modules/auth/](src/modules/auth/) | 注册、登录、JWT Token 签发 |
| 用户 | [src/modules/user/](src/modules/user/) | 用户 CRUD、分页查询、软删除 |
| 文件 | [src/modules/file/](src/modules/file/) | 文件上传、分页查询、详情查询、软删除 |

## 注意事项

### 数据库
- 开发环境自动开启 `synchronize`（实体自动同步表结构）
- 生产环境禁止 `synchronize`，需使用 migration
- 删除操作采用软删除策略（`isDelete` 标记）

### 文件上传
- 默认限制 10MB，可通过 `MAX_FILE_SIZE` 环境变量调整
- 支持图片类型：jpeg、png、gif、webp
- 上传文件按 `年/月/日` 目录结构存储

### Redis
- 采用 `lazyConnect` 模式，由应用显式控制连接
- 连接失败会抛出异常，阻塞应用启动

### 签名验证
- 默认开启，可通过 `SIGNATURE_ENABLED=false` 关闭
- 客户端需在请求头携带 `X-Signature`、`X-Timestamp`、`X-Nonce`
- 生产环境务必修改 `SIGNATURE_SECRET`

### 环境变量
- 本地 `.env` 文件优先级最高，不应提交到 Git
- 敏感信息（密钥、密码）不要在 `.env.example` 中填写真实值

### 认证
- Access Token 有效期 2 小时，Refresh Token 有效期 7 天
- 密码使用 bcryptjs 加密存储（10 轮哈希）
- 登录/注册接口在签名白名单之外，调用时需携带签名参数

## 作者

Haor