springbootAI 1.8.0__py3-none-any.whl

spring/annotations/__init__.py

@@ -0,0 +1,188 @@
+from .core import (
+    SpringBootApplication,
+    ComponentScan,
+    ApplicationEvent,
+    EventListener,
+    RestController,
+    Controller,
+    RequestMapping,
+    GetMapping,
+    PostMapping,
+    PutMapping,
+    PatchMapping,
+    DeleteMapping,
+    Service,
+    Component,
+    Repository,
+    Autowired,
+    Qualifier,
+    Configuration,
+    Scope,
+    Bean,
+    Value,
+    ConfigurationProperties,
+    RequestParam,
+    PathVariable,
+    RequestBody,
+    Valid,
+    Validated,
+    CrossOrigin,
+    ControllerAdvice,
+    ExceptionHandler,
+    Slf4j,
+    LogExecutionTime,
+    PostConstruct,
+    PreDestroy,
+    Primary,
+    Profile,
+    Lazy,
+    RequestHeader,
+    CookieValue,
+    ResponseStatus,
+    Transactional,
+    Cacheable,
+    Retryable,
+    Async,
+    Scheduled,
+    AsyncResult,
+    RateLimit,
+    CircuitBreaker,
+    Idempotent,
+    AuditLog,
+    FeatureToggle,
+    Lock,
+    Metrics,
+    Synchronized,
+    Validate,
+    Trace,
+    PreAuthorize,
+    Secured,
+    Authenticate,
+)
+
+from .cloud import (
+    EnableDiscoveryClient,
+    NacosValue,
+    RefreshScope,
+    EnableFeignClients,
+    FeignClient,
+    SentinelResource,
+    EnableGateway,
+    LoadBalanced,
+    GlobalTransactional,
+)
+
+# 缓存增强注解（@CachePut / @CacheEvict / @CacheConfig / @Caching），对齐 Spring Cache
+from .cache import (
+    CachePut,
+    CacheEvict,
+    CacheConfig,
+    Caching,
+)
+
+# 条件装配注解（@Conditional / @ConditionalOnProperty / ...），对齐 Spring Boot
+from .conditional import (
+    Conditional,
+    ConditionalOnProperty,
+    ConditionalOnBean,
+    ConditionalOnMissingBean,
+    ConditionalOnClass,
+)
+
+# 可选导入：消息队列注解（需要pika）
+try:
+    from .messaging import (
+        RabbitListener,
+        RabbitTemplate,
+    )
+except ImportError:
+    # pika未安装，这些注解不可用
+    RabbitListener = None
+    RabbitTemplate = None
+
+__all__ = [
+    "SpringBootApplication",
+    "ComponentScan",
+    "ApplicationEvent",
+    "EventListener",
+    "RestController",
+    "Controller",
+    "RequestMapping",
+    "GetMapping",
+    "PostMapping",
+    "PutMapping",
+    "PatchMapping",
+    "DeleteMapping",
+    "Service",
+    "Component",
+    "Repository",
+    "Autowired",
+    "Qualifier",
+    "Configuration",
+    "Scope",
+    "Bean",
+    "Value",
+    "ConfigurationProperties",
+    "RequestParam",
+    "PathVariable",
+    "RequestBody",
+    "CrossOrigin",
+    "ControllerAdvice",
+    "ExceptionHandler",
+    "Slf4j",
+    "LogExecutionTime",
+    "PostConstruct",
+    "PreDestroy",
+    "Primary",
+    "Profile",
+    "Lazy",
+    "RequestHeader",
+    "CookieValue",
+    "ResponseStatus",
+    "Transactional",
+    "Cacheable",
+    "Retryable",
+    "Async",
+    "Scheduled",
+    "AsyncResult",
+    "RateLimit",
+    "CircuitBreaker",
+    "Idempotent",
+    "AuditLog",
+    "FeatureToggle",
+    "Lock",
+    "Metrics",
+    "Synchronized",
+    "Validate",
+    "Trace",
+    # 安全注解
+    "PreAuthorize",
+    "Secured",
+    "Authenticate",
+    # Spring Cloud 注解
+    "EnableDiscoveryClient",
+    "NacosValue",
+    "RefreshScope",
+    "EnableFeignClients",
+    "FeignClient",
+    "SentinelResource",
+    "EnableGateway",
+    "LoadBalanced",
+    "GlobalTransactional",
+    "Valid",
+    "Validated",
+    # 缓存增强注解
+    "CachePut",
+    "CacheEvict",
+    "CacheConfig",
+    "Caching",
+    # 条件装配注解
+    "Conditional",
+    "ConditionalOnProperty",
+    "ConditionalOnBean",
+    "ConditionalOnMissingBean",
+    "ConditionalOnClass",
+    # 消息队列注解
+    "RabbitListener",
+    "RabbitTemplate",
+]

spring/annotations/cache.py

@@ -0,0 +1,126 @@
+"""SpringBootAI 缓存增强注解 —— 对齐 Spring Cache 抽象的完整操作族。
+
+本模块在既有 ``@Cacheable``（``spring.annotations.core.Cacheable``）基础上补齐 Spring Cache
+剩余四个核心注解，复用同一 ``SpringAnnotation`` 元数据范式：
+
+- ``@CachePut``：方法**总是执行**，把返回值写入缓存（更新缓存）。
+- ``@CacheEvict``：方法执行后（或前）失效缓存（按 key 或 all_entries）。
+- ``@CacheConfig``：类级注解，为类内方法提供默认 cache name / key 生成器。
+- ``@Caching``：组合多个缓存操作（cacheable/put/evict）。
+
+与 Spring 的一致点：
+- 操作语义（put/evict/condition/all_entries/before_invocation）对齐 Spring Cache。
+- ``@CacheConfig`` 作为类级默认值，方法注解显式指定时覆盖。
+
+与 Spring 的差异（已标注）：
+- Spring 的 ``@CacheConfig``/``@Caching`` 依赖 ``CacheManager`` + ``KeyGenerator`` 抽象；
+  本框架复用 ``BeanFactory`` 内置的进程内缓存（``_cache`` / ``_cache_metadata``，与
+  ``@Cacheable`` 同一存储），由 ``bean_factory._apply_aop_proxy`` 统一包装切面。
+- ``condition`` 仅支持参数名（或 ``!参数名`` 取反）与 callable，不支持 SpEL 表达式
+  （与既有 ``@Cacheable.condition`` 保持一致，避免引入 SpEL 引擎）。
+"""
+from __future__ import annotations
+
+from typing import Any, List, Optional, Tuple, Type, Union
+
+from spring.annotations.core import SpringAnnotation
+
+
+class CachePut(SpringAnnotation):
+    """``@CachePut``：方法总是执行，把返回值写入缓存（对齐 Spring ``@CachePut``）。
+
+    与 ``@Cacheable`` 的区别：``@Cacheable`` 命中缓存时跳过方法；``@CachePut`` **总是**
+    执行方法并把结果写入缓存（用于强制刷新缓存）。
+
+    Args:
+        value:      缓存名（命名空间）。为空时回退到类级 ``@CacheConfig`` 默认。
+        key:        缓存 key。支持 ``{param}`` 模板或纯参数名；为空时按全部参数聚合。
+        condition:  条件表达式。仅当为真时才写入。支持参数名/``!参数名``/callable。
+    """
+
+    _annotation_type = "aop"
+
+    def __init__(
+        self,
+        value: str = "",
+        key: Optional[str] = None,
+        condition: Optional[Union[str, Any]] = None,
+    ):
+        super().__init__(value=value, key=key, condition=condition)
+
+
+class CacheEvict(SpringAnnotation):
+    """``@CacheEvict``：失效缓存（对齐 Spring ``@CacheEvict``）。
+
+    Args:
+        value:             缓存名（命名空间）。为空时回退到类级 ``@CacheConfig`` 默认。
+        key:               缓存 key。支持 ``{param}`` 模板或纯参数名；为空且
+                           ``all_entries=False`` 时按全部参数聚合。
+        condition:         条件表达式。仅当为真时才失效。
+        all_entries:       是否清空整个缓存命名空间（所有 ``value:*`` 条目）。默认 False。
+        before_invocation: 是否在方法**调用前**失效（默认 False=调用成功后失效）。
+                           调用前失效无论方法成功与否都执行；调用后失效仅在方法成功时执行。
+    """
+
+    _annotation_type = "aop"
+
+    def __init__(
+        self,
+        value: str = "",
+        key: Optional[str] = None,
+        condition: Optional[Union[str, Any]] = None,
+        all_entries: bool = False,
+        before_invocation: bool = False,
+    ):
+        super().__init__(
+            value=value, key=key, condition=condition,
+            all_entries=all_entries, before_invocation=before_invocation,
+        )
+
+
+class CacheConfig(SpringAnnotation):
+    """``@CacheConfig``：类级缓存配置，为类内方法提供默认值（对齐 Spring ``@CacheConfig``）。
+
+    Args:
+        cache_names:    默认缓存名列表（方法注解未指定 ``value`` 时取第一个）。
+        key_generator:  key 生成器名（保留字段，当前未实现自定义生成器，仅元数据）。
+    """
+
+    _annotation_type = "aop"
+
+    def __init__(
+        self,
+        cache_names: Optional[List[str]] = None,
+        key_generator: Optional[str] = None,
+    ):
+        super().__init__(
+            cache_names=list(cache_names) if cache_names else [],
+            key_generator=key_generator,
+        )
+
+
+class Caching(SpringAnnotation):
+    """``@Caching``：组合多个缓存操作（对齐 Spring ``@Caching``）。
+
+    Args:
+        cacheable: 组合的 ``@Cacheable`` 操作列表。
+        put:       组合的 ``@CachePut`` 操作列表。
+        evict:     组合的 ``@CacheEvict`` 操作列表。
+    """
+
+    _annotation_type = "aop"
+
+    def __init__(
+        self,
+        cacheable: Optional[List[Any]] = None,
+        put: Optional[List[Any]] = None,
+        evict: Optional[List[Any]] = None,
+    ):
+        super().__init__(
+            cacheable=list(cacheable) if cacheable else [],
+            put=list(put) if put else [],
+            evict=list(evict) if evict else [],
+        )
+
+
+__all__ = ["CachePut", "CacheEvict", "CacheConfig", "Caching"]

spring/annotations/cloud.py

@@ -0,0 +1,207 @@
+"""
+Spring Cloud 微服务注解
+包含注册发现、配置中心、Feign、熔断限流、网关、负载均衡、分布式事务等注解
+"""
+from typing import Optional, Union, Dict, Any, Type, List, Callable
+from .core import SpringAnnotation, Valid, Validated
+
+
+# ==================== 注册发现注解 ====================
+
+class EnableDiscoveryClient(SpringAnnotation):
+    """
+    启用服务注册发现
+    所有微服务（服务提供者、消费者、网关）都要加
+    通用兼容：SpringCloud新版本统一使用该注解，不要混用@EnableEurekaClient
+    
+    使用注意：
+    - 必须在application.yml配置spring.application.name，否则注册中心显示未知服务
+    - Feign调用依赖服务名配置
+    """
+    _annotation_type = "discovery"
+
+    def __init__(self, client_type: str = "nacos"):
+        super().__init__(client_type=client_type)
+
+
+class NacosValue(SpringAnnotation):
+    """
+    Nacos配置动态刷新注解
+    和@Value区别：@Value配置变更不会自动刷新，@NacosValue(autoRefreshed=True)才支持动态刷新
+    
+    使用注意：
+    - 基础类型生效，复杂实体类不推荐
+    - 批量配置绑定优先使用@ConfigurationProperties
+    """
+    _annotation_type = "value"
+
+    def __init__(self, value: str, auto_refreshed: bool = False):
+        super().__init__(value=value, auto_refreshed=auto_refreshed)
+
+
+# ==================== 配置中心注解 ====================
+
+class RefreshScope(SpringAnnotation):
+    """
+    配置刷新作用域注解
+    仅加了该注解的类，配置变更才会自动刷新
+    
+    使用注意：
+    - 不能标注在@Controller上，会导致接口上下文丢失、请求参数解析异常
+    - 动态配置读取放在Service层
+    - 会创建代理类，存在循环依赖的Bean会启动直接报错
+    """
+    _annotation_type = "refresh_scope"
+
+    def __init__(self):
+        super().__init__()
+
+
+# ==================== Feign远程调用注解 ====================
+
+class EnableFeignClients(SpringAnnotation):
+    """
+    启用Feign客户端扫描
+    默认只扫描启动类同包下的Feign接口
+    
+    使用注意：
+    - Feign接口放在其他包时，必须指定扫描路径
+    - 不能和Dubbo注解混用，会出现RPC上下文冲突
+    """
+    _annotation_type = "feign"
+
+    def __init__(self, base_packages: Optional[List[str]] = None):
+        super().__init__(base_packages=base_packages)
+
+
+class FeignClient(SpringAnnotation):
+    """
+    Feign客户端注解
+    value值必须和目标服务spring.application.name完全一致，大小写敏感
+    
+    使用注意：
+    - fallback降级类必须实现当前Feign接口，且交给Spring管理
+    - 如果目标服务配置server.servlet.context-path，必须通过path属性指定
+    - 禁止在Feign接口方法上使用@Valid做参数校验
+    """
+    _annotation_type = "feign"
+
+    def __init__(
+        self,
+        value: str,
+        path: str = "",
+        fallback: Optional[Type] = None,
+        fallback_factory: Optional[Type] = None,
+        url: str = "",
+    ):
+        super().__init__(
+            value=value,
+            path=path,
+            fallback=fallback,
+            fallback_factory=fallback_factory,
+            url=url,
+        )
+
+
+# ==================== 熔断限流注解 ====================
+
+class SentinelResource(SpringAnnotation):
+    """
+    Sentinel资源保护注解（Alibaba Sentinel，生产推荐）
+    value资源名唯一，建议和接口路径保持一致
+    
+    使用注意：
+    - blockHandler：只处理限流、黑名单、系统保护这类Sentinel阻断异常
+    - fallback：处理业务异常、远程调用异常，二者分工不同
+    - 限流/降级处理函数：返回值、参数列表必须和原接口完全一致
+    - 热点参数限流：需要指定hotkey="参数名"，基础类型参数才生效
+    """
+    _annotation_type = "aop"
+
+    def __init__(
+        self,
+        value: str,
+        block_handler: str = "",
+        fallback: str = "",
+        block_handler_class: Optional[Type] = None,
+        fallback_class: Optional[Type] = None,
+        hotkey: str = "",
+        exceptions_to_ignore: Optional[List[Type[Exception]]] = None,
+    ):
+        super().__init__(
+            value=value,
+            block_handler=block_handler,
+            fallback=fallback,
+            block_handler_class=block_handler_class,
+            fallback_class=fallback_class,
+            hotkey=hotkey,
+            exceptions_to_ignore=exceptions_to_ignore or [],
+        )
+
+
+# ==================== 网关注解 ====================
+
+class EnableGateway(SpringAnnotation):
+    """
+    启用Gateway网关
+    仅网关模块启动类添加，业务服务禁止引入Gateway依赖和该注解
+    
+    使用注意：
+    - 会引入WebFlux依赖，和SpringMVC冲突
+    - 不能使用SpringMVC的拦截器，自定义逻辑必须使用Gateway全局过滤器GlobalFilter
+    """
+    _annotation_type = "gateway"
+
+    def __init__(self):
+        super().__init__()
+
+
+# ==================== 负载均衡注解 ====================
+
+class LoadBalanced(SpringAnnotation):
+    """
+    负载均衡注解
+    仅作用于@Bean修饰的RestTemplate
+    
+    使用注意：
+    - 不能标注在注入字段、类上，仅能放在创建RestTemplate的Bean方法上
+    - WebClient负载均衡需单独配置，该注解不生效
+    """
+    _annotation_type = "bean"
+
+    def __init__(self, strategy: str = "round_robin"):
+        super().__init__()
+        self.strategy = strategy
+
+
+# ==================== 分布式事务注解 ====================
+
+class GlobalTransactional(SpringAnnotation):
+    """
+    Seata分布式事务注解
+    仅事务发起入口方法添加，所有参与分布式事务的微服务不需要添加该注解
+    
+    使用注意：
+    - 数据库必须使用InnoDB引擎，支持行锁
+    - 业务表必须存在主键
+    - 必须配置Seata注册中心、事务组
+    - 不支持嵌套事务
+    - 只有RuntimeException才会触发全局回滚
+    - 禁止在异步线程中使用，事务上下文无法传递
+    """
+    _annotation_type = "aop"
+
+    def __init__(
+        self,
+        timeout: int = 60000,
+        name: str = "",
+        rollback_for: Optional[List[Type[Exception]]] = None,
+        no_rollback_for: Optional[List[Type[Exception]]] = None,
+    ):
+        super().__init__(
+            timeout=timeout,
+            name=name,
+            rollback_for=rollback_for or [],
+            no_rollback_for=no_rollback_for or [],
+        )
+