springbootAI 1.8.1__tar.gz → 1.8.3__tar.gz

{springbootai-1.8.1/springbootAI.egg-info → springbootai-1.8.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: springbootAI
-Version: 1.8.1
+Version: 1.8.3
 Summary: Python版Spring Boot框架，集成PyMyBatis ORM
 Author-email: YuConggen <1516933915@qq.com>
 License-Expression: MIT
@@ -86,7 +86,7 @@ Dynamic: license-file
 
 SpringBootAI 是一个借鉴 Spring Boot 编程模型的 Python Web 框架，提供装饰器式组件扫描、依赖注入、FastAPI 路由、配置加载、安全能力、内嵌的 PyMyBatis ORM，以及企业级 AI 模块（对齐 Spring AI 2.0：ChatClient/Advisor/Tools/RAG/Function Calling）。本指南为框架核心综合使用文档；**AI / ORM / Cloud / Excel 等模块的完整注解与功能说明已分离为独立文档**（见下方“模块文档”），本指南相应章节保留概览与跳转链接。
 
-- SpringBootAI 版本：`1.8.1`
+- SpringBootAI 版本：`1.8.3`
 - 内嵌 PyMyBatis 版本：`1.4.0`
 - Python：3.10+
 - 状态：Beta（企业试点）
@@ -95,10 +95,12 @@ SpringBootAI 是一个借鉴 Spring Boot 编程模型的 Python Web 框架，提
 
 ## 模块文档
 
-各模块的注解参考与功能说明已从本指南分离为独立文档，按需查阅：
+第一次使用请先读 [新手入门指南](doc/BEGINNER_GUIDE.md)。它从安装开始，带你创建第一个接口，并解释 Controller、Service、Bean、依赖注入和配置文件是什么。各模块文档统一按“解决什么问题 -> 如何启用 -> 最小示例 -> 如何验证 -> 常见错误 -> 生产边界”组织，按需查阅即可，不要求一次读完。
 
 | 模块 | 文档 | 安装 | 说明 |
 |------|------|------|------|
+| 新手入门 | [BEGINNER_GUIDE.md](doc/BEGINNER_GUIDE.md) | 随核心包 | 从零安装、创建项目、运行接口、打开 Swagger、选择后续模块 |
+| 常用注解模块 | [ANNOTATION_MODULES.md](doc/ANNOTATION_MODULES.md) | 随核心包 | Bean Validation / 条件装配 / 缓存增强 / CSV / `@Version` / `@Transient` |
 | AI（对齐 Spring AI 2.0） | [AI_MODULE.md](doc/AI_MODULE.md) | `pip install springbootAI[ai]` | ChatClient / Advisor / Tools / RAG / Function Calling / ETL / 多厂商 LangChain 化 / 韧性 / 观测 |
 | 内嵌 PyMyBatis ORM 与 DDL | [ORM_MODULE.md](doc/ORM_MODULE.md) | 随核心包 | Mapper 注解 / XML Mapper / 分页 / SQL 安全 / DDL 自动建表 |
 | Spring Cloud（对齐 Cloud Alibaba） | [CLOUD_MODULE.md](doc/CLOUD_MODULE.md) | 随核心包 | 服务注册发现 / 配置刷新 / Feign / Sentinel / Gateway / 负载均衡 / 分布式事务 |
@@ -107,10 +109,19 @@ SpringBootAI 是一个借鉴 Spring Boot 编程模型的 Python Web 框架，提
 | Swagger / OpenAPI（对齐 SpringDoc） | [SWAGGER_MODULE.md](doc/SWAGGER_MODULE.md) | 随核心包 | `@Tag` / `@Operation` / `@ApiResponse` / `@Parameter` / `@Schema` / `@SecurityScheme` 注解驱动 API 文档 + Swagger2 别名 |
 | P0/P1/P2 八大模块 | [EIGHT_MODULES.md](doc/EIGHT_MODULES.md) | 随核心包 | Spring Data Repository / Actuator / 多数据源读写分离 / 事务事件 / 配置松散绑定 / 测试切片 / i18n / WebSocket |
 | 安全 | [SECURITY.md](doc/SECURITY.md) | 随核心包 | JWT 生成校验 / 密码加密（SHA256/MD5/BCrypt）/ SQL 注入防护 / 访问控制 |
+| BeanUtils（属性复制工具） | [BEAN_UTILS.md](doc/BEAN_UTILS.md) | 随核心包 | `copy_properties` / `clone` / `get_property` / `set_property` / `populate` / `describe` 对齐 Spring + Apache Commons BeanUtils |
 | 测试报告 | [TEST_REPORT.md](doc/TEST_REPORT.md) | — | 全量测试用例与覆盖范围 |
 
 > 所有模块文档统一存放于 [`doc/`](doc/) 目录。本指南正文中出现的"已分离至独立文档"链接均指向 `doc/` 下的对应文件。
 
+### 新手推荐阅读顺序
+
+1. 按 [新手入门指南](doc/BEGINNER_GUIDE.md) 跑通 `/api/hello/{name}`。
+2. 阅读本页第 4、6、7 章，理解配置、依赖注入和 Controller。
+3. 做数据库 CRUD 时阅读 [ORM_MODULE.md](doc/ORM_MODULE.md)。
+4. 需要输入校验、缓存或条件开关时阅读 [ANNOTATION_MODULES.md](doc/ANNOTATION_MODULES.md)。
+5. 最后再按业务需要选择安全、Cloud、AI、Excel、WebSocket 或性能测试文档。
+
 ## 目录
 
 1. [框架概述与定位](#1-框架概述与定位)
@@ -142,7 +153,7 @@ SpringBootAI 借鉴了 Spring Boot 的注解和分层习惯，但运行时是 Py
 
 | 组件 | 当前版本 |
 |------|----------|
-| `spring` 框架 API | 1.8.0 |
+| `spring` 框架 API | 1.8.3 |
 | `spring.orm.pymybatis` | 1.4.0 |
 | Python | 3.10+ |
 
@@ -158,7 +169,7 @@ SpringBootAI 借鉴了 Spring Boot 的注解和分层习惯，但运行时是 Py
 - 自动化 ORM 契约测试使用 SQLite；MySQL、PostgreSQL、Oracle 需单独验证。
 - 本地 `@Transactional` 支持全部七种 Spring 传播模式；`REQUIRES_NEW` 和 `NOT_SUPPORTED` 需要连接池有额外可用连接。
 - Profile 会筛选 `@Profile` Bean，但不会自动合并 `application-{profile}.yml`。
-- Nacos、RabbitMQ、Prometheus 依赖外部服务；Sentinel、Seata HTTP-AT、OpenTelemetry 追踪均已内嵌实现无需外部 Server。
+- Nacos、RabbitMQ、Prometheus 依赖外部服务；Sentinel 和 OpenTelemetry 追踪可内嵌运行。HTTP 事务模式是持久化补偿协调器，不提供 Seata AT 强一致性；生产强一致场景必须使用真实 Seata Server 或可靠消息方案。
 - 限流、分布式锁、幂等和缓存语义依赖 Redis 等后端，降级路径需要故障注入。
 
 ### 1.4 注解使用总览
@@ -193,7 +204,7 @@ SpringBootAI 注解会先把元数据放到 `__spring_annotations__`。之后是
 | Nacos 服务发现 | ✅ 可用 | 服务注册/发现/订阅，支持无认证开发模式 |
 | Sentinel 限流熔断 | ✅ 可用 | 内嵌引擎，QPS 限流、异常比例/异常数/慢调用熔断、热点参数限流，无需 Dashboard |
 | 分布式追踪 | ✅ 可用 | 原生 OpenTelemetry(W3C traceparent)，自动 HTTP/Feign 注入，无需 OAP Server |
-| Seata 分布式事务 | ✅ 可用 | 内嵌 HTTP-AT 模式，分支注册/提交/回滚，XID 自动传播，无需 Seata Server |
+| Seata 分布式事务 | ⚠️ 有边界 | `distributed` 对接真实 Seata SDK/Server；`http` 仅提供显式启用的持久化补偿，支持重启恢复和 XID 传播，不等同 AT |
 | API Gateway | ✅ 可用 | 轻量 ASGI/WSGI 网关，路由转发、路径重写、过滤器链、负载均衡 |
 | Prometheus 监控 | ✅ 可用 | Counter/Gauge/Histogram 指标暴露 |
 | Feign 声明式 HTTP | ✅ 可用 | 声明式接口、Fallback 降级、自动传播 XID 和 trace 头 |
@@ -1491,7 +1502,7 @@ class ScheduledTasks:
 | `@SentinelResource` | 限流、业务异常 fallback | 受管 Bean 方法会包装；已内嵌限流熔断引擎，无需 Sentinel Dashboard |
 | `@EnableGateway` | 启用 API Gateway | 元数据标记；配合 `GatewayRouter` 使用，内嵌轻量 ASGI/WSGI 网关 |
 | `@LoadBalanced` | 给 `@Bean` 工厂返回对象添加负载均衡标记 | `@Bean` 方法上会执行，但实际请求仍需配合框架负载均衡客户端 |
-| `@GlobalTransactional` | 通过 Seata 管理全局事务 | 受管 Bean 方法会调用 Seata manager；已内嵌 HTTP-AT 模式，XID 自动通过 Feign 传播；不支持嵌套 |
+| `@GlobalTransactional` | 通过 Seata 管理全局事务 | 受管 Bean 方法调用 Seata manager；HTTP 模式为持久化补偿且要求幂等回调，强一致生产场景使用 `distributed`；不支持嵌套 |
 | `@Valid` | 非空/嵌套对象基础检查 | 受管 Bean 方法会执行简化校验，不等同 Jakarta Bean Validation |
 | `@Validated` | 分组校验 | 会执行简化检查，但 `groups` 当前未驱动真正的分组规则 |
 | `@RabbitListener` | 注册 RabbitMQ 消费者 | 可直接装饰受管 Bean 方法；容器声明队列/交换机、注册回调，并在刷新后启动后台消费；支持同步和异步回调 |
@@ -1964,7 +1975,7 @@ class AdminController:
 
 ### 11.1 @Cacheable
 
-当前 `@Cacheable` 使用 `BeanFactory` 内的本地缓存，默认最多 1000 项、TTL 300 秒。`value` 是缓存命名空间；`key="user_id"` 取同名参数，`key="user_{user_id}"` 使用模板，其他字符串作为固定键；`condition="enabled"`、`condition="!skip_cache"` 或 callable 决定是否缓存。同步方法缓存普通返回值，异步方法会先 `await` 再缓存最终结果，不会缓存 coroutine。缓存不跨进程，也没有对应的自动驱逐注解。写操作后的业务缓存失效不由 ORM 查询缓存自动替代。
+当前缓存默认由 `BeanFactory` 提供本地内存实现，最多 1000 项、TTL 300 秒，不跨进程。`@Cacheable` 负责“先查缓存，未命中才执行方法”；`@CachePut` 负责执行方法后写入新值；`@CacheEvict` 负责删除一个键或清空一个命名空间；`@CacheConfig` 和 `@Caching` 用于统一命名空间或组合多个操作。`value` 是缓存命名空间；`key="user_id"` 取同名参数，`key="user_{user_id}"` 使用模板，其他字符串作为固定键；`condition="enabled"`、`condition="!skip_cache"` 或 callable 决定是否缓存。同步方法缓存普通返回值，异步方法会先 `await` 再缓存最终结果，不会缓存 coroutine。写操作后的业务缓存失效仍需由业务方法显式使用 `@CachePut`/`@CacheEvict`；生产多 worker 或多实例应接入共享 Redis，并自行验证一致性和故障降级。
 
 ### 11.2 @Retryable
 
@@ -2018,7 +2029,7 @@ class CleanupJob:
 
 `@SentinelResource`、`@GlobalTransactional` 和方法级 `@LoadBalanced` 有 AOP 消费路径；`@EnableDiscoveryClient`、`@FeignClient` 等当前主要是元数据，Nacos 实际初始化由 `discovery.enabled` 和 `ApplicationContext` 启动流程控制。Nacos 客户端需要 `nacos-sdk-python`、`NACOS_SERVER`、`NACOS_USERNAME`、`NACOS_PASSWORD`；Nacos 2.2+ Docker 服务端还需要 Base64 token 和 identity 环境变量。
 
-配置 `rabbitmq.enabled: true` 并提供 host、port、username、password、virtual_host。开发环境也应在真实 Nacos、RabbitMQ、Redis 等环境执行集成、断线和重复投递测试。Sentinel、Seata HTTP-AT、OpenTelemetry 追踪、API Gateway 均已内嵌实现，无需外部 Server。
+配置 `rabbitmq.enabled: true` 并提供 host、port、username、password、virtual_host。开发环境也应在真实 Nacos、RabbitMQ、Redis 等环境执行集成、断线和重复投递测试。HTTP 事务模式会将协调元数据写入 `seata.store_path`，并在 worker 启动后周期恢复；它是补偿事务，不是 Seata AT，也不能单独满足支付、订单、库存的一致性要求。
 
 ---
 
@@ -2228,7 +2239,7 @@ class UserMapper:
 | `@LoadBalanced` | 同名注解 | 使用 Python 负载均衡实现；不要复用 `RestTemplate` 用法 |
 | Sentinel `@SentinelResource` | 同名注解 | 已内嵌限流熔断引擎，无需 Dashboard；如需更强大治理能力可对接外部 Sentinel Dashboard |
 | Spring Cloud Gateway | `@EnableGateway` + `GatewayRouter` | 内嵌轻量 ASGI/WSGI 网关；复杂网关需求可使用 Kong/APISIX 等专业网关 |
-| Seata `@GlobalTransactional` | 同名注解 | 已内嵌 HTTP-AT 模式，无需 Seata Server，XID 自动通过 Feign 传播；如需更强一致性保障可对接外部 Seata Server |
+| Seata `@GlobalTransactional` | 同名注解 | `http` 模式是持久化补偿协调器，依赖幂等分支回调；企业强一致场景必须配置真实 Seata Server 与兼容 SDK |
 
 **Cloud 高级功能迁移对照**：
 
@@ -2236,7 +2247,7 @@ class UserMapper:
 |---|---|---|
 | Sentinel Dashboard + `@SentinelResource` | `@SentinelResource` | 内嵌引擎，无需 Dashboard；支持 QPS 限流、异常比例/异常数/慢调用熔断、热点参数限流 |
 | SkyWalking Agent + OAP Server | `@Trace` + 内嵌 Tracer | 原生 OpenTelemetry(W3C traceparent)，无需 OAP Server；自动注入 HTTP/Feign 追踪头 |
-| Seata Server + `@GlobalTransactional` | `@GlobalTransactional` | 内嵌 HTTP-AT 模式，无需 Seata Server；支持分支注册/提交/回滚，XID 自动传播 |
+| Seata Server + `@GlobalTransactional` | `@GlobalTransactional` | `distributed` 模式对接 Seata Server；`http` 仅用于补偿流程和故障演练，不提供 AT 语义 |
 | Spring Cloud Gateway | `GatewayRouter` | 轻量 ASGI/WSGI 网关，支持路由转发、路径重写、过滤器链、负载均衡 |
 | JPA `hibernate.ddl-auto` | `@entity` + `ddl-auto` 配置 | 支持 create/update/validate/create-drop；自动扫描实体包，自动建表/添加列/创建索引 |
 
@@ -2322,7 +2333,7 @@ Java 的 profile 文件自动合并不是当前功能。部署流程应生成最
 4. 用目标 MySQL/PostgreSQL/Oracle 版本执行相同测试，特别验证自增主键、事务隔离、超时和连接中断。
 5. 启动 ASGI 应用，检查 `/docs`、`/actuator/health/liveness` 和 `/actuator/health/readiness`。
 6. 接入 Nacos、RabbitMQ、Redis 等外部中间件，并演练断线、重复投递和回滚。
-7. 验证内嵌 Cloud 功能：`@SentinelResource` 限流熔断、`@Trace` 追踪、`@GlobalTransactional` 分布式事务、`GatewayRouter` 网关、`@entity` + `ddl-auto` 自动建表。这些功能无需部署外部 Server，但应在真实流量和故障注入下验证。
+7. 验证 Cloud 功能：`@SentinelResource` 限流熔断、`@Trace` 追踪、`@GlobalTransactional` 补偿流程、`GatewayRouter` 网关、`@entity` + `ddl-auto` 自动建表。HTTP 补偿模式必须验证重复回调、进程重启和部分失败；强一致事务需部署真实 Seata Server 并执行集成测试。
 
 ---
 
@@ -2446,9 +2457,13 @@ logging:
 | `DISCOVERY_ENABLED` | 是否启用 Nacos 服务发现 | false |
 | `NACOS_SERVER` | Nacos 地址 | localhost:8848 |
 | `NACOS_USERNAME` / `NACOS_PASSWORD` | Nacos 客户端账号/密码 | 空 |
+| `SEATA_HTTP_STORE_PATH` | HTTP 补偿协调 SQLite 文件路径（同主机多 worker 共享） | `./data/seata-http.sqlite3` |
+| `SEATA_HTTP_RECOVER_ON_STARTUP` | 初始化时扫描并恢复未完成补偿 | true |
+| `SEATA_HTTP_RECOVERY_GRACE_MS` | 接管其他 worker 的 COMMITTING/ROLLING_BACK 前等待时间 | 30000 |
+| `SEATA_HTTP_RECOVERY_INTERVAL_S` | worker 内周期恢复间隔，0 表示关闭 | 30 |
 | `SPRING_DISABLE_DOCKER_IP_DETECT` | 设为 1 禁用 Docker 容器 IP 自动检测 | 0 |
 
-> Sentinel、OpenTelemetry 追踪、Seata HTTP-AT、API Gateway 已内嵌实现，没有对应环境变量。
+> HTTP 补偿模式使用 `SEATA_HTTP_*` 配置，仍不提供 Seata AT；生产强一致事务必须配置 `SEATA_MODE=distributed`、真实 Server 和兼容 SDK。
 
 ### 14.5 启动应用
 
@@ -2526,7 +2541,7 @@ curl http://localhost:8080/actuator/health
 }
 ```
 
-> Sentinel、OpenTelemetry 追踪、Seata HTTP-AT、API Gateway 已内嵌实现，不属于外部依赖组件，因此不显示在聚合健康检查中；可通过应用日志或 `@SentinelResource`、`@Trace`、`@GlobalTransactional` 注解的实际调用验证。
+> Sentinel、OpenTelemetry 追踪和 API Gateway 可内嵌运行；HTTP 补偿协调器的未完成事务会纳入恢复日志。它不属于强一致外部事务协调器，不能替代 Seata Server。
 
 ### 14.7 部署故障排查
 
@@ -2751,7 +2766,7 @@ export LOG_LEVEL=INFO
 export LOG_DIR=logs
 ```
 
-> Sentinel 限流熔断、OpenTelemetry 分布式追踪、Seata HTTP-AT 分布式事务、API Gateway 均为内嵌实现，无对应环境变量。AI 模块环境变量见第 12.2 节。
+> Sentinel 限流熔断、OpenTelemetry 分布式追踪和 API Gateway 可内嵌实现；HTTP 补偿事务通过 `SEATA_HTTP_*` 配置。AI 模块环境变量见第 12.2 节。
 
 ## 附录 B：Docker Compose 示例
 

{springbootai-1.8.1 → springbootai-1.8.3}/README.md

@@ -2,7 +2,7 @@
 
 SpringBootAI 是一个借鉴 Spring Boot 编程模型的 Python Web 框架，提供装饰器式组件扫描、依赖注入、FastAPI 路由、配置加载、安全能力、内嵌的 PyMyBatis ORM，以及企业级 AI 模块（对齐 Spring AI 2.0：ChatClient/Advisor/Tools/RAG/Function Calling）。本指南为框架核心综合使用文档；**AI / ORM / Cloud / Excel 等模块的完整注解与功能说明已分离为独立文档**（见下方“模块文档”），本指南相应章节保留概览与跳转链接。
 
-- SpringBootAI 版本：`1.8.1`
+- SpringBootAI 版本：`1.8.3`
 - 内嵌 PyMyBatis 版本：`1.4.0`
 - Python：3.10+
 - 状态：Beta（企业试点）
@@ -11,10 +11,12 @@ SpringBootAI 是一个借鉴 Spring Boot 编程模型的 Python Web 框架，提
 
 ## 模块文档
 
-各模块的注解参考与功能说明已从本指南分离为独立文档，按需查阅：
+第一次使用请先读 [新手入门指南](doc/BEGINNER_GUIDE.md)。它从安装开始，带你创建第一个接口，并解释 Controller、Service、Bean、依赖注入和配置文件是什么。各模块文档统一按“解决什么问题 -> 如何启用 -> 最小示例 -> 如何验证 -> 常见错误 -> 生产边界”组织，按需查阅即可，不要求一次读完。
 
 | 模块 | 文档 | 安装 | 说明 |
 |------|------|------|------|
+| 新手入门 | [BEGINNER_GUIDE.md](doc/BEGINNER_GUIDE.md) | 随核心包 | 从零安装、创建项目、运行接口、打开 Swagger、选择后续模块 |
+| 常用注解模块 | [ANNOTATION_MODULES.md](doc/ANNOTATION_MODULES.md) | 随核心包 | Bean Validation / 条件装配 / 缓存增强 / CSV / `@Version` / `@Transient` |
 | AI（对齐 Spring AI 2.0） | [AI_MODULE.md](doc/AI_MODULE.md) | `pip install springbootAI[ai]` | ChatClient / Advisor / Tools / RAG / Function Calling / ETL / 多厂商 LangChain 化 / 韧性 / 观测 |
 | 内嵌 PyMyBatis ORM 与 DDL | [ORM_MODULE.md](doc/ORM_MODULE.md) | 随核心包 | Mapper 注解 / XML Mapper / 分页 / SQL 安全 / DDL 自动建表 |
 | Spring Cloud（对齐 Cloud Alibaba） | [CLOUD_MODULE.md](doc/CLOUD_MODULE.md) | 随核心包 | 服务注册发现 / 配置刷新 / Feign / Sentinel / Gateway / 负载均衡 / 分布式事务 |
@@ -23,10 +25,19 @@ SpringBootAI 是一个借鉴 Spring Boot 编程模型的 Python Web 框架，提
 | Swagger / OpenAPI（对齐 SpringDoc） | [SWAGGER_MODULE.md](doc/SWAGGER_MODULE.md) | 随核心包 | `@Tag` / `@Operation` / `@ApiResponse` / `@Parameter` / `@Schema` / `@SecurityScheme` 注解驱动 API 文档 + Swagger2 别名 |
 | P0/P1/P2 八大模块 | [EIGHT_MODULES.md](doc/EIGHT_MODULES.md) | 随核心包 | Spring Data Repository / Actuator / 多数据源读写分离 / 事务事件 / 配置松散绑定 / 测试切片 / i18n / WebSocket |
 | 安全 | [SECURITY.md](doc/SECURITY.md) | 随核心包 | JWT 生成校验 / 密码加密（SHA256/MD5/BCrypt）/ SQL 注入防护 / 访问控制 |
+| BeanUtils（属性复制工具） | [BEAN_UTILS.md](doc/BEAN_UTILS.md) | 随核心包 | `copy_properties` / `clone` / `get_property` / `set_property` / `populate` / `describe` 对齐 Spring + Apache Commons BeanUtils |
 | 测试报告 | [TEST_REPORT.md](doc/TEST_REPORT.md) | — | 全量测试用例与覆盖范围 |
 
 > 所有模块文档统一存放于 [`doc/`](doc/) 目录。本指南正文中出现的"已分离至独立文档"链接均指向 `doc/` 下的对应文件。
 
+### 新手推荐阅读顺序
+
+1. 按 [新手入门指南](doc/BEGINNER_GUIDE.md) 跑通 `/api/hello/{name}`。
+2. 阅读本页第 4、6、7 章，理解配置、依赖注入和 Controller。
+3. 做数据库 CRUD 时阅读 [ORM_MODULE.md](doc/ORM_MODULE.md)。
+4. 需要输入校验、缓存或条件开关时阅读 [ANNOTATION_MODULES.md](doc/ANNOTATION_MODULES.md)。
+5. 最后再按业务需要选择安全、Cloud、AI、Excel、WebSocket 或性能测试文档。
+
 ## 目录
 
 1. [框架概述与定位](#1-框架概述与定位)
@@ -58,7 +69,7 @@ SpringBootAI 借鉴了 Spring Boot 的注解和分层习惯，但运行时是 Py
 
 | 组件 | 当前版本 |
 |------|----------|
-| `spring` 框架 API | 1.8.0 |
+| `spring` 框架 API | 1.8.3 |
 | `spring.orm.pymybatis` | 1.4.0 |
 | Python | 3.10+ |
 
@@ -74,7 +85,7 @@ SpringBootAI 借鉴了 Spring Boot 的注解和分层习惯，但运行时是 Py
 - 自动化 ORM 契约测试使用 SQLite；MySQL、PostgreSQL、Oracle 需单独验证。
 - 本地 `@Transactional` 支持全部七种 Spring 传播模式；`REQUIRES_NEW` 和 `NOT_SUPPORTED` 需要连接池有额外可用连接。
 - Profile 会筛选 `@Profile` Bean，但不会自动合并 `application-{profile}.yml`。
-- Nacos、RabbitMQ、Prometheus 依赖外部服务；Sentinel、Seata HTTP-AT、OpenTelemetry 追踪均已内嵌实现无需外部 Server。
+- Nacos、RabbitMQ、Prometheus 依赖外部服务；Sentinel 和 OpenTelemetry 追踪可内嵌运行。HTTP 事务模式是持久化补偿协调器，不提供 Seata AT 强一致性；生产强一致场景必须使用真实 Seata Server 或可靠消息方案。
 - 限流、分布式锁、幂等和缓存语义依赖 Redis 等后端，降级路径需要故障注入。
 
 ### 1.4 注解使用总览
@@ -109,7 +120,7 @@ SpringBootAI 注解会先把元数据放到 `__spring_annotations__`。之后是
 | Nacos 服务发现 | ✅ 可用 | 服务注册/发现/订阅，支持无认证开发模式 |
 | Sentinel 限流熔断 | ✅ 可用 | 内嵌引擎，QPS 限流、异常比例/异常数/慢调用熔断、热点参数限流，无需 Dashboard |
 | 分布式追踪 | ✅ 可用 | 原生 OpenTelemetry(W3C traceparent)，自动 HTTP/Feign 注入，无需 OAP Server |
-| Seata 分布式事务 | ✅ 可用 | 内嵌 HTTP-AT 模式，分支注册/提交/回滚，XID 自动传播，无需 Seata Server |
+| Seata 分布式事务 | ⚠️ 有边界 | `distributed` 对接真实 Seata SDK/Server；`http` 仅提供显式启用的持久化补偿，支持重启恢复和 XID 传播，不等同 AT |
 | API Gateway | ✅ 可用 | 轻量 ASGI/WSGI 网关，路由转发、路径重写、过滤器链、负载均衡 |
 | Prometheus 监控 | ✅ 可用 | Counter/Gauge/Histogram 指标暴露 |
 | Feign 声明式 HTTP | ✅ 可用 | 声明式接口、Fallback 降级、自动传播 XID 和 trace 头 |
@@ -1407,7 +1418,7 @@ class ScheduledTasks:
 | `@SentinelResource` | 限流、业务异常 fallback | 受管 Bean 方法会包装；已内嵌限流熔断引擎，无需 Sentinel Dashboard |
 | `@EnableGateway` | 启用 API Gateway | 元数据标记；配合 `GatewayRouter` 使用，内嵌轻量 ASGI/WSGI 网关 |
 | `@LoadBalanced` | 给 `@Bean` 工厂返回对象添加负载均衡标记 | `@Bean` 方法上会执行，但实际请求仍需配合框架负载均衡客户端 |
-| `@GlobalTransactional` | 通过 Seata 管理全局事务 | 受管 Bean 方法会调用 Seata manager；已内嵌 HTTP-AT 模式，XID 自动通过 Feign 传播；不支持嵌套 |
+| `@GlobalTransactional` | 通过 Seata 管理全局事务 | 受管 Bean 方法调用 Seata manager；HTTP 模式为持久化补偿且要求幂等回调，强一致生产场景使用 `distributed`；不支持嵌套 |
 | `@Valid` | 非空/嵌套对象基础检查 | 受管 Bean 方法会执行简化校验，不等同 Jakarta Bean Validation |
 | `@Validated` | 分组校验 | 会执行简化检查，但 `groups` 当前未驱动真正的分组规则 |
 | `@RabbitListener` | 注册 RabbitMQ 消费者 | 可直接装饰受管 Bean 方法；容器声明队列/交换机、注册回调，并在刷新后启动后台消费；支持同步和异步回调 |
@@ -1880,7 +1891,7 @@ class AdminController:
 
 ### 11.1 @Cacheable
 
-当前 `@Cacheable` 使用 `BeanFactory` 内的本地缓存，默认最多 1000 项、TTL 300 秒。`value` 是缓存命名空间；`key="user_id"` 取同名参数，`key="user_{user_id}"` 使用模板，其他字符串作为固定键；`condition="enabled"`、`condition="!skip_cache"` 或 callable 决定是否缓存。同步方法缓存普通返回值，异步方法会先 `await` 再缓存最终结果，不会缓存 coroutine。缓存不跨进程，也没有对应的自动驱逐注解。写操作后的业务缓存失效不由 ORM 查询缓存自动替代。
+当前缓存默认由 `BeanFactory` 提供本地内存实现，最多 1000 项、TTL 300 秒，不跨进程。`@Cacheable` 负责“先查缓存，未命中才执行方法”；`@CachePut` 负责执行方法后写入新值；`@CacheEvict` 负责删除一个键或清空一个命名空间；`@CacheConfig` 和 `@Caching` 用于统一命名空间或组合多个操作。`value` 是缓存命名空间；`key="user_id"` 取同名参数，`key="user_{user_id}"` 使用模板，其他字符串作为固定键；`condition="enabled"`、`condition="!skip_cache"` 或 callable 决定是否缓存。同步方法缓存普通返回值，异步方法会先 `await` 再缓存最终结果，不会缓存 coroutine。写操作后的业务缓存失效仍需由业务方法显式使用 `@CachePut`/`@CacheEvict`；生产多 worker 或多实例应接入共享 Redis，并自行验证一致性和故障降级。
 
 ### 11.2 @Retryable
 
@@ -1934,7 +1945,7 @@ class CleanupJob:
 
 `@SentinelResource`、`@GlobalTransactional` 和方法级 `@LoadBalanced` 有 AOP 消费路径；`@EnableDiscoveryClient`、`@FeignClient` 等当前主要是元数据，Nacos 实际初始化由 `discovery.enabled` 和 `ApplicationContext` 启动流程控制。Nacos 客户端需要 `nacos-sdk-python`、`NACOS_SERVER`、`NACOS_USERNAME`、`NACOS_PASSWORD`；Nacos 2.2+ Docker 服务端还需要 Base64 token 和 identity 环境变量。
 
-配置 `rabbitmq.enabled: true` 并提供 host、port、username、password、virtual_host。开发环境也应在真实 Nacos、RabbitMQ、Redis 等环境执行集成、断线和重复投递测试。Sentinel、Seata HTTP-AT、OpenTelemetry 追踪、API Gateway 均已内嵌实现，无需外部 Server。
+配置 `rabbitmq.enabled: true` 并提供 host、port、username、password、virtual_host。开发环境也应在真实 Nacos、RabbitMQ、Redis 等环境执行集成、断线和重复投递测试。HTTP 事务模式会将协调元数据写入 `seata.store_path`，并在 worker 启动后周期恢复；它是补偿事务，不是 Seata AT，也不能单独满足支付、订单、库存的一致性要求。
 
 ---
 
@@ -2144,7 +2155,7 @@ class UserMapper:
 | `@LoadBalanced` | 同名注解 | 使用 Python 负载均衡实现；不要复用 `RestTemplate` 用法 |
 | Sentinel `@SentinelResource` | 同名注解 | 已内嵌限流熔断引擎，无需 Dashboard；如需更强大治理能力可对接外部 Sentinel Dashboard |
 | Spring Cloud Gateway | `@EnableGateway` + `GatewayRouter` | 内嵌轻量 ASGI/WSGI 网关；复杂网关需求可使用 Kong/APISIX 等专业网关 |
-| Seata `@GlobalTransactional` | 同名注解 | 已内嵌 HTTP-AT 模式，无需 Seata Server，XID 自动通过 Feign 传播；如需更强一致性保障可对接外部 Seata Server |
+| Seata `@GlobalTransactional` | 同名注解 | `http` 模式是持久化补偿协调器，依赖幂等分支回调；企业强一致场景必须配置真实 Seata Server 与兼容 SDK |
 
 **Cloud 高级功能迁移对照**：
 
@@ -2152,7 +2163,7 @@ class UserMapper:
 |---|---|---|
 | Sentinel Dashboard + `@SentinelResource` | `@SentinelResource` | 内嵌引擎，无需 Dashboard；支持 QPS 限流、异常比例/异常数/慢调用熔断、热点参数限流 |
 | SkyWalking Agent + OAP Server | `@Trace` + 内嵌 Tracer | 原生 OpenTelemetry(W3C traceparent)，无需 OAP Server；自动注入 HTTP/Feign 追踪头 |
-| Seata Server + `@GlobalTransactional` | `@GlobalTransactional` | 内嵌 HTTP-AT 模式，无需 Seata Server；支持分支注册/提交/回滚，XID 自动传播 |
+| Seata Server + `@GlobalTransactional` | `@GlobalTransactional` | `distributed` 模式对接 Seata Server；`http` 仅用于补偿流程和故障演练，不提供 AT 语义 |
 | Spring Cloud Gateway | `GatewayRouter` | 轻量 ASGI/WSGI 网关，支持路由转发、路径重写、过滤器链、负载均衡 |
 | JPA `hibernate.ddl-auto` | `@entity` + `ddl-auto` 配置 | 支持 create/update/validate/create-drop；自动扫描实体包，自动建表/添加列/创建索引 |
 
@@ -2238,7 +2249,7 @@ Java 的 profile 文件自动合并不是当前功能。部署流程应生成最
 4. 用目标 MySQL/PostgreSQL/Oracle 版本执行相同测试，特别验证自增主键、事务隔离、超时和连接中断。
 5. 启动 ASGI 应用，检查 `/docs`、`/actuator/health/liveness` 和 `/actuator/health/readiness`。
 6. 接入 Nacos、RabbitMQ、Redis 等外部中间件，并演练断线、重复投递和回滚。
-7. 验证内嵌 Cloud 功能：`@SentinelResource` 限流熔断、`@Trace` 追踪、`@GlobalTransactional` 分布式事务、`GatewayRouter` 网关、`@entity` + `ddl-auto` 自动建表。这些功能无需部署外部 Server，但应在真实流量和故障注入下验证。
+7. 验证 Cloud 功能：`@SentinelResource` 限流熔断、`@Trace` 追踪、`@GlobalTransactional` 补偿流程、`GatewayRouter` 网关、`@entity` + `ddl-auto` 自动建表。HTTP 补偿模式必须验证重复回调、进程重启和部分失败；强一致事务需部署真实 Seata Server 并执行集成测试。
 
 ---
 
@@ -2362,9 +2373,13 @@ logging:
 | `DISCOVERY_ENABLED` | 是否启用 Nacos 服务发现 | false |
 | `NACOS_SERVER` | Nacos 地址 | localhost:8848 |
 | `NACOS_USERNAME` / `NACOS_PASSWORD` | Nacos 客户端账号/密码 | 空 |
+| `SEATA_HTTP_STORE_PATH` | HTTP 补偿协调 SQLite 文件路径（同主机多 worker 共享） | `./data/seata-http.sqlite3` |
+| `SEATA_HTTP_RECOVER_ON_STARTUP` | 初始化时扫描并恢复未完成补偿 | true |
+| `SEATA_HTTP_RECOVERY_GRACE_MS` | 接管其他 worker 的 COMMITTING/ROLLING_BACK 前等待时间 | 30000 |
+| `SEATA_HTTP_RECOVERY_INTERVAL_S` | worker 内周期恢复间隔，0 表示关闭 | 30 |
 | `SPRING_DISABLE_DOCKER_IP_DETECT` | 设为 1 禁用 Docker 容器 IP 自动检测 | 0 |
 
-> Sentinel、OpenTelemetry 追踪、Seata HTTP-AT、API Gateway 已内嵌实现，没有对应环境变量。
+> HTTP 补偿模式使用 `SEATA_HTTP_*` 配置，仍不提供 Seata AT；生产强一致事务必须配置 `SEATA_MODE=distributed`、真实 Server 和兼容 SDK。
 
 ### 14.5 启动应用
 
@@ -2442,7 +2457,7 @@ curl http://localhost:8080/actuator/health
 }
 ```
 
-> Sentinel、OpenTelemetry 追踪、Seata HTTP-AT、API Gateway 已内嵌实现，不属于外部依赖组件，因此不显示在聚合健康检查中；可通过应用日志或 `@SentinelResource`、`@Trace`、`@GlobalTransactional` 注解的实际调用验证。
+> Sentinel、OpenTelemetry 追踪和 API Gateway 可内嵌运行；HTTP 补偿协调器的未完成事务会纳入恢复日志。它不属于强一致外部事务协调器，不能替代 Seata Server。
 
 ### 14.7 部署故障排查
 
@@ -2667,7 +2682,7 @@ export LOG_LEVEL=INFO
 export LOG_DIR=logs
 ```
 
-> Sentinel 限流熔断、OpenTelemetry 分布式追踪、Seata HTTP-AT 分布式事务、API Gateway 均为内嵌实现，无对应环境变量。AI 模块环境变量见第 12.2 节。
+> Sentinel 限流熔断、OpenTelemetry 分布式追踪和 API Gateway 可内嵌实现；HTTP 补偿事务通过 `SEATA_HTTP_*` 配置。AI 模块环境变量见第 12.2 节。
 
 ## 附录 B：Docker Compose 示例
 

{springbootai-1.8.1 → springbootai-1.8.3}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
 [project]
 # 发行名 springbootAI（PyPI 包名，pip install springbootAI）；导入包名仍为 spring
 name = "springbootAI"
-version = "1.8.1"
+version = "1.8.3"
 description = "Python版Spring Boot框架，集成PyMyBatis ORM"
 readme = "README.md"
 license = "MIT"

{springbootai-1.8.1 → springbootai-1.8.3}/spring/__init__.py

@@ -5,7 +5,7 @@ from .config import *
 from .utils import *
 from .main import create_app, run, SpringApplication, run_cli
 
-__version__ = "1.8.1"
+__version__ = "1.8.3"
 __author__ = "yuconggen"
 __license__ = "MIT"
 

{springbootai-1.8.1 → springbootai-1.8.3}/spring/aop/cloud_aop.py

@@ -3,6 +3,7 @@ Spring Cloud AOP 切面实现（企业级版本）
 使用真实的分布式组件：Seata事务、Nacos服务发现、Sentinel限流熔断等
 """
 from typing import Any, Callable, Dict, List, Optional, Type
+import asyncio
 import time
 import functools
 import threading
@@ -139,17 +140,44 @@ def global_transactional_decorator(annotation: GlobalTransactional):
                 if seata_manager.is_in_transaction():
                     logger.warning("[GlobalTransactional] Nested transaction detected, skipping")
                     return await func(*args, **kwargs)
-                tx_id = begin_transaction()
+                if seata_manager.get_mode() == "http":
+                    tx_id = await asyncio.to_thread(begin_transaction)
+                    transaction_context = await asyncio.to_thread(
+                        seata_manager.get_transaction_context, tx_id
+                    )
+                    if transaction_context is None:
+                        seata_manager._cleanup_context()
+                        raise RuntimeError(
+                            f"Unable to bind durable HTTP transaction context: {tx_id}"
+                        )
+                    seata_manager.bind_transaction_context(transaction_context)
+                else:
+                    tx_id = begin_transaction()
                 start_time = time.monotonic()
                 try:
                     result = await func(*args, **kwargs)
-                    commit_transaction(tx_id, time.monotonic() - start_time)
-                    return result
                 except Exception:
                     if seata_manager.is_in_transaction():
-                        seata_manager.rollback_transaction(tx_id)
+                        try:
+                            await asyncio.to_thread(
+                                seata_manager.rollback_transaction, tx_id
+                            )
+                        finally:
+                            # Context changes in to_thread stay in its copied
+                            # context, so clear the event-loop task explicitly.
+                            seata_manager._cleanup_context()
                     raise
 
+                try:
+                    await asyncio.to_thread(
+                        commit_transaction,
+                        tx_id,
+                        time.monotonic() - start_time,
+                    )
+                    return result
+                finally:
+                    seata_manager._cleanup_context()
+
             return async_wrapper
 
         @functools.wraps(func)

{springbootai-1.8.1 → springbootai-1.8.3}/spring/cloud/__init__.py

@@ -18,6 +18,7 @@ from spring.cloud.seata import (
     SeataTransactionManager,
     BranchStatus,
 )
+from spring.cloud.transaction_store import SQLiteTransactionStore
 from spring.cloud.sentinel import (
     sentinel_engine,
     SentinelEngine,
@@ -63,6 +64,7 @@ __all__ = [
     'FeignClientProxy', 'FeignClientFactory', 'create_feign_client', 'create_declared_feign_client',
     # 分布式事务
     'seata_manager', 'init_seata', 'SeataTransactionManager', 'BranchStatus',
+    'SQLiteTransactionStore',
     # 熔断限流
     'sentinel_engine', 'SentinelEngine', 'FlowRule', 'DegradeRule',
     'SystemRule', 'HotParamRule', 'BlockException', 'sentinel_protect',

{springbootai-1.8.1 → springbootai-1.8.3}/spring/cloud/gateway.py

@@ -185,9 +185,10 @@ class GatewayRouter:
     作为异步 Starlette/FastAPI endpoint 使用。上游 I/O 不会阻塞事件循环。
 
     Usage:
-        gateway = GatewayRouter(discovery_client=nacos_discovery)
-        gateway.route("/api/users/**", "user-service", strip_prefix=True)
-        app.add_route("/api/{path:path}", gateway.handle_asgi, methods=["GET","POST","PUT","DELETE"])
+        gateway = GatewayRouter(timeout=5)
+        gateway.route("/api/users/**", uri="http://127.0.0.1:8081",
+                      strip_prefix=True)
+        gateway.install(app, "/api/{path:path}")
     """
 
     _HOP_BY_HOP_HEADERS = {
@@ -216,11 +217,27 @@ class GatewayRouter:
     def install(self, app, path: str = "/{path:path}",
                 methods: Optional[List[str]] = None) -> "GatewayRouter":
         """Register the gateway route and its HTTP-client shutdown hook."""
-        app.add_api_route(
-            path,
-            self.handle_asgi,
-            methods=methods or ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"],
-        )
+        route_methods = methods or ["GET", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
+        path_id = re.sub(r"[^a-zA-Z0-9]+", "_", path).strip("_") or "root"
+        existing_operation_ids = {
+            getattr(route, "operation_id", None) for route in app.routes
+        }
+        for method in route_methods:
+            normalized_method = method.upper()
+            base_operation_id = f"gateway_{normalized_method.lower()}_{path_id}"
+            operation_id = base_operation_id
+            suffix = 2
+            while operation_id in existing_operation_ids:
+                operation_id = f"{base_operation_id}_{suffix}"
+                suffix += 1
+            existing_operation_ids.add(operation_id)
+            app.add_api_route(
+                path,
+                self.handle_asgi,
+                methods=[normalized_method],
+                name=operation_id,
+                operation_id=operation_id,
+            )
         app.router.add_event_handler("shutdown", self.aclose)
         return self