springbootAI 1.8.2__tar.gz → 1.8.4__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: springbootAI
-Version: 1.8.2
+Version: 1.8.4
 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.2`
+- SpringBootAI 版本：`1.8.4`
 - 内嵌 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 / 负载均衡 / 分布式事务 |
@@ -112,6 +114,14 @@ SpringBootAI 是一个借鉴 Spring Boot 编程模型的 Python Web 框架，提
 
 > 所有模块文档统一存放于 [`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-框架概述与定位)
@@ -143,7 +153,7 @@ SpringBootAI 借鉴了 Spring Boot 的注解和分层习惯，但运行时是 Py
 
 | 组件 | 当前版本 |
 |------|----------|
-| `spring` 框架 API | 1.8.2 |
+| `spring` 框架 API | 1.8.4 |
 | `spring.orm.pymybatis` | 1.4.0 |
 | Python | 3.10+ |
 
@@ -1965,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
 

{springbootai-1.8.2 → springbootai-1.8.4}/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.2`
+- SpringBootAI 版本：`1.8.4`
 - 内嵌 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 / 负载均衡 / 分布式事务 |
@@ -28,6 +30,14 @@ SpringBootAI 是一个借鉴 Spring Boot 编程模型的 Python Web 框架，提
 
 > 所有模块文档统一存放于 [`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-框架概述与定位)
@@ -59,7 +69,7 @@ SpringBootAI 借鉴了 Spring Boot 的注解和分层习惯，但运行时是 Py
 
 | 组件 | 当前版本 |
 |------|----------|
-| `spring` 框架 API | 1.8.2 |
+| `spring` 框架 API | 1.8.4 |
 | `spring.orm.pymybatis` | 1.4.0 |
 | Python | 3.10+ |
 
@@ -1881,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
 

{springbootai-1.8.2 → springbootai-1.8.4}/pyproject.toml

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

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

{springbootai-1.8.2 → springbootai-1.8.4}/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.2 → springbootai-1.8.4}/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.2 → springbootai-1.8.4}/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