EntAPI事务边界 - 第2节
2.1 EntAPI 的定位：从“流量代理”到“事务边界引擎”
传统 API 网关的核心职责是流量代理、路由转发、限流熔断与安全认证。EntAPI 在此基础上，将自身定位为企业级事务边界引擎——它不仅管理请求的入口，更管理请求在多个微服务、数据源、外部系统之间的事务一致性边界。
核心定位转变：
传统网关：请求 → 路由 → 转发 → 返回
EntAPI：请求 → 事务边界解析 → 分布式协调 → 一致性保障 → 返回
传统网关：请求 → 路由 → 转发 → 返回
EntAPI：请求 → 事务边界解析 → 分布式协调 → 一致性保障 → 返回
EntAPI 的定位可以概括为三个层次：
- 边界定义层：通过声明式配置，定义跨服务调用的事务边界范围（本地事务、Saga、TCC、XA）。
- 协调执行层：在边界内协调多个参与方的提交或回滚，确保最终一致性或强一致性。
- 可观测层：提供事务边界内的全链路追踪、状态快照、补偿日志，便于排障与审计。
2.2 EntAPI 核心组件
EntAPI 由六大核心组件构成，各组件协同完成事务边界的定义、解析、协调与监控。
| 组件名称 | 职责 | 关键能力 |
|---|---|---|
| 事务边界解析器 | 解析 API 声明中的事务边界配置 | 支持 YAML/JSON/注解三种声明方式 |
| 事务协调器 | 管理事务生命周期（开始、提交、回滚、补偿） | 内置 Saga、TCC、XA 三种协调策略 |
| 参与方代理 | 封装下游服务/数据库的调用与状态反馈 | 自动生成补偿操作、幂等校验 |
| 状态存储 | 持久化事务状态与补偿日志 | 支持 MySQL、Redis、Kafka 三种后端 |
| 超时与重试引擎 | 处理超时、网络抖动、部分失败场景 | 可配置重试次数、退避策略、降级回调 |
| 可观测性模块 | 暴露事务指标、链路追踪、事件流 | 集成 OpenTelemetry、Prometheus、ELK |
实践建议：在项目初期，建议先使用“事务边界解析器 + 事务协调器 + 状态存储”三个核心组件搭建最小闭环，后续再逐步接入可观测性模块。
2.3 EntAPI 与传统 API 网关的区别
传统 API 网关（如 Kong、Zuul、Spring Cloud Gateway）与 EntAPI 在架构理念、核心能力、适用场景上存在本质差异。下表从 8 个关键维度进行对比：
| 对比维度 | 传统 API 网关 | EntAPI |
|---|---|---|
| 核心职责 | 流量路由、限流、认证 | 事务边界定义、协调、一致性保障 |
| 事务支持 | 无（仅透传 HTTP 请求） | 内置 Saga、TCC、XA 事务模型 |
| 状态管理 | 无状态（推荐） | 有状态（事务状态持久化） |
| 补偿能力 | 无 | 自动生成补偿操作，支持幂等重试 |
| 超时处理 | 简单超时断开 | 超时重试 + 降级 + 补偿回滚 |
| 可观测性 | 请求级别（延迟、错误率） | 事务级别（状态快照、补偿日志、链路追踪） |
| 配置复杂度 | 路由规则 + 插件 | 路由规则 + 事务边界声明 + 补偿策略 |
| 典型场景 | API 聚合、微服务网关 | 分布式事务、跨服务数据一致性、补偿编排 |
架构决策提示：如果系统仅需要统一入口、限流、认证，传统 API 网关足够。当业务涉及跨多个微服务的“写操作一致性”时（如订单→库存→支付→积分），才需要引入 EntAPI 的事务边界能力。切勿将 EntAPI 当作普通网关使用，否则会引入不必要的状态复杂度。
2.3.1 架构定位对比图
下图从架构层次角度展示传统 API 网关与 EntAPI 在系统中所处位置的不同：
传统 API 网关位于流量入口层，与业务逻辑解耦；EntAPI 位于业务协调层，深度参与服务间的事务边界管理。两者可以共存：EntAPI 部署在传统网关之后，专门处理需要事务保障的写操作路由。
2.4 本章小结
- EntAPI 的定位是事务边界引擎，而非传统流量代理。
- 六大核心组件覆盖了事务边界的定义、协调、代理、存储、容错、观测全流程。
- 与传统 API 网关相比，EntAPI 的核心差异在于有状态、可补偿、事务级可观测。
- 在实际架构中，EntAPI 与传统网关可以分层共存，各司其职。