springbootAI 1.8.7__tar.gz → 1.8.8__tar.gz

{springbootai-1.8.7/springbootAI.egg-info → springbootai-1.8.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: springbootAI
-Version: 1.8.7
+Version: 1.8.8
 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.4`
+- SpringBootAI 版本：`1.8.8`
 - 内嵌 PyMyBatis 版本：`1.4.0`
 - Python：3.10+
 - 状态：Beta（企业试点）
@@ -153,7 +153,7 @@ SpringBootAI 借鉴了 Spring Boot 的注解和分层习惯，但运行时是 Py
 
 | 组件 | 当前版本 |
 |------|----------|
-| `spring` 框架 API | 1.8.4 |
+| `spring` 框架 API | 1.8.8 |
 | `spring.orm.pymybatis` | 1.4.0 |
 | Python | 3.10+ |
 
@@ -442,7 +442,7 @@ CORS_ALLOW_ORIGINS      CORS_ALLOW_CREDENTIALS
 LOG_LEVEL               LOG_DIR
 ```
 
-当前 `SPRING_PROFILES_ACTIVE` 用于 `@Profile` 组件筛选和生产安全校验，不会自动合并 `application-prod.yml`。需要多环境文件时，由部署流程生成最终 `application.yml` 或显式传入配置路径。
+`SPRING_PROFILES_ACTIVE` 用于 `@Profile` 组件筛选、生产安全校验，以及**自动加载并深度合并** `application-{profile}.yml`（v1.8.5 起实现，对齐 Spring Boot 语义）。Profile 文件与主 `application.yml` 同目录，加载顺序为：主配置 → profile 配置深度合并（profile 覆盖主配置的同名键，未涉及的键保留），合并后再解析 `${ENV:default}` 占位符和环境变量覆盖。例如 `SPRING_PROFILES_ACTIVE=prod` 会自动合并 `application-prod.yml`，无需部署流程生成最终 `application.yml`。
 
 ### 4.4 Docker 容器 IP 自动检测（开发环境）
 

{springbootai-1.8.7 → springbootai-1.8.8}/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.4`
+- SpringBootAI 版本：`1.8.8`
 - 内嵌 PyMyBatis 版本：`1.4.0`
 - Python：3.10+
 - 状态：Beta（企业试点）
@@ -69,7 +69,7 @@ SpringBootAI 借鉴了 Spring Boot 的注解和分层习惯，但运行时是 Py
 
 | 组件 | 当前版本 |
 |------|----------|
-| `spring` 框架 API | 1.8.4 |
+| `spring` 框架 API | 1.8.8 |
 | `spring.orm.pymybatis` | 1.4.0 |
 | Python | 3.10+ |
 
@@ -358,7 +358,7 @@ CORS_ALLOW_ORIGINS      CORS_ALLOW_CREDENTIALS
 LOG_LEVEL               LOG_DIR
 ```
 
-当前 `SPRING_PROFILES_ACTIVE` 用于 `@Profile` 组件筛选和生产安全校验，不会自动合并 `application-prod.yml`。需要多环境文件时，由部署流程生成最终 `application.yml` 或显式传入配置路径。
+`SPRING_PROFILES_ACTIVE` 用于 `@Profile` 组件筛选、生产安全校验，以及**自动加载并深度合并** `application-{profile}.yml`（v1.8.5 起实现，对齐 Spring Boot 语义）。Profile 文件与主 `application.yml` 同目录，加载顺序为：主配置 → profile 配置深度合并（profile 覆盖主配置的同名键，未涉及的键保留），合并后再解析 `${ENV:default}` 占位符和环境变量覆盖。例如 `SPRING_PROFILES_ACTIVE=prod` 会自动合并 `application-prod.yml`，无需部署流程生成最终 `application.yml`。
 
 ### 4.4 Docker 容器 IP 自动检测（开发环境）
 

{springbootai-1.8.7 → springbootai-1.8.8}/pyproject.toml

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

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

{springbootai-1.8.7 → springbootai-1.8.8}/spring/ai/autoconfig.py

@@ -60,10 +60,24 @@ from spring.context.registry import BeanRegistry
 
 logger = logging.getLogger("Spring.AI")
 
-# 生产环境安全开关：AI_ALLOW_FAKE=true（默认）时，api_key 缺失降级 FakeChatModel；
-# 设为 false 时，api_key 缺失直接抛 ConfigurationError，防止生产配错无声返回假数据。
-_AI_ALLOW_FAKE = os.environ.get("AI_ALLOW_FAKE", "true").strip().lower() in (
-    "true", "1", "yes", "on")
+
+def _ai_allow_fake() -> bool:
+    """读取 ``AI_ALLOW_FAKE`` 环境变量，决定 api_key 缺失时是否降级 ``FakeChatModel``。
+
+    安全默认：``false``。开发/测试环境需**显式**设置 ``AI_ALLOW_FAKE=true``
+    才允许降级，防止生产环境配错时无声返回测试数据。
+
+    设计要点：
+    - 每次调用实时读取环境变量（非模块导入时一次性读取），便于 ``config_loader``
+      在生产 profile 下运行时强制 ``AI_ALLOW_FAKE=false``，避免导入时序导致的绕过。
+    - 接受 ``true/1/yes/on``（大小写不敏感）为 True，其余为 False，与框架
+      ``_to_bool`` 规则一致。
+    - 生产环境由 ``config_loader._validate_config`` 双重加固：
+      (1) 强制 ``AI_ALLOW_FAKE=false``；
+      (2) 校验默认 provider 的 api-key 已配置，缺失直接抛 ``ConfigurationError``。
+    """
+    return os.environ.get("AI_ALLOW_FAKE", "false").strip().lower() in (
+        "true", "1", "yes", "on")
 
 
 # ==================== 类型化配置 dataclass ====================
@@ -258,7 +272,7 @@ def _build_chat_model(props: AIProperties, redis_client=None) -> ChatModel:
 
     if provider == "openai":
         if not props.openai.api_key:
-            if not _AI_ALLOW_FAKE:
+            if not _ai_allow_fake():
                 raise ValueError(
                     "AI_ALLOW_FAKE=false 但 spring.ai.openai.api-key 未配置。"
                     " 请设置 OPENAI_API_KEY 环境变量或 application.yml 的 api-key。")
@@ -295,7 +309,7 @@ def _build_chat_model(props: AIProperties, redis_client=None) -> ChatModel:
     if provider in _COMPAT_SPECS:
         pname, lc_mod, lc_cls, cfg = _COMPAT_SPECS[provider]
         if not cfg.api_key:
-            if not _AI_ALLOW_FAKE:
+            if not _ai_allow_fake():
                 raise ValueError(
                     f"AI_ALLOW_FAKE=false 但 spring.ai.{provider}.api-key 未配置。"
                     f" 请设置 {provider.upper()}_API_KEY 环境变量。")
@@ -309,7 +323,7 @@ def _build_chat_model(props: AIProperties, redis_client=None) -> ChatModel:
         )
 
     logger.warning("未知 AI provider: %s", provider)
-    if not _AI_ALLOW_FAKE:
+    if not _ai_allow_fake():
         raise ValueError(
             f"AI_ALLOW_FAKE=false 但未知 provider: {provider}。"
             " 请检查 application.yml 的 spring.ai.default-provider 配置。")
@@ -323,7 +337,7 @@ def _build_embedding_model(props: AIProperties, redis_client=None):
 
     if provider == "openai":
         if not props.openai.api_key:
-            if not _AI_ALLOW_FAKE:
+            if not _ai_allow_fake():
                 raise ValueError(
                     "AI_ALLOW_FAKE=false 但 Embedding 未配置 api-key。"
                     " 请设置 OPENAI_API_KEY 环境变量。")
@@ -351,7 +365,7 @@ def _build_embedding_model(props: AIProperties, redis_client=None):
     if provider in ("deepseek", "moonshot", "zhipu"):
         cfg = getattr(props, provider)
         if not cfg.api_key:
-            if not _AI_ALLOW_FAKE:
+            if not _ai_allow_fake():
                 raise ValueError(
                     f"AI_ALLOW_FAKE=false 但 Embedding 未配置 {provider} api-key。")
             logger.warning("Embedding 未配置 %s api-key，降级 FakeEmbeddingModel",
@@ -364,7 +378,7 @@ def _build_embedding_model(props: AIProperties, redis_client=None):
             circuit_breaker=cb,
         )
 
-    if not _AI_ALLOW_FAKE:
+    if not _ai_allow_fake():
         raise ValueError(
             "AI_ALLOW_FAKE=false 但未知 Embedding provider。"
             " 请检查 application.yml 的 spring.ai.default-provider 配置。")

{springbootai-1.8.7 → springbootai-1.8.8}/spring/annotations/cloud.py

@@ -178,16 +178,18 @@ class LoadBalanced(SpringAnnotation):
 
 class GlobalTransactional(SpringAnnotation):
     """
-    Seata分布式事务注解
-    仅事务发起入口方法添加，所有参与分布式事务的微服务不需要添加该注解
+    Seata 分布式事务注解。
+
+    仅事务发起入口方法添加。distributed 模式使用官方 Java 客户端桥接和
+    Seata TCC；参与服务通过 ``register_branch`` 注册业务分支。
     
     使用注意：
-    - 数据库必须使用InnoDB引擎，支持行锁
-    - 业务表必须存在主键
-    - 必须配置Seata注册中心、事务组
+    - 必须配置 Seata Server、bridge、共享令牌和事务组
+    - TCC 分支必须实现持久化资源预留和幂等的 prepare/commit/rollback
+    - 回调要处理重复提交、空回滚和悬挂，不能只修改进程内变量
     - 不支持嵌套事务
-    - 只有RuntimeException才会触发全局回滚
-    - 禁止在异步线程中使用，事务上下文无法传递
+    - 业务方法抛出异常时会触发全局回滚
+    - 不要把 ContextVar 事务上下文直接复制到独立后台任务中继续使用
     """
     _annotation_type = "aop"
 

{springbootai-1.8.7 → springbootai-1.8.8}/spring/aop/cloud_aop.py

@@ -140,16 +140,27 @@ def global_transactional_decorator(annotation: GlobalTransactional):
                 if seata_manager.is_in_transaction():
                     logger.warning("[GlobalTransactional] Nested transaction detected, skipping")
                     return await func(*args, **kwargs)
-                if seata_manager.get_mode() == "http":
+                mode = seata_manager.get_mode()
+                if mode in {"http", "distributed"}:
                     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}"
+                    if mode == "http":
+                        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}"
+                            )
+                    else:
+                        transaction_context = {
+                            'in_transaction': True,
+                            'tx_id': tx_id,
+                            'status': 'Begin',
+                            'timeout': annotation.timeout,
+                            'start_time': time.time(),
+                            'name': annotation.name or func.__name__,
+                        }
                     seata_manager.bind_transaction_context(transaction_context)
                 else:
                     tx_id = begin_transaction()

{springbootai-1.8.7 → springbootai-1.8.8}/spring/cloud/__init__.py

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

{springbootai-1.8.7 → springbootai-1.8.8}/spring/cloud/gateway.py

@@ -198,6 +198,7 @@ class GatewayRouter:
 
     def __init__(self, discovery_client=None, default_filters: List[GatewayFilter] = None,
                  timeout: float = 10.0, max_body_size: int = 10 * 1024 * 1024,
+                 max_response_size: int = 50 * 1024 * 1024,
                  transport: Optional[httpx.AsyncBaseTransport] = None):
         self.discovery = discovery_client
         self.routes: List[Route] = []
@@ -210,6 +211,9 @@ class GatewayRouter:
         self._path_pattern_cache: Dict[str, re.Pattern] = {}
         self.timeout = float(timeout)
         self.max_body_size = int(max_body_size)
+        # 上游响应大小上限（字节）：防止大文件下载/并发请求整体载入内存耗尽 worker。
+        # 旧版本直接 upstream.content 整体载入，无大小限制。0 表示禁用限制（不推荐）。
+        self.max_response_size = int(max_response_size)
         self._transport = transport
         self._client: Optional[httpx.AsyncClient] = None
         self._client_lock = threading.Lock()
@@ -410,33 +414,102 @@ class GatewayRouter:
         }
         try:
             target_url = target_uri + forward_path
-            upstream = await self._get_client().request(
+            # 使用 stream=True 避免上游响应整体载入内存：
+            # 旧版本 upstream.content 一次性载入全部响应体，大文件下载或并发请求
+            # 可能耗尽 worker 内存。流式读取配合 max_response_size 可在超限时提前中止。
+            req = self._get_client().build_request(
                 method,
                 target_url,
                 params=query_items,
                 headers=request_headers,
                 content=body,
             )
+            upstream = await self._get_client().send(req, stream=True)
 
-            ctx.response_status = upstream.status_code
-            response_headers = {
-                key: value for key, value in upstream.headers.items()
-                if key.lower() not in self._HOP_BY_HOP_HEADERS | {'content-length'}
-            }
-            ctx.response_headers.update(response_headers)
-
-            # 执行后置过滤器
-            for flt in self.filters:
-                try:
-                    await self._run_filter(flt, 'post_filter', ctx)
-                except Exception:
-                    logger.exception("[Gateway] post filter failed")
-
-            return Response(
-                content=upstream.content,
-                status_code=upstream.status_code,
-                headers=ctx.response_headers,
-            )
+            try:
+                ctx.response_status = upstream.status_code
+                response_headers = {
+                    key: value for key, value in upstream.headers.items()
+                    if key.lower() not in self._HOP_BY_HOP_HEADERS | {'content-length'}
+                }
+                ctx.response_headers.update(response_headers)
+
+                # 执行后置过滤器
+                for flt in self.filters:
+                    try:
+                        await self._run_filter(flt, 'post_filter', ctx)
+                    except Exception:
+                        logger.exception("[Gateway] post filter failed")
+
+                # 响应大小限制：
+                # (1) 先检查 Content-Length 头（快速路径，无需读取响应体即可拒绝）
+                # (2) 流式读取时累计字节数，超限立即中止并返回 502
+                if self.max_response_size > 0:
+                    content_length = upstream.headers.get('content-length')
+                    if content_length:
+                        try:
+                            if int(content_length) > self.max_response_size:
+                                logger.warning(
+                                    "[Gateway] Upstream response Content-Length %s exceeds limit %d",
+                                    content_length, self.max_response_size,
+                                )
+                                return JSONResponse(
+                                    {"error": "Upstream response too large",
+                                     "limit_bytes": self.max_response_size},
+                                    status_code=502,
+                                )
+                        except ValueError:
+                            pass
+
+                    # is_stream_consumed=True 表示响应体已预载（如 MockTransport 或
+                    # 非 stream 模式）；此时 aiter_raw() 会抛 StreamConsumed，
+                    # 直接用 .content 检查大小即可。
+                    if upstream.is_stream_consumed:
+                        response_body = upstream.content
+                        if len(response_body) > self.max_response_size:
+                            logger.warning(
+                                "[Gateway] Upstream response %d bytes exceeds limit %d",
+                                len(response_body), self.max_response_size,
+                            )
+                            return JSONResponse(
+                                {"error": "Upstream response too large",
+                                 "limit_bytes": self.max_response_size},
+                                status_code=502,
+                            )
+                    else:
+                        chunks = []
+                        response_size = 0
+                        too_large = False
+                        async for chunk in upstream.aiter_raw():
+                            response_size += len(chunk)
+                            if response_size > self.max_response_size:
+                                logger.warning(
+                                    "[Gateway] Upstream response exceeded %d bytes (got %d+), aborting",
+                                    self.max_response_size, response_size,
+                                )
+                                too_large = True
+                                break
+                            chunks.append(chunk)
+
+                        if too_large:
+                            return JSONResponse(
+                                {"error": "Upstream response too large",
+                                 "limit_bytes": self.max_response_size},
+                                status_code=502,
+                            )
+                        response_body = b''.join(chunks)
+                else:
+                    # 无限制：直接读取完整响应（向后兼容，不推荐在生产使用）
+                    response_body = await upstream.aread()
+
+                return Response(
+                    content=response_body,
+                    status_code=upstream.status_code,
+                    headers=ctx.response_headers,
+                )
+            finally:
+                # stream=True 模式下必须显式关闭响应，否则连接不会归还连接池
+                await upstream.aclose()
         except httpx.TimeoutException as exc:
             logger.warning(f"[Gateway] Upstream timeout: {exc}")
             return JSONResponse({"error": "Gateway timeout"}, status_code=504)