# base-server-nest

**Repository Path**: chaoyu91/base-server-nest

## Basic Information

- **Project Name**: base-server-nest
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-28
- **Last Updated**: 2026-01-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NestJS 后端服务框架

## 1. 项目概述

本项目是一个基于 NestJS 框架的企业级后端服务模板，提供了完整的后端架构解决方案。它包含了认证授权、API 文档、日志记录、缓存管理、任务队列、WebSocket 支持等核心功能，旨在帮助开发者快速构建高质量、可扩展的后端应用。

### 核心功能

- ✅ **模块化架构**：清晰的模块化设计，便于代码维护和扩展
- ✅ **完整的认证授权**：JWT 认证 + Basic Auth 保护
- ✅ **API 文档自动生成**：集成 Swagger，自动生成 API 文档
- ✅ **完善的日志系统**：基于 Winston 的日志记录，支持按日期轮转
- ✅ **缓存管理**：支持 Redis 缓存
- ✅ **任务队列**：基于 Bull 的异步任务处理
- ✅ **WebSocket 支持**：实时通信能力
- ✅ **安全防护**：Helmet、CSRF 保护
- ✅ **代码质量保障**：ESLint + Prettier 代码规范
- ✅ **测试框架**：Jest 测试支持

## 2. 技术栈

| 类别 | 技术/框架 | 版本 |
|------|-----------|------|
| 核心框架 | NestJS | ^11.1.9 |
| 开发语言 | TypeScript | ^5.9.3 |
| HTTP 服务 | Fastify | ^5.6.2 |
| 数据库 ORM | TypeORM | ^0.3.28 |
| 缓存 | Redis | ^5.8.2 |
| 认证 | JWT | ^11.0.1 |
| API 文档 | Swagger | ^11.2.3 |
| 日志 | Winston | ^3.18.3 |
| 任务队列 | Bull | ^4.16.5 |
| WebSocket | NestJS WebSocket | ^11.1.9 |
| 测试 | Jest | ^30.2.0 |
| 代码规范 | ESLint + Prettier | - |

## 3. 项目结构

```
├── src/                      # 源代码目录
│   ├── apis/                 # API 模块目录
│   ├── config/               # 配置文件
│   ├── constants/            # 常量定义
│   ├── database/             # 数据库相关
│   │   ├── entities/         # 数据库实体类
│   │   └── vos/              # 值对象
│   ├── decorators/           # 自定义装饰器
│   ├── filters/              # 异常过滤器
│   ├── guards/               # 守卫（认证授权）
│   ├── interceptors/         # 拦截器
│   ├── interfaces/           # TypeScript 接口定义
│   ├── pipes/                # 管道（数据转换和验证）
│   ├── shared/               # 共享模块
│   ├── types/                # TypeScript 类型定义
│   ├── utils/                # 工具函数
│   ├── app.module.ts         # 根模块
│   └── main.ts               # 应用入口
├── libs/                     # 自定义库
│   ├── redis/                # Redis 客户端库
│   ├── captcha/              # 验证码服务
│   └── excel/                # Excel 处理库
├── dist/                     # 编译输出目录
├── logs/                     # 日志文件目录
├── test/                     # 测试文件
├── nest-cli.json             # Nest CLI 配置
├── tsconfig.json             # TypeScript 配置
└── package.json              # 项目依赖和脚本
```

### 核心目录说明

- **apis/**：存放所有 API 模块，按照业务功能进行模块化组织
- **config/**：应用配置，支持多环境配置
- **database/entities/**：数据库实体类，定义数据模型
- **interceptors/**：请求拦截器，用于统一响应格式、日志记录等
- **guards/**：认证守卫，实现 JWT 认证和权限控制
- **filters/**：异常过滤器，统一处理应用异常
- **pipes/**：数据验证和转换管道
- **shared/**：共享模块，包含队列、事件等公共服务
- **utils/**：通用工具函数

## 4. 安装和运行

### 环境要求

- Node.js 18.x 或更高版本
- pnpm 包管理器
- Redis 服务（用于缓存和队列）
- 数据库服务（根据配置支持多种数据库）

### 安装步骤

1. 克隆项目代码

```bash
git clone <项目地址>
cd base-server-nest
```

2. 安装依赖

```bash
pnpm install
```

### 运行项目

#### 开发模式

```bash
pnpm dev
```

开发模式下，应用会监听文件变化并自动重启，同时输出详细日志。

#### 生产构建

```bash
pnpm build
```

构建完成后，会在 `dist` 目录生成编译后的代码。

#### 生产运行

```bash
pnpm start:prod
```

### 其他脚本

| 脚本命令 | 功能说明 |
|----------|----------|
| `pnpm format` | 格式化代码 |
| `pnpm lint` | 代码 lint 检查 |
| `pnpm test` | 运行单元测试 |
| `pnpm test:cov` | 运行测试并生成覆盖率报告 |
| `pnpm test:e2e` | 运行端到端测试 |

## 5. 配置说明

### 配置文件

项目配置主要集中在 `src/config` 目录下，支持多环境配置。配置加载顺序为：

1. 内置默认配置
2. 环境变量配置
3. 命令行参数配置

### 核心配置项

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `app.port` | 应用端口 | 3000 |
| `app.apiPath` | API 路径前缀 | /api |
| `app.docPath` | Swagger 文档路径 | /doc |
| `app.queuePath` | 任务队列管理路径 | /queue |
| `typeorm` | 数据库连接配置 | - |
| `redis` | Redis 连接配置 | - |
| `jwt` | JWT 认证配置 | - |
| `captcha` | 验证码配置 | - |
| `basicAuth` | Basic Auth 配置 | - |

### 环境变量

主要环境变量：

- `NODE_ENV`：运行环境（development/production）
- `DATABASE_URL`：数据库连接 URL
- `REDIS_URL`：Redis 连接 URL
- `JWT_SECRET`：JWT 密钥

## 6. 开发指南

### 6.1 新增 API 模块

1. 在 `src/apis` 目录下创建新的模块目录
2. 创建控制器、服务和模块文件
3. 在 `src/apis/api.module.ts` 中注册新模块

示例：

```typescript
// src/apis/user/user.module.ts
import { Module } from '@nestjs/common';
import { UserController } from './user.controller';
import { UserService } from './user.service';

@Module({
  controllers: [UserController],
  providers: [UserService],
})
export class UserModule {}
```

### 6.2 新增数据库实体

1. 在 `src/database/entities` 目录下创建新的实体类
2. 使用 TypeORM 装饰器定义实体
3. 运行迁移命令生成数据库表

示例：

```typescript
// src/database/entities/user.entity.ts
import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';

@Entity('sys_user')
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column()
  username: string;

  @Column()
  password: string;

  @Column({ default: true })
  status: boolean;
}
```

### 6.3 自定义装饰器

在 `src/decorators` 目录下创建自定义装饰器，用于扩展 NestJS 功能。

### 6.4 中间件使用

- **守卫（Guards）**：用于认证和权限控制
- **拦截器（Interceptors）**：用于请求前后处理，如统一响应格式、日志记录
- **过滤器（Filters）**：用于异常处理
- **管道（Pipes）**：用于数据验证和转换

### 6.5 依赖注入使用规范

NestJS 采用依赖注入（DI）设计模式，实现了松耦合、可测试的代码结构。以下是本项目中依赖注入的使用规范：

#### 6.5.1 基本使用原则

1. **优先使用构造函数注入**：所有依赖必须通过构造函数注入，禁止使用属性注入
2. **依赖抽象而非具体实现**：依赖接口或抽象类，而非具体类
3. **单一职责原则**：每个服务只负责一个功能领域
4. **明确的依赖关系**：避免循环依赖

#### 6.5.2 服务注册方式

- **模块内服务**：在当前模块的 `providers` 数组中注册
- **全局服务**：使用 `@Global()` 装饰器或在根模块注册
- **自定义提供者**：支持值提供者、类提供者、工厂提供者等多种方式

#### 6.5.3 依赖注入示例

```typescript
// 1. 定义抽象接口
interface IUserService {
  findAll(): Promise<User[]>;
}

// 2. 实现具体服务
@Injectable()
export class UserService implements IUserService {
  constructor(
    @InjectRepository(User) private userRepository: Repository<User>,
    private readonly cacheService: CacheService
  ) {}

  async findAll(): Promise<User[]> {
    return this.userRepository.find();
  }
}

// 3. 注册服务
@Module({
  controllers: [UserController],
  providers: [
    { provide: 'IUserService', useClass: UserService }, // 基于接口的注入
    CacheService
  ]
})
export class UserModule {}

// 4. 使用依赖
@Controller('users')
export class UserController {
  constructor(
    @Inject('IUserService') private readonly userService: IUserService
  ) {}

  @Get()
  async findAll() {
    return this.userService.findAll();
  }
}
```

#### 6.5.4 最佳实践

1. **避免过度依赖**：单个类的依赖数量不宜超过 5 个
2. **使用 `@Inject()` 装饰器**：对于接口或字符串令牌，必须使用 `@Inject()` 装饰器
3. **依赖注入顺序**：将核心依赖放在前面，辅助依赖放在后面
4. **测试友好**：依赖注入便于编写单元测试，可以轻松替换真实依赖为模拟对象
5. **循环依赖处理**：如确需循环依赖，使用 `forwardRef()` 进行处理

#### 6.5.5 禁止事项

- ❌ 禁止使用属性注入（`@Inject()` 装饰器直接用于属性）
- ❌ 禁止在运行时动态修改依赖
- ❌ 禁止在构造函数中执行复杂业务逻辑
- ❌ 禁止依赖具体实现而非抽象

## 7. 项目规范

### 7.1 代码规范

#### 命名规范

- 类名：使用 PascalCase
- 变量和函数名：使用 camelCase
- 常量：使用全大写 + 下划线
- 文件名：使用 kebab-case
- 模块名：使用 PascalCase

#### 代码风格

- 使用 2 个空格缩进
- 行尾使用 LF
- 字符串使用单引号
- 接口名以 `I` 开头
- 类型别名使用 `type` 关键字

#### 注释规范

- 类和函数必须添加 JSDoc 注释
- 复杂逻辑必须添加单行注释
- 公共 API 必须详细注释

### 7.2 Git 提交规范

遵循 [Conventional Commits](https://www.conventionalcommits.org/zh-hans/v1.0.0/) 规范：

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

#### 提交类型

- `feat`：新增功能
- `fix`：修复 bug
- `docs`：文档更新
- `style`：代码风格调整
- `refactor`：代码重构
- `perf`：性能优化
- `test`：测试相关
- `chore`：构建或依赖更新
- `revert`：回滚提交

### 7.3 测试规范

- 单元测试覆盖率不低于 80%
- 关键业务逻辑必须有测试用例
- 使用 Jest 测试框架
- 测试文件命名：`*.spec.ts`

## 8. 监控和维护

### 8.1 日志管理

- 日志文件位于 `logs` 目录
- 按日期自动轮转
- 支持不同日志级别：debug、info、warn、error
- 包含请求日志、错误日志、操作日志

### 8.2 健康检查

应用提供了健康检查端点，可用于监控系统状态。

### 8.3 性能监控

- 集成了请求响应时间监控
- 支持缓存命中率统计
- 任务队列状态监控

## 9. 后续开发建议

### 9.1 功能扩展

1. **API 网关集成**：添加 API 网关，实现请求路由和负载均衡
2. **微服务架构**：将现有模块拆分为微服务
3. **消息队列**：集成 Kafka 或 RabbitMQ，实现可靠消息传递
4. **文件存储**：集成对象存储服务，如 MinIO、AWS S3
5. **定时任务**：添加定时任务管理功能
6. **API 版本控制**：实现 API 版本管理

### 9.2 性能优化

1. **数据库索引优化**：根据查询模式优化数据库索引
2. **缓存策略优化**：合理设置缓存过期时间和缓存键
3. **并发处理优化**：优化异步操作和并发请求处理
4. **内存管理**：监控和优化内存使用
5. **数据库连接池**：优化数据库连接池配置

### 9.3 安全增强

1. **API 限流**：添加 API 限流功能，防止恶意请求
2. **数据加密**：敏感数据加密存储
3. **API 密钥管理**：实现 API 密钥认证
4. **安全审计**：增强安全审计日志
5. **漏洞扫描**：定期进行漏洞扫描

### 9.4 开发效率提升

1. **自动化部署**：实现 CI/CD 自动化部署流程
2. **代码生成器**：添加代码生成器，快速生成基础代码
3. **API 文档自动同步**：实现 API 文档自动同步到团队协作工具
4. **开发环境一键搭建**：提供 Docker 容器化部署方案
5. **测试自动化**：增强自动化测试覆盖率

## 10. 常见问题

### 10.1 如何添加新的数据库实体？

1. 在 `src/database/entities` 目录下创建实体类
2. 运行 `pnpm typeorm migration:generate` 生成迁移文件
3. 运行 `pnpm typeorm migration:run` 执行迁移

### 10.2 如何配置多环境？

1. 在 `src/config` 目录下创建不同环境的配置文件
2. 通过 `NODE_ENV` 环境变量指定运行环境

### 10.3 如何访问 Swagger 文档？

开发模式下，访问 `http://localhost:3000/doc` 即可查看 API 文档。

### 10.4 如何监控任务队列？

访问 `http://localhost:3000/queue` 即可查看任务队列状态。

## 11. 贡献指南

欢迎提交 Issue 和 Pull Request！

### 贡献流程

1. Fork 项目
2. 创建特性分支：`git checkout -b feat/xxx`
3. 提交代码：`git commit -m 'feat: add xxx'`
4. 推送分支：`git push origin feat/xxx`
5. 提交 Pull Request

## 12. 许可证

MIT License

## 13. 联系方式

如有问题或建议，请通过以下方式联系：

- 项目地址：<项目仓库地址>
- 维护者：<维护者信息>
- 邮箱：<联系邮箱>

---

**© 2025 base-server-nest. All rights reserved.**