1. 事务边界治理概述
1.1 什么是事务边界
事务边界（Transaction Boundary）是指一组数据库操作在逻辑上被视作一个不可分割的原子单元时，其开始与结束之间的范围。在关系型数据库中，事务通过 ACID（原子性、一致性、隔离性、持久性）特性保证数据完整性。事务边界定义了哪些操作属于同一个事务，以及事务何时提交或回滚。
| 维度 | 说明 | 典型边界标识 |
|---|---|---|
| 开始边界 | 事务启动的时机 | BEGIN TRANSACTION / @Transactional() 装饰器 |
| 操作范围 | 事务内包含的数据库操作集合 | 多个 Repository 调用、跨表更新 |
| 结束边界 | 事务提交或回滚的决策点 | COMMIT / ROLLBACK / 异常抛出 |
| 传播边界 | 嵌套事务或跨服务调用时的边界扩散 | REQUIRES_NEW / NESTED 传播行为 |
核心观点：事务边界不是数据库独有的概念——在微服务架构中，事务边界会跨越多个服务、多个数据库甚至消息队列，此时边界治理的复杂度呈指数级上升。
1.2 为什么在 API 层面需要治理
传统单体应用中，事务边界通常由数据库或 ORM 框架隐式管理。但在 NestJS 构建的企业级 API 中，事务边界治理面临以下驱动力：
- API 作为事务入口：REST/gRPC/GraphQL API 是外部请求进入系统的唯一通道，事务必须在 API 层明确声明边界，否则数据库连接池和锁资源将失控。
- 跨资源操作：一个 API 端点可能同时更新用户表、订单表和库存表，缺少显式边界会导致部分成功、部分失败的数据不一致。
- 分布式事务需求：微服务间通过 API 调用链完成业务，事务边界需要从单个服务扩展到 Saga、TCC 等分布式模式。
- 可观测性与审计：API 层的事务边界是日志追踪、性能监控和故障恢复的锚点，没有边界则无法定位事务失败根因。
实践建议：在 NestJS 中，每个 Controller 方法都应该被视为一个潜在的事务边界起点。即使当前方法只读，也要考虑未来扩展为写操作时的边界一致性。
1.3 NestJS 中的事务挑战
NestJS 基于 TypeScript 和装饰器模式，提供了 @Transactional() 等开箱即用的事务支持，但在实际企业级项目中，开发者常遇到以下挑战：
| 挑战类别 | 具体问题 | 典型场景 |
|---|---|---|
| 装饰器边界模糊 | @Transactional() 作用在 Service 方法上，但 Controller 层也可能需要事务 |
Controller 中调用多个 Service 方法，期望原子提交 |
| 异步上下文丢失 | NestJS 使用 async_hooks 管理事务上下文，但异步回调、定时任务中容易丢失 |
setTimeout、Observable、EventEmitter 内的事务传播 |
| 跨模块事务传播 | 不同 Feature Module 之间的事务边界无法自动继承 | OrderModule 调用 PaymentModule 的服务，事务回滚不一致 |
| ORM 耦合 | TypeORM / Prisma / MikroORM 的事务 API 各不相同，切换 ORM 时边界治理方案需重写 | 从 TypeORM 迁移到 Prisma，事务装饰器失效 |
| OpenAPI 规范缺失 | API 文档（Swagger）不描述事务边界，前端和下游服务无法感知事务约束 | 前端连续调用两个 API 期望原子性，但后端未做事务关联 |
常见误区：很多团队认为在 Service 层加上
@Transactional() 就解决了所有事务问题。实际上，事务边界治理需要从 API 契约层开始设计，而不是在代码实现层补救。
1.4 事务边界治理的核心维度
为了系统化解决上述挑战，我们将事务边界治理拆解为四个核心维度，这也是本课程后续章节的展开基础：
- 契约维度：在 OpenAPI 规范中显式声明事务边界、隔离级别、超时时间和回滚条件。
- 代码维度：利用 NestJS 装饰器、拦截器和自定义提供者实现可复用的边界管理。
- 传播维度：设计跨服务、跨模块的事务传播策略，支持 REQUIRED、REQUIRES_NEW、NESTED 等行为。
- 观测维度：通过日志、指标和分布式追踪监控事务边界内的操作状态。
1.5 事务边界治理的典型反模式
在 NestJS 项目中，以下反模式会导致事务边界失控，需要在架构设计阶段主动规避：
- 隐式提交陷阱：在
@Transactional()方法内调用this.repository.save()后立即返回，未考虑后续异步操作失败时的回滚。 - 事务穿透：将
EntityManager或PrismaClient直接注入到 Controller 中，导致事务边界扩散到表现层。 - 嵌套事务滥用：在同一个请求链中多次使用
REQUIRES_NEW，造成数据库连接池耗尽和死锁风险。 - 忽略只读事务：对纯查询操作也开启事务，增加数据库锁竞争和连接开销。