springbootAI 1.8.0__py3-none-any.whl

spring/validation/constraints.py

@@ -0,0 +1,357 @@
+"""SpringBootAI Bean Validation 约束注解 —— 字段级描述符。
+
+设计原则：**复用项目既有范式，不重复造轮子**。本模块的字段级约束完全镜像 ORM 层
+``spring/orm/ddl_auto.py`` 的 ``Column``/``Id`` 与 Excel 层 ``spring/excel/annotations.py``
+的 ``ExcelProperty`` 元数据描述符范式：
+
+- 字段级约束以**类属性描述符**形式声明（推荐），Python 自动回填字段名；也支持**函数装饰器**
+  形式（镜像 ``column()`` / ``ExcelProperty.__call__``）。
+- 元数据通过 ``cls.__mro__`` 反射读取（与 ``Column``/``__column__`` 一致），由
+  ``BeanValidator`` 统一收集并校验。
+
+对齐 Jakarta Bean Validation（``javax.validation.constraints``）的核心约束：
+``@NotNull`` / ``@NotBlank`` / ``@NotEmpty`` / ``@Size`` / ``@Min`` / ``@Max`` /
+``@Pattern`` / ``@Email`` / ``@Positive`` / ``@PositiveOrZero`` / ``@Negative`` /
+``@NegativeOrZero`` / ``@AssertTrue`` / ``@AssertFalse``。
+
+与 Java 的差异（已标注）：
+- Java Bean Validation 是 JSR-380 标准 + Hibernate Validator 实现，运行时通过反射读注解；
+  本模块同样反射读字段描述符，但不依赖 JPA/Pydantic，适用于任意 Python 对象。
+- 约束只支持字段级（Java 还支持方法参数级/返回值级），方法级校验由 ``@BeanValidate`` AOP
+  切面对参数对象整体校验实现（见 ``validator.py``）。
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Callable, Optional
+
+
+class Constraint:
+    """所有字段约束的基类（镜像 ORM ``Column`` 描述符范式）。
+
+    子类需实现 ``_check(value) -> Optional[str]``，返回违规消息字符串；通过返回 ``None``
+    表示通过。``message`` 可由用户覆盖。
+
+    两种使用方式（与 ``Column``/``ExcelProperty`` 一致）：
+
+    1. 类属性描述符（推荐）::
+
+           class User:
+               name = NotBlank(message="姓名不能为空")
+               age = Min(0, message="年龄不能为负")
+               def __init__(self, name=None, age=None): ...
+
+    2. 函数装饰器（镜像 ``@column``）::
+
+           @NotBlank()
+           def name(self): ...
+    """
+
+    # 约束名，子类覆盖（用于校验报告归类）
+    constraint_name: str = "Constraint"
+
+    def __init__(self, message: Optional[str] = None):
+        self.message = message
+        self.attr_name: str = ""
+
+    def __set_name__(self, owner: type, name: str) -> None:
+        """类属性描述符形式时，Python 自动回填字段名（镜像 ``ExcelProperty``）。"""
+        self.attr_name = name
+
+    def __call__(self, target: Callable) -> Callable:
+        """函数装饰器形式：``@NotBlank()``，把约束挂到 ``__bean_constraint__`` 列表。
+
+        镜像 ORM ``column()`` 的 ``setattr(f, '__column__', col)`` 与
+        ``ExcelProperty.__call__`` 的 ``setattr(target, '__excel_property__', self)``。
+        一个方法上可叠加多个约束（用列表累积，而非覆盖）。
+        """
+        existing = getattr(target, "__bean_constraint__", None)
+        if isinstance(existing, list):
+            existing.append(self)
+        else:
+            setattr(target, "__bean_constraint__", [self])
+        if not self.attr_name:
+            self.attr_name = getattr(target, "__name__", "")
+        return target
+
+    def _check(self, value: Any) -> Optional[str]:
+        """子类实现：返回违规消息（None 表示通过）。"""
+        raise NotImplementedError
+
+    def validate(self, value: Any) -> Optional[str]:
+        """对外校验入口：返回违规消息或 None。
+
+        默认消息优先取用户自定义 ``message``，否则取 ``_check`` 返回的默认消息。
+        """
+        msg = self._check(value)
+        if msg is None:
+            return None
+        return self.message if self.message else msg
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(attr={self.attr_name!r})"
+
+
+# ==================== 非空类约束 ====================
+
+class NotNull(Constraint):
+    """``@NotNull``：值不能为 None（允许空字符串/空集合）。
+
+    对齐 ``javax.validation.constraints.NotNull``。
+    """
+    constraint_name = "NotNull"
+
+    def _check(self, value: Any) -> Optional[str]:
+        if value is None:
+            return "不能为 null"
+        return None
+
+
+class NotBlank(Constraint):
+    """``@NotBlank``：字符串不能为 None 且去除首尾空白后长度 > 0。
+
+    对齐 ``javax.validation.constraints.NotBlank``（仅作用于字符串）。
+    """
+    constraint_name = "NotBlank"
+
+    def _check(self, value: Any) -> Optional[str]:
+        if value is None:
+            return "不能为空"
+        if not isinstance(value, str):
+            return None  # 非字符串交给其他约束（如 NotNull）
+        if value.strip() == "":
+            return "不能为空白"
+        return None
+
+
+class NotEmpty(Constraint):
+    """``@NotEmpty``：不能为 None 且 size > 0（字符串/集合/字典/数组）。
+
+    对齐 ``javax.validation.constraints.NotEmpty``。
+    """
+    constraint_name = "NotEmpty"
+
+    def _check(self, value: Any) -> Optional[str]:
+        if value is None:
+            return "不能为空"
+        try:
+            if len(value) == 0:
+                return "长度/大小必须大于 0"
+        except TypeError:
+            return None  # 无 len() 的对象，不强制
+        return None
+
+
+# ==================== 长度/大小约束 ====================
+
+class Size(Constraint):
+    """``@Size``：字符串/集合/数组长度在 ``[min, max]`` 区间。
+
+    对齐 ``javax.validation.constraints.Size``。``min`` 默认 0，``max`` 默认 2^31-1。
+    """
+    constraint_name = "Size"
+
+    def __init__(self, min: int = 0, max: int = 2 ** 31 - 1, message: Optional[str] = None):
+        super().__init__(message=message)
+        if min < 0:
+            raise ValueError("@Size min 不能为负")
+        if max < min:
+            raise ValueError("@Size max 不能小于 min")
+        self.min = min
+        self.max = max
+
+    def _check(self, value: Any) -> Optional[str]:
+        if value is None:
+            return None  # null 交给 @NotNull
+        try:
+            length = len(value)
+        except TypeError:
+            return None  # 无 len() 的对象，不强制
+        if length < self.min or length > self.max:
+            return f"长度必须在 {self.min} 到 {self.max} 之间（实际 {length}）"
+        return None
+
+
+# ==================== 数值范围约束 ====================
+
+class Min(Constraint):
+    """``@Min``：数值 >= value。对齐 ``javax.validation.constraints.Min``。"""
+    constraint_name = "Min"
+
+    def __init__(self, value: Any, message: Optional[str] = None):
+        super().__init__(message=message)
+        self.value = value
+
+    def _check(self, value: Any) -> Optional[str]:
+        if value is None:
+            return None
+        try:
+            if float(value) < float(self.value):
+                return f"必须大于等于 {self.value}"
+        except (TypeError, ValueError):
+            return None  # 非数值，不强制
+        return None
+
+
+class Max(Constraint):
+    """``@Max``：数值 <= value。对齐 ``javax.validation.constraints.Max``。"""
+    constraint_name = "Max"
+
+    def __init__(self, value: Any, message: Optional[str] = None):
+        super().__init__(message=message)
+        self.value = value
+
+    def _check(self, value: Any) -> Optional[str]:
+        if value is None:
+            return None
+        try:
+            if float(value) > float(self.value):
+                return f"必须小于等于 {self.value}"
+        except (TypeError, ValueError):
+            return None
+        return None
+
+
+class Positive(Constraint):
+    """``@Positive``：数值 > 0。对齐 ``javax.validation.constraints.Positive``。"""
+    constraint_name = "Positive"
+
+    def _check(self, value: Any) -> Optional[str]:
+        if value is None:
+            return None
+        try:
+            if float(value) <= 0:
+                return "必须为正数"
+        except (TypeError, ValueError):
+            return None
+        return None
+
+
+class PositiveOrZero(Constraint):
+    """``@PositiveOrZero``：数值 >= 0。"""
+    constraint_name = "PositiveOrZero"
+
+    def _check(self, value: Any) -> Optional[str]:
+        if value is None:
+            return None
+        try:
+            if float(value) < 0:
+                return "必须大于等于 0"
+        except (TypeError, ValueError):
+            return None
+        return None
+
+
+class Negative(Constraint):
+    """``@Negative``：数值 < 0。"""
+    constraint_name = "Negative"
+
+    def _check(self, value: Any) -> Optional[str]:
+        if value is None:
+            return None
+        try:
+            if float(value) >= 0:
+                return "必须为负数"
+        except (TypeError, ValueError):
+            return None
+        return None
+
+
+class NegativeOrZero(Constraint):
+    """``@NegativeOrZero``：数值 <= 0。"""
+    constraint_name = "NegativeOrZero"
+
+    def _check(self, value: Any) -> Optional[str]:
+        if value is None:
+            return None
+        try:
+            if float(value) > 0:
+                return "必须小于等于 0"
+        except (TypeError, ValueError):
+            return None
+        return None
+
+
+# ==================== 字符串格式约束 ====================
+
+class Pattern(Constraint):
+    """``@Pattern``：字符串匹配正则。对齐 ``javax.validation.constraints.Pattern``。"""
+    constraint_name = "Pattern"
+
+    def __init__(self, regex: str, message: Optional[str] = None):
+        super().__init__(message=message)
+        try:
+            self._compiled = re.compile(regex)
+        except re.error as e:
+            raise ValueError(f"@Pattern 正则非法: {e}") from e
+        self.regex = regex
+
+    def _check(self, value: Any) -> Optional[str]:
+        if value is None:
+            return None
+        if not isinstance(value, str):
+            value = str(value)
+        if not self._compiled.search(value):
+            return f"不匹配模式 {self.regex!r}"
+        return None
+
+
+# 常见邮箱正则（与 Hibernate Validator Email 推荐一致，宽松版本）
+_EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
+
+
+class Email(Constraint):
+    """``@Email``：字符串为合法邮箱格式。对齐 ``javax.validation.constraints.Email``。
+
+    采用宽松邮箱正则（``local@domain.tld``），不追求 RFC 5322 完整覆盖，
+    生产环境如需更严格校验请配合 ``@Pattern`` 自定义。
+    """
+    constraint_name = "Email"
+
+    def _check(self, value: Any) -> Optional[str]:
+        if value is None:
+            return None
+        if not isinstance(value, str):
+            value = str(value)
+        if value == "":
+            return None  # 空串交给 @NotBlank
+        if not _EMAIL_RE.match(value):
+            return "邮箱格式不合法"
+        return None
+
+
+# ==================== 布尔断言约束 ====================
+
+class AssertTrue(Constraint):
+    """``@AssertTrue``：值必须为 True（或真值）。对齐 ``javax.validation.constraints.AssertTrue``。"""
+    constraint_name = "AssertTrue"
+
+    def _check(self, value: Any) -> Optional[str]:
+        if value is None:
+            return None
+        if not bool(value):
+            return "必须为 true"
+        return None
+
+
+class AssertFalse(Constraint):
+    """``@AssertFalse``：值必须为 False（或假值）。对齐 ``javax.validation.constraints.AssertFalse``。"""
+    constraint_name = "AssertFalse"
+
+    def _check(self, value: Any) -> Optional[str]:
+        if value is None:
+            return None
+        if bool(value):
+            return "必须为 false"
+        return None
+
+
+__all__ = [
+    "Constraint",
+    "NotNull", "NotBlank", "NotEmpty",
+    "Size",
+    "Min", "Max",
+    "Positive", "PositiveOrZero", "Negative", "NegativeOrZero",
+    "Pattern", "Email",
+    "AssertTrue", "AssertFalse",
+]

spring/validation/exceptions.py

@@ -0,0 +1,55 @@
+"""SpringBootAI Bean Validation 异常定义。
+
+设计对齐 Jakarta Bean Validation（Hibernate Validator）的错误语义：
+- ``ValidationError``：校验失败时抛出的汇总异常，包含全部约束违反。
+- ``ConstraintViolation``：单条约束违反信息（字段、值、消息、约束类型）。
+"""
+from __future__ import annotations
+
+from typing import Any, List
+
+
+class ConstraintViolation:
+    """单条约束违反记录。
+
+    属性：
+        attr_name:    违反约束的字段名。
+        value:        被校验的实际值。
+        constraint:   触发违反的约束注解实例（如 ``NotNull``/``Size``）。
+        message:      人可读的违规描述。
+    """
+
+    __slots__ = ("attr_name", "value", "constraint", "message")
+
+    def __init__(self, attr_name: str, value: Any, constraint: Any, message: str):
+        self.attr_name = attr_name
+        self.value = value
+        self.constraint = constraint
+        self.message = message
+
+    def __repr__(self) -> str:
+        cname = type(self.constraint).__name__
+        return (f"ConstraintViolation(attr={self.attr_name!r}, "
+                f"constraint={cname}, value={self.value!r}, message={self.message!r})")
+
+    def __str__(self) -> str:
+        return f"{self.attr_name}: {self.message}"
+
+
+class ValidationError(Exception):
+    """Bean Validation 校验失败异常。
+
+    汇总一次校验产生的所有 ``ConstraintViolation``，便于上层统一处理或批量回显。
+    """
+
+    def __init__(self, violations: List[ConstraintViolation]):
+        self.violations: List[ConstraintViolation] = list(violations)
+        lines = "; ".join(str(v) for v in self.violations) if self.violations else "校验失败"
+        super().__init__(lines)
+
+    @property
+    def messages(self) -> List[str]:
+        return [v.message for v in self.violations]
+
+
+__all__ = ["ConstraintViolation", "ValidationError"]

spring/validation/validator.py

@@ -0,0 +1,139 @@
+"""SpringBootAI Bean Validation 验证器。
+
+``BeanValidator`` 反射实体类的字段约束（``Constraint`` 描述符或 ``__bean_constraint__``
+函数装饰器），对一个对象实例执行全部约束校验，收集 ``ConstraintViolation``。
+
+镜像 ORM ``DdlAutoManager._parse_entity`` 与 Excel ``parse_excel_columns`` 的反射范式：
+遍历 ``cls.__mro__`` 的 ``__dict__``，自底向上收集每个字段的约束列表，子类覆盖父类。
+
+用法::
+
+    from spring.validation import BeanValidator, NotBlank, Min
+
+    class User:
+        name = NotBlank(message="姓名不能为空")
+        age = Min(0)
+        def __init__(self, name=None, age=None):
+            self.name = name; self.age = age
+
+    violations = BeanValidator.validate(User(name="", age=-1))
+    if violations:
+        ...  # 处理违规
+    BeanValidator.validate_or_raise(User(name="Tom", age=18))  # 通过则不抛错
+
+方法级校验由 ``@BeanValidate`` AOP 切面驱动（注册到 ``comprehensive_aop``），见模块 ``__init__``。
+"""
+from __future__ import annotations
+
+import inspect
+from typing import Any, Dict, List, Optional, Type
+
+from .constraints import Constraint
+from .exceptions import ConstraintViolation, ValidationError
+
+
+def _collect_constraints(cls: Type) -> Dict[str, List[Constraint]]:
+    """反射收集类（含 MRO 父类）每个字段的约束列表。
+
+    镜像 ORM ``_parse_entity`` 与 Excel ``parse_excel_columns`` 的 MRO 遍历：
+    自底向上（``reversed(cls.__mro__)``），子类约束覆盖父类同名字段。
+    支持两种声明形式：
+      1. 类属性 ``Constraint`` 描述符（如 ``name = NotBlank()``）。
+      2. 函数上的 ``__bean_constraint__`` 列表（``@NotBlank() def name(self): ...``）。
+    """
+    collected: Dict[str, List[Constraint]] = {}
+
+    for base in reversed(cls.__mro__):
+        if base is object:
+            continue
+        for attr_name, value in vars(base).items():
+            if attr_name.startswith("__"):
+                continue
+            constraints: List[Constraint] = []
+            # 形式1：类属性 Constraint 描述符实例
+            if isinstance(value, Constraint):
+                if not value.attr_name:
+                    value.attr_name = attr_name
+                constraints.append(value)
+            # 形式2：函数装饰器上的 __bean_constraint__ 列表
+            elif hasattr(value, "__bean_constraint__"):
+                clist = getattr(value, "__bean_constraint__")
+                if isinstance(clist, list):
+                    for c in clist:
+                        if isinstance(c, Constraint) and not c.attr_name:
+                            c.attr_name = attr_name
+                        constraints.append(c)
+            if constraints:
+                # 子类覆盖父类同名字段（与 ORM/Excel 解析一致）
+                collected[attr_name] = constraints
+    return collected
+
+
+def _get_field_value(obj: Any, attr_name: str) -> Any:
+    """从对象实例取字段值：优先 ``getattr``，失败则 None。"""
+    try:
+        return getattr(obj, attr_name)
+    except AttributeError:
+        return None
+
+
+class BeanValidator:
+    """Bean Validation 校验器（静态方法风格，无状态，可直接调用）。
+
+    设计为无状态工具类，对齐 Jakarta ``Validator`` 接口的 ``validate`` 语义，
+    但简化为静态方法，避免在未接入 IoC 容器的场景下还需手动构造实例。
+    """
+
+    @staticmethod
+    def get_constraints(cls: Type) -> Dict[str, List[Constraint]]:
+        """返回类上声明的字段约束映射（公开 API，便于调试/报告）。"""
+        return _collect_constraints(cls)
+
+    @staticmethod
+    def validate(obj: Any, groups: Optional[List[type]] = None) -> List[ConstraintViolation]:
+        """校验对象实例，返回全部约束违反列表（通过则返回空列表）。
+
+        Args:
+            obj:    待校验对象。若是类，则按无实例处理（仅字段无值，仅 NotNull 类会触发）。
+            groups: 校验分组（对齐 Jakarta Validation groups）。当前实现：约束未声明 groups
+                    时始终执行；声明了 groups 时仅当传入 groups 命中才执行。
+                    （分组功能为兼容预留，约束默认不限定分组。）
+        """
+        if obj is None:
+            return []
+        cls = obj if isinstance(obj, type) else type(obj)
+        constraints_map = _collect_constraints(cls)
+
+        violations: List[ConstraintViolation] = []
+        for attr_name, constraints in constraints_map.items():
+            value = None if isinstance(obj, type) else _get_field_value(obj, attr_name)
+            for constraint in constraints:
+                # 分组过滤：约束可选声明 groups
+                cgroups = getattr(constraint, "groups", None) or []
+                if cgroups:
+                    if not groups or not any(g in cgroups for g in groups):
+                        continue
+                msg = constraint.validate(value)
+                if msg is not None:
+                    violations.append(ConstraintViolation(
+                        attr_name=attr_name,
+                        value=value,
+                        constraint=constraint,
+                        message=msg,
+                    ))
+        return violations
+
+    @staticmethod
+    def validate_or_raise(obj: Any, groups: Optional[List[type]] = None) -> None:
+        """校验对象实例，存在违反则抛出 ``ValidationError``；通过则无返回。"""
+        violations = BeanValidator.validate(obj, groups=groups)
+        if violations:
+            raise ValidationError(violations)
+
+    @staticmethod
+    def is_valid(obj: Any, groups: Optional[List[type]] = None) -> bool:
+        """便捷判断：是否通过全部约束。"""
+        return not BeanValidator.validate(obj, groups=groups)
+
+
+__all__ = ["BeanValidator", "_collect_constraints"]

spring/web/__init__.py

@@ -0,0 +1,12 @@
+from .web_context import WebApplicationContext
+from .result import Result
+from .interceptor import HandlerInterceptor, InterceptorRegistry
+from .exception_handler import GlobalExceptionHandler
+
+__all__ = [
+    "WebApplicationContext",
+    "Result",
+    "HandlerInterceptor",
+    "InterceptorRegistry",
+    "GlobalExceptionHandler",
+]