springbootAI 1.8.1__tar.gz → 1.8.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: springbootAI
-Version: 1.8.1
+Version: 1.8.2
 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.2`
 - 内嵌 PyMyBatis 版本：`1.4.0`
 - Python：3.10+
 - 状态：Beta（企业试点）
@@ -107,6 +107,7 @@ 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/` 下的对应文件。
@@ -142,7 +143,7 @@ SpringBootAI 借鉴了 Spring Boot 的注解和分层习惯，但运行时是 Py
 
 | 组件 | 当前版本 |
 |------|----------|
-| `spring` 框架 API | 1.8.0 |
+| `spring` 框架 API | 1.8.2 |
 | `spring.orm.pymybatis` | 1.4.0 |
 | Python | 3.10+ |
 
@@ -158,7 +159,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 +194,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 +1492,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 方法；容器声明队列/交换机、注册回调，并在刷新后启动后台消费；支持同步和异步回调 |
@@ -2018,7 +2019,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 +2229,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 +2237,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 +2323,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 +2447,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 +2531,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 +2756,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.2}/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.2`
 - 内嵌 PyMyBatis 版本：`1.4.0`
 - Python：3.10+
 - 状态：Beta（企业试点）
@@ -23,6 +23,7 @@ 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/` 下的对应文件。
@@ -58,7 +59,7 @@ SpringBootAI 借鉴了 Spring Boot 的注解和分层习惯，但运行时是 Py
 
 | 组件 | 当前版本 |
 |------|----------|
-| `spring` 框架 API | 1.8.0 |
+| `spring` 框架 API | 1.8.2 |
 | `spring.orm.pymybatis` | 1.4.0 |
 | Python | 3.10+ |
 
@@ -74,7 +75,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 +110,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 +1408,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 方法；容器声明队列/交换机、注册回调，并在刷新后启动后台消费；支持同步和异步回调 |
@@ -1934,7 +1935,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 +2145,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 +2153,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 +2239,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 +2363,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 +2447,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 +2672,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.2}/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.2"
 description = "Python版Spring Boot框架，集成PyMyBatis ORM"
 readme = "README.md"
 license = "MIT"

{springbootai-1.8.1 → springbootai-1.8.2}/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.2"
 __author__ = "yuconggen"
 __license__ = "MIT"
 

{springbootai-1.8.1 → springbootai-1.8.2}/spring/utils/__init__.py

@@ -1,5 +1,6 @@
 from .logger import SpringLogger
 from .banner import BannerPrinter
 from .redis_client import RedisClient
+from .bean_utils import BeanUtils
 
-__all__ = ["SpringLogger", "BannerPrinter", "RedisClient"]
+__all__ = ["SpringLogger", "BannerPrinter", "RedisClient", "BeanUtils"]

springbootai-1.8.2/spring/utils/bean_utils.py

@@ -0,0 +1,314 @@
+"""
+BeanUtils - 属性复制工具（对齐 Spring org.springframework.beans.BeanUtils）
+
+提供对象间属性复制、属性读写、属性描述符等功能，命名与方法语义对齐 Spring BeanUtils，
+并补充 Apache Commons BeanUtils 常用方法（getProperty/setProperty/populate/describe）。
+
+== 与 Java Spring BeanUtils 的差异 ==
+1. Python 动态类型，属性复制不做类型转换（Java 通过 PropertyEditor/ConversionService 转换）；
+   若同名属性类型不兼容，直接原样赋值，由目标对象自行决定是否接受。
+2. 基于 ``__dict__`` / ``getattr`` / ``setattr`` 实现，支持普通类、dataclass、Pydantic v2 Model、ORM entity。
+3. 默认浅拷贝（嵌套对象复制引用），需要深拷贝请用 ``copy_deep=True`` 或 ``BeanUtils.clone(source, deep=True)``。
+4. 不支持 Java 的 PropertyChangeListener / VetoableChangeListener 等监听机制。
+5. 双下划线开头（``__``）的特殊属性与方法（callable）自动排除；单下划线（``_``）约定的私有属性默认参与复制，
+   如需排除请通过 ``ignore`` 显式指定。
+
+== 方法对齐速查 ==
+- Spring BeanUtils: copy_properties / copy_property / get_property_descriptors / get_property_descriptor / clone
+- Apache Commons BeanUtils: get_property / set_property / get_simple_property / populate / describe
+"""
+from __future__ import annotations
+
+import copy as _copy_module
+from typing import Any, Dict, Iterable, Mapping, Optional
+
+
+__all__ = ["BeanUtils"]
+
+
+def _is_copyable_attr(name: str, value: Any) -> bool:
+    """判断属性是否可参与复制：排除双下划线特殊属性与可调用对象（方法）。"""
+    if name.startswith("__"):
+        return False
+    if callable(value):
+        return False
+    return True
+
+
+def _get_readable_properties(source: Any) -> Dict[str, Any]:
+    """
+    收集源对象所有可读属性（实例属性 + 类上定义的 property）。
+
+    优先取实例 ``__dict__``，再补充类层 property（dataclass/普通类均覆盖）。
+    property 的 getter 抛异常时跳过该属性，避免复制中断。
+    """
+    props: Dict[str, Any] = {}
+    source_dict = getattr(source, "__dict__", None)
+    if isinstance(source_dict, dict):
+        for name, value in source_dict.items():
+            if _is_copyable_attr(name, value):
+                props[name] = value
+
+    # 补充类层 property（不含实例 __dict__ 已收集的）
+    for klass in type(source).__mro__:
+        try:
+            klass_vars = vars(klass)
+        except TypeError:
+            continue
+        for name, attr in klass_vars.items():
+            if name in props:
+                continue
+            if name.startswith("__"):
+                # 提前跳过 dunder，避免触发 Pydantic 等内部 property 的弃用 getter
+                continue
+            if isinstance(attr, property) and attr.fget is not None:
+                try:
+                    value = attr.fget(source)
+                except Exception:
+                    continue
+                if _is_copyable_attr(name, value):
+                    props[name] = value
+    return props
+
+
+def _is_writable(target: Any, name: str) -> bool:
+    """判断目标对象是否能写入该属性：只读 property 返回 False。"""
+    for klass in type(target).__mro__:
+        try:
+            klass_vars = vars(klass)
+        except TypeError:
+            continue
+        if name in klass_vars:
+            attr = klass_vars[name]
+            if isinstance(attr, property):
+                return attr.fset is not None
+            # dataclass field / 普通类属性 -> 可写
+            return True
+    # 实例 __dict__ 可动态扩展的普通对象 -> 可写
+    return hasattr(target, "__dict__") or hasattr(target, "__slots__")
+
+
+class BeanUtils:
+    """属性复制工具类（对齐 Spring BeanUtils + Apache Commons BeanUtils）。"""
+
+    # ------------------------------------------------------------------
+    # Spring BeanUtils 对齐
+    # ------------------------------------------------------------------
+    @staticmethod
+    def copy_properties(
+        source: Any,
+        target: Any,
+        ignore: Optional[Iterable[str]] = None,
+        copy_deep: bool = False,
+    ) -> None:
+        """
+        复制源对象同名属性到目标对象（对齐 Spring ``BeanUtils.copyProperties``）。
+
+        Args:
+            source: 源对象（``None`` 时直接返回）。
+            target: 目标对象（``None`` 时直接返回）。
+            ignore: 忽略的属性名集合（对齐 Java ``ignoreProperties`` 变长参数）。
+            copy_deep: 是否对每个属性值做深拷贝。默认 False（浅拷贝，与 Spring 一致）。
+
+        规则：
+            - 仅复制源对象存在且可读的属性；目标对象不可写（如只读 property）时跳过。
+            - 双下划线属性与方法自动排除；私有属性（单下划线）默认复制。
+            - 目标对象 setattr 失败（如 Pydantic frozen / slots 限制）时跳过，不抛异常。
+        """
+        if source is None or target is None:
+            return
+        ignore_set: set = set(ignore) if ignore else set()
+        for name, value in _get_readable_properties(source).items():
+            if name in ignore_set:
+                continue
+            if not _is_writable(target, name):
+                continue
+            try:
+                setattr(target, name, _copy_module.deepcopy(value) if copy_deep else value)
+            except (AttributeError, TypeError, ValueError):
+                # 目标对象校验失败或不可写：跳过，保持 Spring 的"尽力复制"语义
+                continue
+
+    @staticmethod
+    def copy_property(source: Any, target: Any, property_name: str) -> bool:
+        """
+        复制单个属性（对齐 Spring ``BeanUtils.copyProperty``）。
+
+        Returns:
+            是否复制成功（源无此属性或目标不可写返回 False）。
+        """
+        if source is None or target is None:
+            return False
+        if not hasattr(source, property_name):
+            return False
+        try:
+            value = getattr(source, property_name)
+        except Exception:
+            return False
+        if not _is_copyable_attr(property_name, value):
+            return False
+        if not _is_writable(target, property_name):
+            return False
+        try:
+            setattr(target, property_name, value)
+            return True
+        except (AttributeError, TypeError, ValueError):
+            return False
+
+    @staticmethod
+    def clone(source: Any, deep: bool = False) -> Any:
+        """
+        克隆对象（对齐 Spring ``BeanUtils.cloneBean``，Apache Commons 风格）。
+
+        Args:
+            source: 源对象。
+            deep: True 做深拷贝；False 仅复制顶层（嵌套对象共享引用）。
+
+        Returns:
+            与源同类型的新对象，属性已复制。
+        """
+        if source is None:
+            return None
+        target = type(source).__new__(type(source))
+        BeanUtils.copy_properties(source, target, copy_deep=deep)
+        return target
+
+    @staticmethod
+    def get_property_descriptors(obj: Any) -> Dict[str, Optional[type]]:
+        """
+        获取属性描述符（对齐 Spring ``BeanUtils.getPropertyDescriptors``）。
+
+        Returns:
+            属性名 -> 属性值类型的映射（无法推断类型时为 None）。
+        """
+        descriptors: Dict[str, Optional[type]] = {}
+        for name, value in _get_readable_properties(obj).items():
+            descriptors[name] = type(value) if value is not None else None
+        return descriptors
+
+    @staticmethod
+    def get_property_descriptor(obj: Any, name: str) -> Optional[type]:
+        """获取单个属性的描述符（对齐 Spring ``BeanUtils.getPropertyDescriptor``）。"""
+        if obj is None or not hasattr(obj, name):
+            return None
+        try:
+            value = getattr(obj, name)
+        except Exception:
+            return None
+        return type(value) if value is not None else None
+
+    # ------------------------------------------------------------------
+    # Apache Commons BeanUtils 对齐
+    # ------------------------------------------------------------------
+    @staticmethod
+    def get_property(obj: Any, name: str, default: Any = None) -> Any:
+        """
+        获取属性值，支持嵌套路径（对齐 Apache Commons ``BeanUtils.getProperty``）。
+
+        Args:
+            name: 属性名，支持点号嵌套，如 ``"user.address.city"``。
+            default: 路径中断或取值异常时返回的默认值。
+
+        Returns:
+            属性值；路径中断或异常返回 ``default``。
+        """
+        if obj is None or not name:
+            return default
+        current: Any = obj
+        for part in name.split("."):
+            if current is None:
+                return default
+            if isinstance(current, Mapping) and part in current:
+                current = current[part]
+            elif hasattr(current, part):
+                try:
+                    current = getattr(current, part)
+                except Exception:
+                    return default
+            else:
+                return default
+        return current if current is not None else default
+
+    @staticmethod
+    def set_property(obj: Any, name: str, value: Any) -> bool:
+        """
+        设置属性值，支持嵌套路径（对齐 Apache Commons ``BeanUtils.setProperty``）。
+
+        Args:
+            name: 属性名，支持点号嵌套；嵌套中间节点为 None 时创建失败返回 False。
+
+        Returns:
+            是否设置成功。
+        """
+        if obj is None or not name:
+            return False
+        parts = name.split(".")
+        current: Any = obj
+        for part in parts[:-1]:
+            if current is None:
+                return False
+            if isinstance(current, Mapping):
+                if part not in current or current[part] is None:
+                    return False
+                current = current[part]
+            elif hasattr(current, part):
+                try:
+                    nxt = getattr(current, part)
+                except Exception:
+                    return False
+                if nxt is None:
+                    return False
+                current = nxt
+            else:
+                return False
+        leaf = parts[-1]
+        try:
+            if isinstance(current, Mapping):
+                current[leaf] = value
+            else:
+                setattr(current, leaf, value)
+            return True
+        except (AttributeError, TypeError, ValueError, KeyError):
+            return False
+
+    @staticmethod
+    def get_simple_property(obj: Any, name: str, default: Any = None) -> Any:
+        """获取简单属性（不支持嵌套，对齐 Apache Commons ``getSimpleProperty``）。"""
+        if obj is None or not name or not hasattr(obj, name):
+            return default
+        try:
+            value = getattr(obj, name)
+        except Exception:
+            return default
+        return value if value is not None else default
+
+    @staticmethod
+    def populate(obj: Any, properties: Mapping[str, Any]) -> None:
+        """
+        用字典批量设置属性（对齐 Apache Commons ``BeanUtils.populate``）。
+
+        Args:
+            obj: 目标对象。
+            properties: 属性名 -> 值的映射；不可写的属性自动跳过。
+        """
+        if obj is None or not properties:
+            return
+        for name, value in properties.items():
+            if not _is_writable(obj, name):
+                continue
+            try:
+                setattr(obj, name, value)
+            except (AttributeError, TypeError, ValueError):
+                continue
+
+    @staticmethod
+    def describe(obj: Any) -> Dict[str, Any]:
+        """
+        将对象可读属性导出为字典（对齐 Apache Commons ``BeanUtils.describe``）。
+
+        Returns:
+            属性名 -> 值的映射（仅可读属性，排除方法与双下划线属性）。
+        """
+        if obj is None:
+            return {}
+        return _get_readable_properties(obj)