NestJS Boilerplate项目架构解析：基于六边形架构的设计实践-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00944/article/details/148552783

NestJS Boilerplate项目架构解析：基于六边形架构的设计实践

nestjs-boilerplate NestJS boilerplate. Auth, TypeORM, Postgres, Mailing, I18N, Docker. 项目地址: https://gitcode.com/gh_mirrors/ne/nestjs-boilerplate

前言

在现代后端应用开发中，清晰的架构设计对于项目的可维护性和可扩展性至关重要。本文将深入解析NestJS Boilerplate项目采用的六边形架构（Hexagonal Architecture）设计，帮助开发者理解其核心思想与实现方式。

什么是六边形架构？

六边形架构（又称端口与适配器架构）是一种将业务逻辑与外部依赖隔离的设计模式。其核心思想是将应用程序划分为三个主要层次：

领域层（Domain）：包含纯粹的业务逻辑和领域模型
端口层（Ports）：定义应用程序与外部世界的交互接口
适配器层（Adapters）：实现端口接口，处理与具体技术栈的交互

这种架构通过明确的边界划分，使得业务逻辑不依赖于任何具体的技术实现，从而获得更好的可测试性和可替换性。

为什么选择六边形架构？

NestJS Boilerplate采用六边形架构主要基于以下优势：

关注点分离：业务逻辑与基础设施完全解耦
技术无关性：可轻松更换数据库、文件存储等基础设施
可测试性：核心业务逻辑可独立于外部依赖进行测试
演进能力：系统各组件可独立演进而不互相影响

模块结构详解

让我们深入分析项目的典型模块结构：

.
├── domain
│   └── [DOMAIN_ENTITY].ts
├── dto
│   ├── create.dto.ts
│   ├── find-all.dto.ts
│   └── update.dto.ts
├── infrastructure
│   └── persistence
│       ├── document
│       │   ├── document-persistence.module.ts
│       │   ├── entities
│       │   │   └── [SCHEMA].ts
│       │   ├── mappers
│       │   │   └── [MAPPER].ts
│       │   └── repositories
│       │       └── [ADAPTER].repository.ts
│       ├── relational
│       │   ├── entities
│       │   │   └── [ENTITY].ts
│       │   ├── mappers
│       │   │   └── [MAPPER].ts
│       │   ├── relational-persistence.module.ts
│       │   └── repositories
│       │       └── [ADAPTER].repository.ts
│       └── [PORT].repository.ts
├── controller.ts
├── module.ts
└── service.ts

关键组件说明

领域实体（Domain Entity）
- 代表业务核心概念
- 不包含任何基础设施依赖
- 只关注业务规则和状态
数据传输对象（DTO）
- 定义API接口的输入输出格式
- 包含数据验证逻辑
- 通常分为创建、更新和查询等类型
基础设施层
- 持久化模块：处理数据存储相关逻辑
  - 文档型数据库：MongoDB等NoSQL实现
  - 关系型数据库：PostgreSQL等SQL实现
- 映射器（Mapper）：负责领域对象与持久化对象间的转换
- 端口（Port）：定义存储操作的抽象接口
- 适配器（Adapter）：具体存储技术的实现

最佳实践建议

仓储模式实现

在实现仓储接口时，应避免创建过于通用的方法，而应采用单一职责原则：

// 不推荐 - 过于通用的查询方法
export class UsersRelationalRepository implements UserRepository {
  async find(condition: UniversalConditionInterface): Promise<User> {
    // 实现细节
  }
}

// 推荐 - 职责单一的具体方法
export class UsersRelationalRepository implements UserRepository {
  async findByEmail(email: string): Promise<User> {
    // 实现细节
  }
  
  async findByRoles(roles: string[]): Promise<User> {
    // 实现细节
  }
  
  async findByIds(ids: string[]): Promise<User> {
    // 实现细节
  }
}

这种设计使得每个方法都有明确的意图，更易于维护和扩展。