springbootAI 1.8.0__py3-none-any.whl

spring/cloud/tracer.py

@@ -0,0 +1,337 @@
+"""
+原生 OpenTelemetry 兼容分布式追踪 (Native OpenTelemetry-compatible Tracer)
+
+实现 W3C Trace Context 标准的分布式追踪，无需外部 SkyWalking agent：
+- 生成/传播 traceId, spanId (W3C traceparent header)
+- 支持 HTTP 自动注入/提取
+- 支持 Feign 跨服务调用追踪
+- 支持方法级 @Trace 注解
+- 支持导出到日志/控制台，兼容 Zipkin/Jaeger OTLP 格式（可选）
+"""
+
+import time
+import uuid
+import random
+import threading
+import logging
+import functools
+from typing import Dict, List, Optional, Any, Callable
+from contextvars import ContextVar
+from enum import Enum
+
+logger = logging.getLogger("Spring.Cloud.Tracer")
+
+
+class SpanKind(Enum):
+    INTERNAL = "INTERNAL"
+    SERVER = "SERVER"
+    CLIENT = "CLIENT"
+    PRODUCER = "PRODUCER"
+    CONSUMER = "CONSUMER"
+
+
+class SpanStatus(Enum):
+    OK = "OK"
+    ERROR = "ERROR"
+    UNSET = "UNSET"
+
+
+class Span:
+    """追踪 Span"""
+    __slots__ = (
+        'trace_id', 'span_id', 'parent_span_id', 'name', 'kind',
+        'start_time_ns', 'end_time_ns', 'attributes', 'events',
+        'status', 'status_description', 'service_name', '_ended'
+    )
+
+    def __init__(self, trace_id: str, span_id: str, parent_span_id: Optional[str],
+                 name: str, kind: SpanKind, service_name: str = "unknown"):
+        self.trace_id = trace_id
+        self.span_id = span_id
+        self.parent_span_id = parent_span_id
+        self.name = name
+        self.kind = kind
+        self.start_time_ns = time.time_ns()
+        self.end_time_ns = 0
+        self.attributes: Dict[str, Any] = {}
+        self.events: List[Dict[str, Any]] = []
+        self.status = SpanStatus.UNSET
+        self.status_description = ""
+        self.service_name = service_name
+        self._ended = False
+
+    def set_attribute(self, key: str, value: Any):
+        self.attributes[key] = value
+        return self
+
+    def set_status(self, status: SpanStatus, description: str = ""):
+        self.status = status
+        self.status_description = description
+        return self
+
+    def add_event(self, name: str, attributes: Dict[str, Any] = None):
+        self.events.append({
+            'name': name,
+            'timestamp_ns': time.time_ns(),
+            'attributes': attributes or {},
+        })
+        return self
+
+    def record_exception(self, exception: Exception):
+        self.add_event("exception", {
+            'exception.type': type(exception).__name__,
+            'exception.message': str(exception),
+        })
+        self.set_status(SpanStatus.ERROR, str(exception))
+        return self
+
+    def end(self):
+        if not self._ended:
+            self.end_time_ns = time.time_ns()
+            if self.status == SpanStatus.UNSET:
+                self.status = SpanStatus.OK
+            self._ended = True
+
+    @property
+    def duration_ms(self) -> float:
+        end = self.end_time_ns or time.time_ns()
+        return (end - self.start_time_ns) / 1_000_000
+
+    def to_dict(self) -> dict:
+        return {
+            'traceId': self.trace_id,
+            'id': self.span_id,
+            'parentId': self.parent_span_id or '',
+            'name': self.name,
+            'kind': self.kind.value,
+            'timestamp': self.start_time_ns // 1000,  # microseconds for OTLP
+            'duration': (self.end_time_ns - self.start_time_ns) // 1000 if self.end_time_ns else 0,
+            'localEndpoint': {'serviceName': self.service_name},
+            'tags': self.attributes,
+            'annotations': [{'timestamp': e['timestamp_ns'] // 1000, 'value': e['name']} for e in self.events],
+            'tags': {**self.attributes, **{
+                'otel.status_code': self.status.value,
+                'error': self.status_description if self.status == SpanStatus.ERROR else '',
+            }},
+        }
+
+
+def _generate_trace_id() -> str:
+    """生成 W3C 兼容 32-hex traceId"""
+    return uuid.uuid4().hex
+
+
+def _generate_span_id() -> str:
+    """生成 16-hex spanId"""
+    return '%016x' % random.getrandbits(64)
+
+
+def _parse_traceparent(header: str) -> Optional[tuple]:
+    """解析 W3C traceparent header: 00-traceid-spanid-flags"""
+    try:
+        parts = header.strip().split('-')
+        if len(parts) >= 4:
+            version = parts[0]
+            trace_id = parts[1]
+            span_id = parts[2]
+            flags = parts[3]
+            if len(trace_id) == 32 and len(span_id) == 16:
+                return trace_id, span_id, flags
+    except Exception:
+        pass
+    return None
+
+
+def _build_traceparent(trace_id: str, span_id: str, sampled: bool = True) -> str:
+    flags = '01' if sampled else '00'
+    return f"00-{trace_id}-{span_id}-{flags}"
+
+
+class Tracer:
+    """
+    OpenTelemetry 兼容追踪器
+
+    Usage:
+        tracer = Tracer("my-service")
+        with tracer.span("my-operation") as span:
+            span.set_attribute("http.method", "GET")
+            ...
+    """
+    def __init__(self, service_name: str = "springpy-app", enabled: bool = True,
+                 sample_rate: float = 1.0, export_to_log: bool = True):
+        self.service_name = service_name
+        self.enabled = enabled
+        self.sample_rate = sample_rate
+        self.export_to_log = export_to_log
+        self._spans: List[Span] = []
+        self._lock = threading.Lock()
+        self._span_stack: ContextVar[List[Span]] = ContextVar('span_stack', default=[])
+
+    def _should_sample(self) -> bool:
+        if self.sample_rate >= 1.0:
+            return True
+        if self.sample_rate <= 0:
+            return False
+        return random.random() < self.sample_rate
+
+    def start_span(self, name: str, kind: SpanKind = SpanKind.INTERNAL,
+                   attributes: Dict[str, Any] = None,
+                   traceparent: str = None) -> Span:
+        if not self.enabled or not self._should_sample():
+            # 返回一个空span（disabled）
+            span = Span("0" * 32, "0" * 16, None, name, kind, self.service_name)
+            span._ended = True
+            return span
+
+        # 从context或traceparent获取父span
+        stack = self._span_stack.get()
+        parent_trace_id = None
+        parent_span_id = None
+
+        if traceparent:
+            parsed = _parse_traceparent(traceparent)
+            if parsed:
+                parent_trace_id, parent_span_id, _ = parsed
+
+        if parent_trace_id is None:
+            if stack:
+                parent = stack[-1]
+                parent_trace_id = parent.trace_id
+                parent_span_id = parent.span_id
+            else:
+                parent_trace_id = _generate_trace_id()
+
+        span_id = _generate_span_id()
+        span = Span(parent_trace_id, span_id, parent_span_id, name, kind, self.service_name)
+        if attributes:
+            span.attributes.update(attributes)
+
+        new_stack = list(stack) + [span]
+        self._span_stack.set(new_stack)
+        return span
+
+    def end_span(self, span: Span):
+        if span._ended or span.trace_id == "0" * 32:
+            return
+        span.end()
+        # 从栈中移除
+        stack = self._span_stack.get()
+        if stack and stack[-1] is span:
+            self._span_stack.set(stack[:-1])
+        with self._lock:
+            self._spans.append(span)
+        if self.export_to_log and span.status == SpanStatus.ERROR:
+            logger.error(f"[Trace] {span.trace_id[:16]}... {span.name} "
+                         f"status={span.status.value} duration={span.duration_ms:.2f}ms error={span.status_description}")
+        elif self.export_to_log:
+            logger.debug(f"[Trace] {span.trace_id[:16]}... {span.name} "
+                         f"duration={span.duration_ms:.2f}ms")
+
+    def span(self, name: str, kind: SpanKind = SpanKind.INTERNAL,
+             attributes: Dict[str, Any] = None, traceparent: str = None):
+        return _SpanContext(self, name, kind, attributes, traceparent)
+
+    def get_current_span(self) -> Optional[Span]:
+        stack = self._span_stack.get()
+        return stack[-1] if stack else None
+
+    def get_traceparent_header(self) -> str:
+        span = self.get_current_span()
+        if span and span.trace_id != "0" * 32:
+            return _build_traceparent(span.trace_id, span.span_id)
+        return ""
+
+    def inject_headers(self, headers: Dict[str, str]) -> Dict[str, str]:
+        """将traceparent注入HTTP headers（用于Feign跨服务调用）"""
+        tp = self.get_traceparent_header()
+        if tp:
+            headers['traceparent'] = tp
+            headers['X-B3-TraceId'] = self.get_current_span().trace_id
+            headers['X-B3-SpanId'] = self.get_current_span().span_id
+        return headers
+
+    def extract_from_headers(self, headers: Dict[str, str]) -> Optional[str]:
+        """从HTTP headers提取traceparent"""
+        if not headers:
+            return None
+        tp = headers.get('traceparent') or headers.get('Traceparent')
+        if not tp:
+            # 尝试 B3 格式
+            tid = headers.get('X-B3-TraceId')
+            sid = headers.get('X-B3-SpanId')
+            if tid and sid:
+                tp = f"00-{tid}-sid-01"
+        return tp
+
+    def get_spans(self, trace_id: str = None) -> List[Span]:
+        with self._lock:
+            if trace_id:
+                return [s for s in self._spans if s.trace_id == trace_id]
+            return list(self._spans)
+
+    def clear(self):
+        with self._lock:
+            self._spans.clear()
+
+
+class _SpanContext:
+    """Span 上下文管理器"""
+    def __init__(self, tracer: Tracer, name: str, kind: SpanKind,
+                 attributes: Dict[str, Any], traceparent: str):
+        self.tracer = tracer
+        self.name = name
+        self.kind = kind
+        self.attributes = attributes
+        self.traceparent = traceparent
+        self.span = None
+
+    def __enter__(self):
+        self.span = self.tracer.start_span(self.name, self.kind,
+                                           self.attributes, self.traceparent)
+        return self.span
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        if exc_val is not None:
+            self.span.record_exception(exc_val)
+        self.tracer.end_span(self.span)
+        return False
+
+
+# 全局Tracer实例
+_tracer_instance: Optional[Tracer] = None
+_tracer_lock = threading.Lock()
+
+
+def get_tracer(service_name: str = "springpy-app", **kwargs) -> Tracer:
+    global _tracer_instance
+    if _tracer_instance is None:
+        with _tracer_lock:
+            if _tracer_instance is None:
+                _tracer_instance = Tracer(service_name, **kwargs)
+    return _tracer_instance
+
+
+def trace_span(name: str = "", kind: SpanKind = SpanKind.INTERNAL):
+    """
+    @Trace 方法级追踪注解装饰器
+
+    Usage:
+        @trace_span("my-method")
+        def my_method():
+            ...
+    """
+    def decorator(func: Callable) -> Callable:
+        span_name = name or f"{func.__module__}.{func.__qualname__}"
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            tracer = get_tracer()
+            with tracer.span(span_name, kind) as span:
+                try:
+                    result = func(*args, **kwargs)
+                    return result
+                except Exception as e:
+                    span.record_exception(e)
+                    raise
+        return wrapper
+    return decorator

spring/config/__init__.py

@@ -0,0 +1,21 @@
+"""
+配置模块
+提供配置加载和管理功能
+"""
+from .config_loader import (
+    ConfigLoader,
+    ConfigurationError,
+    config_loader,
+    set_global_config_loader,
+    get_config,
+    get_config_value,
+)
+
+__all__ = [
+    'ConfigLoader',
+    'ConfigurationError',
+    'config_loader',
+    'set_global_config_loader',
+    'get_config',
+    'get_config_value',
+]

spring/config/binding.py

@@ -0,0 +1,206 @@
+"""配置属性松散绑定与校验（对齐 Spring Boot ``@ConfigurationProperties`` 松散绑定 +
+``@NestedConfigurationProperties`` + ``@Validated``）。
+
+能力：
+- **松散绑定**：``kebab-case`` / ``camelCase`` / ``snake_case`` / ``SCREAMING_SNAKE`` 等命名
+  规范化后等价匹配（对齐 Spring ``RelaxedNames``）。如 ``max-connections``、``maxConnections``、
+  ``max_connections`` 均绑定到属性 ``max_connections``。
+- **嵌套绑定**：属性类型标注为 ``@NestedConfigurationProperties`` 类时，递归绑定子字典到该类实例。
+- **类型强转**：标量值按属性类型注解强转（``int``/``float``/``bool``/``str``），避免 YAML 字符串误绑。
+- **校验**：类上标注 ``@Validated`` 时，绑定后调用 ``BeanValidator.validate_or_raise``，
+  违反约束抛 ``ValidationError``（对齐 Spring ``@Validated`` + Hibernate Validator）。
+
+设计：
+- **复用既有范式**：``@NestedConfigurationProperties`` 继承 ``SpringAnnotation``；校验复用
+  ``spring.validation.BeanValidator``，不重复造轮子。
+- **独立可测**：``ConfigurationPropertiesBinder.bind`` 为静态方法，无需 IoC 容器即可使用。
+- **集成点**：``ApplicationContext._apply_configuration_properties`` 调用本绑定器替代原扁平绑定。
+
+与 Java 的差异：
+- Spring 用 ``Binder`` + ``BeanBinder``；本实现用反射 + ``get_type_hints``，简化但覆盖常见场景。
+- 不支持 ``Duration``/``DataSize`` 等专用转换器（可按需扩展 ``_coerce``）。
+"""
+from __future__ import annotations
+
+import logging
+import re
+from typing import Any, Dict, Optional, Type, get_type_hints
+
+from spring.annotations.core import SpringAnnotation, Validated
+
+logger = logging.getLogger("Spring.Config.Binding")
+
+
+class NestedConfigurationProperties(SpringAnnotation):
+    """``@NestedConfigurationProperties`` 标记一个类可作为嵌套配置属性持有者。
+
+    标注后，父 ``@ConfigurationProperties`` 绑定时遇到该类型的属性会递归绑定子字典。
+    """
+
+    _annotation_type = "nested_properties"
+
+    def __init__(self, prefix: str = ""):
+        super().__init__(prefix=prefix)
+
+
+# 匹配非字母数字字符（kebab/camel/snake 分隔符）用于规范化
+_NON_ALNUM = re.compile(r'[^0-9a-zA-Z]+')
+
+
+def _normalize(name: str) -> str:
+    """规范化命名：去除分隔符并小写，用于松散匹配。
+
+    ``max-connections`` / ``maxConnections`` / ``max_connections`` / ``MAX_CONNECTIONS``
+    → ``maxconnections``。
+    """
+    if not isinstance(name, str):
+        return str(name).lower()
+    return _NON_ALNUM.sub('', name).lower()
+
+
+def _is_nested_config_class(cls: Optional[type]) -> bool:
+    """判断类是否标注 ``@NestedConfigurationProperties``。"""
+    if cls is None or not isinstance(cls, type):
+        return False
+    annotations = getattr(cls, '__spring_annotations__', [])
+    return any(isinstance(a, NestedConfigurationProperties) for a in annotations)
+
+
+def _coerce(value: Any, target_type: Optional[type]) -> Any:
+    """按目标类型强转标量值；无法强转则原样返回（交由校验器报错）。"""
+    if target_type is None or value is None:
+        return value
+    # 已经是目标类型，直接返回
+    if isinstance(value, target_type):
+        return value
+    try:
+        if target_type is bool:
+            # YAML 已把 true/false 解析为 bool；字符串场景兜底
+            if isinstance(value, str):
+                return value.strip().lower() in ('true', '1', 'yes', 'on')
+            return bool(value)
+        if target_type is int:
+            return int(value)
+        if target_type is float:
+            return float(value)
+        if target_type is str:
+            return str(value)
+    except (ValueError, TypeError):
+        return value  # 强转失败保留原值，由校验器/使用方处理
+    return value
+
+
+class ConfigurationPropertiesBinder:
+    """配置属性松散绑定器（静态方法风格，无状态）。"""
+
+    @staticmethod
+    def _resolve_attr_name(instance: Any, config_key: str, candidates: Dict[str, str]) -> Optional[str]:
+        """松散匹配：把 config_key 规范化后在属性候选表中查找。
+
+        ``candidates`` 为 ``{normalized_attr_name: actual_attr_name}``。
+        """
+        normalized = _normalize(config_key)
+        return candidates.get(normalized)
+
+    @staticmethod
+    def _attr_candidates(instance: Any) -> Dict[str, str]:
+        """构造属性候选表：``{规范化属性名: 实际属性名}``。
+
+        综合三类来源，确保 ``__init__`` 赋值的实例属性、类级注解属性、继承属性均可命中：
+        1. 类级类型注解（``get_type_hints``，最可靠，含继承）
+        2. 实例 ``__dict__``（``__init__`` 赋值的属性）
+        3. ``dir(cls)`` 类属性兜底
+        """
+        candidates: Dict[str, str] = {}
+        cls = type(instance)
+        # 1. 类型注解（含继承，最可靠的属性名来源）
+        try:
+            for attr in get_type_hints(cls):
+                if not attr.startswith('_'):
+                    candidates[_normalize(attr)] = attr
+        except Exception:
+            pass
+        # 2. 实例属性（__init__ 赋值）
+        for attr in vars(instance):
+            if not attr.startswith('_'):
+                candidates[_normalize(attr)] = attr
+        # 3. 类属性兜底
+        for attr in dir(cls):
+            if attr.startswith('_'):
+                continue
+            candidates.setdefault(_normalize(attr), attr)
+        return candidates
+
+    @staticmethod
+    def bind(instance: Any, config: Dict[str, Any]) -> Any:
+        """递归松散绑定 ``config`` 字典到 ``instance`` 的属性。
+
+        - 嵌套字典 + 属性类型为 ``@NestedConfigurationProperties`` 类 → 递归绑定。
+        - 标量按属性类型注解强转。
+        - 未匹配的键跳过（不报错，对齐 Spring 宽松绑定）。
+        """
+        if not isinstance(config, dict):
+            return instance
+        try:
+            type_hints = get_type_hints(type(instance))
+        except Exception:
+            type_hints = {}
+        candidates = ConfigurationPropertiesBinder._attr_candidates(instance)
+
+        for key, value in config.items():
+            attr_name = ConfigurationPropertiesBinder._resolve_attr_name(
+                instance, key, candidates
+            )
+            if attr_name is None:
+                logger.debug("配置键 '%s' 未匹配到属性，跳过", key)
+                continue
+            attr_type = type_hints.get(attr_name)
+            # 嵌套配置：值是字典且属性类型为 @NestedConfigurationProperties 类
+            if isinstance(value, dict) and _is_nested_config_class(attr_type):
+                nested_instance = ConfigurationPropertiesBinder._build_nested(attr_type)
+                if nested_instance is not None:
+                    ConfigurationPropertiesBinder.bind(nested_instance, value)
+                    setattr(instance, attr_name, nested_instance)
+                    continue
+            # 嵌套字典但属性类型非嵌套注解类：若属性类型是普通类，尝试递归绑定（容错）
+            if isinstance(value, dict) and isinstance(attr_type, type) and attr_type not in (dict,):
+                nested_instance = ConfigurationPropertiesBinder._build_nested(attr_type)
+                if nested_instance is not None and _is_nested_config_class(attr_type):
+                    ConfigurationPropertiesBinder.bind(nested_instance, value)
+                    setattr(instance, attr_name, nested_instance)
+                    continue
+            # 标量/列表/字典：按类型强转后赋值
+            setattr(instance, attr_name, _coerce(value, attr_type))
+        return instance
+
+    @staticmethod
+    def _build_nested(cls: type) -> Optional[Any]:
+        """构造嵌套配置类实例；构造失败返回 None。"""
+        try:
+            return cls()
+        except Exception as exc:
+            logger.warning("构造嵌套配置类 %s 失败: %s", cls.__name__, exc)
+            return None
+
+
+def validate_configuration_properties(instance: Any) -> None:
+    """若 ``instance`` 类标注了 ``@Validated``，运行 BeanValidator 校验，违反则抛错。
+
+    复用 ``spring.validation.BeanValidator``，未启用 validation 模块时静默跳过。
+    """
+    annotations = getattr(type(instance), '__spring_annotations__', [])
+    if not any(isinstance(a, Validated) for a in annotations):
+        return
+    try:
+        from spring.validation import BeanValidator
+    except ImportError:  # pragma: no cover - validation 为内置模块
+        logger.debug("spring.validation 未安装，跳过配置属性校验")
+        return
+    BeanValidator.validate_or_raise(instance)
+
+
+__all__ = [
+    "NestedConfigurationProperties",
+    "ConfigurationPropertiesBinder",
+    "validate_configuration_properties",
+]