python-ddd-framework 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

python_ddd_framework/extensions/models.py

@@ -0,0 +1,142 @@
+"""Application 内的有效模型图；共享 DTO、字段和原生泛型保持不变。"""
+
+from __future__ import annotations
+
+import types
+from collections.abc import Mapping
+from copy import copy
+from functools import reduce
+from operator import or_
+from typing import Annotated, Any, ForwardRef, TypeAliasType, Union, get_args, get_origin
+
+from pydantic import BaseModel, ConfigDict, Field, create_model, model_validator
+from pydantic.fields import FieldInfo
+
+from .contracts import ExtensibleModel, ExtensionProperties
+
+
+class _EffectiveModels:
+    def __init__(
+        self, properties: Mapping[type[ExtensibleModel], type[ExtensionProperties]]
+    ) -> None:
+        self._properties: dict[type[BaseModel], type[ExtensionProperties]] = {
+            model: schema for model, schema in properties.items()
+        }
+        self._models: dict[type[BaseModel], type[BaseModel]] = {}
+
+    def annotation(self, annotation: object) -> object:
+        graph: dict[type[BaseModel], dict[str, FieldInfo]] = {}
+        self._collect(annotation, graph)
+        affected = set(self._properties) | self._models.keys()
+        # 先闭合依赖图，再创建所有前向引用，支持自递归及相互引用的普通 DTO。
+        while True:
+            parents = {
+                model
+                for model, fields in graph.items()
+                if any(_model_types(field.annotation) & affected for field in fields.values())
+            }
+            if parents <= affected:
+                break
+            affected |= parents
+        pending = [model for model in graph if model in affected]
+        symbols = {model: f"_pddd_model_{len(self._models) + i}" for i, model in enumerate(pending)}
+        replacements: dict[type[BaseModel], object] = {
+            **self._models,
+            **{model: ForwardRef(symbol) for model, symbol in symbols.items()},
+        }
+        for model in pending:
+            definitions: dict[str, Any] = {
+                name: (_replace(field.annotation, replacements), copy(field))
+                for name, field in graph[model].items()
+            }
+            self._models[model] = create_model(
+                model.__name__,
+                __base__=model,
+                __module__=model.__module__,
+                __config__=ConfigDict(
+                    defer_build=True, revalidate_instances="always", validate_default=True
+                ),
+                __validators__={"_pddd_effective_input": _instance_validator(model)},
+                **definitions,
+            )
+        namespace = {symbol: self._models[model] for model, symbol in symbols.items()}
+        for model in pending:
+            self._models[model].model_config["defer_build"] = False
+        for model in pending:
+            self._models[model].model_rebuild(_types_namespace=namespace)
+        return _replace(annotation, self._models)
+
+    def _collect(
+        self, annotation: object, graph: dict[type[BaseModel], dict[str, FieldInfo]]
+    ) -> None:
+        for model in _model_types(annotation):
+            if model in graph or model in self._models:
+                continue
+            fields = dict(model.model_fields)
+            if model in self._properties:
+                properties = self._properties[model]
+                fields["extra_properties"] = FieldInfo.from_annotated_attribute(
+                    properties, Field(default_factory=properties)
+                )
+            graph[model] = fields
+            for field in fields.values():
+                self._collect(field.annotation, graph)
+
+
+def _model_types(
+    annotation: object, aliases: frozenset[TypeAliasType] = frozenset()
+) -> set[type[BaseModel]]:
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return {annotation}
+    if isinstance(annotation, TypeAliasType):
+        return (
+            set()
+            if annotation in aliases
+            else _model_types(annotation.__value__, aliases | {annotation})
+        )
+    args = get_args(annotation)
+    if get_origin(annotation) is Annotated:
+        args = args[:1]
+    return {model for arg in args for model in _model_types(arg, aliases)}
+
+
+def _replace(annotation: object, models: Mapping[type[BaseModel], object]) -> Any:
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return models.get(annotation, annotation)
+    if isinstance(annotation, TypeAliasType):
+        if not _model_types(annotation) & models.keys():
+            return annotation
+        updated = _replace(annotation.__value__, models)
+        return annotation if updated == annotation.__value__ else updated
+    args = get_args(annotation)
+    if not args:
+        return annotation
+    origin = get_origin(annotation)
+    if origin is Annotated:
+        return Annotated[_replace(args[0], models), *args[1:]]
+    updated_args = tuple(_replace(item, models) for item in args)
+    if updated_args == args:
+        return annotation
+    if origin in (Union, types.UnionType):
+        return reduce(or_, updated_args)
+    if isinstance(origin, TypeAliasType):
+        return origin[updated_args]
+    if isinstance(origin, type):
+        return types.GenericAlias(origin, updated_args)
+    raise TypeError("unsupported extension annotation container")
+
+
+def _instance_validator(original: type[BaseModel]) -> Any:
+    # Pydantic 泛型会接受同一 origin 的未参数化／不同参数化实例，再重验字段。
+    origin = original.__pydantic_generic_metadata__["origin"] or original
+
+    def accept_instance(value: object) -> object:
+        if isinstance(value, origin):
+            # 保留 Python 原值而非 JSON dump；strict 类型、嵌套实例和未知字段都须继续重验。
+            return {
+                **{name: getattr(value, name) for name in type(value).model_fields},
+                **(value.model_extra or {}),
+            }
+        return value
+
+    return model_validator(mode="before")(accept_instance)

python_ddd_framework/extensions/module.py

@@ -0,0 +1,21 @@
+"""在方法编译前组装有效 DTO；Provider 只在正式 bind 阶段贡献。"""
+
+from dishka import Provider, Scope
+
+from ..lifecycle import ConfigureContext
+from ..modularity import AppModule
+from ..services.composition import ServiceBindingContext, ServiceComposition
+from .catalog import ExtensionCatalog
+
+
+class ExtensionsModule(AppModule):
+    catalog: ExtensionCatalog
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.services.add_composition(ServiceComposition(bind=self._bind))
+
+    def _bind(self, context: ServiceBindingContext) -> None:
+        self.catalog = ExtensionCatalog(context.modules)
+        provider = Provider()
+        provider.provide(lambda: self.catalog, provides=ExtensionCatalog, scope=Scope.APP)
+        context.add_provider(provider)

python_ddd_framework/fastapi/__init__.py

@@ -15,6 +15,7 @@ from .filters import ActionFilterContext, ServiceFilter, service_filter
 from .http import remote_service
 from .http_router import HttpRouter
 from .middleware import DiMiddleware
+from .module import FastApiModule
 from .realtime import (
     FastApiRealtimeModule,
     FastApiRealtimeOptions,
@@ -29,6 +30,7 @@ __all__ = (
     "DiMiddleware",
     "FastApiAdapter",
     "FastApiAdapterError",
+    "FastApiModule",
     "FastApiRealtimeModule",
     "FastApiRealtimeOptions",
     "HttpRouter",

python_ddd_framework/fastapi/action.py

@@ -14,11 +14,10 @@ from anyio import CancelScope
 from dishka import AsyncContainer
 from starlette.requests import Request
 
-from ..application_services.contracts import _DEFAULT_CONNECTION_NAME
 from ..application_services.invocation import _InvocationRuntime, _InvocationState, _managed_action
 from ..invocation import ApplicationInvocationContext
 from ..unit_of_work import UnitOfWork, UnitOfWorkManager
-from ..unit_of_work.options import UnitOfWorkDeclaration
+from ..unit_of_work.options import _DEFAULT_CONNECTION_NAME, UnitOfWorkDeclaration
 from .errors import FastApiAdapterError
 from .filters import ActionFilterContext, ServiceFilter, _run_filters
 from .transfer import _manage_stream

python_ddd_framework/fastapi/adapter.py

@@ -25,6 +25,7 @@ from .contracts import RouterCatalog
 from .errors import FastApiAdapterError
 from .filters import ServiceFilter, _validate_filters
 from .middleware import DiMiddleware, _compile_middlewares
+from .module import FastApiModule
 from .realtime.runtime import _FastApiRealtimeRuntime
 from .request_context import (
     _RequestContextMiddleware,
@@ -82,6 +83,12 @@ class FastApiAdapter:
         self._api_prefix = api_prefix
         if not isinstance(application, Application):
             raise TypeError("application must be python_ddd_framework.Application")
+        # 安装只能使用已组成的能力，不能在 build 后临时补注册或隐式启动调用运行时。
+        application.modules.require_dependency(
+            application.modules.startup.key,
+            FastApiModule,
+            source=application.modules.startup.declaration_source,
+        )
         self._filters = tuple(filters)
         if upload_limits is not None and not isinstance(upload_limits, UploadLimits):
             raise TypeError("upload_limits must be UploadLimits")
@@ -300,6 +307,15 @@ async def _business_error_handler(request: Request, error: Exception) -> JSONRes
                 "code": business_error.definition.code,
                 "message": business_error.definition.message,
                 "fields": [field.name for field in business_error.fields],
+                **(
+                    {
+                        "data": business_error.data.model_dump(
+                            mode="json", by_alias=True, warnings="error"
+                        )
+                    }
+                    if business_error.data is not None
+                    else {}
+                ),
             }
         },
     )

python_ddd_framework/fastapi/application_services.py

@@ -10,15 +10,18 @@ from dataclasses import dataclass, is_dataclass
 from datetime import date, datetime, time
 from decimal import Decimal
 from enum import Enum
-from typing import Annotated, Any, Literal, Union, cast, get_args, get_origin, get_type_hints
+from typing import Annotated, Any, Literal, Union, cast, get_args, get_origin
 from uuid import UUID
 
 from dishka import AsyncContainer
+from dishka.integrations.base import default_parse_dependency
 from dishka.integrations.fastapi import DishkaRoute, FromDishka
 from fastapi import APIRouter, Depends
-from fastapi.params import Body, Param, Path
+from fastapi.params import Body, Param, Path, Query
+from fastapi.params import Depends as DependsParameter
 from fastapi.security import HTTPBearer
 from pydantic import BaseModel
+from pydantic.fields import FieldInfo
 from starlette.requests import Request
 from starlette.responses import Response
 from starlette.routing import compile_path
@@ -27,9 +30,11 @@ from ..application import Application
 from ..application_services import (
     ApplicationServiceRegistration,
 )
-from ..application_services.catalog import _CompiledApplicationService, _CompiledMethod
+from ..application_services.catalog import _CompiledApplicationService
 from ..application_services.dispatcher import _ApplicationServiceDispatcher
+from ..application_services.module import ApplicationServicesModule
 from ..diagnostics import SourceLocation
+from ..invocation.methods import _CompiledMethod
 from ..modularity import AppModule, ModuleDescriptor, ModuleKey
 from .action import _HttpActionOwner, _request_parameter
 from .contracts import (
@@ -184,15 +189,19 @@ def _create_exposure_router(
     registrations = tuple(
         registration
         for target in target_descriptors
-        for registration in application.application_service_catalog.registrations
-        if registration.is_public_service and registration.owner == target.key
+        for registration in application.modules.instance(
+            ApplicationServicesModule
+        ).catalog.registrations
+        if registration.owner == target.key
     )
     overrides = _index_overrides(exposure, registrations)
     router = APIRouter(route_class=_ApplicationServiceRoute)
     for registration in registrations:
         if registration.is_integration_service:
             continue
-        compiled_service = application.application_service_catalog._for_registration(registration)
+        compiled_service = application.modules.instance(
+            ApplicationServicesModule
+        ).catalog._for_registration(registration)
         service_override = overrides.get((registration.contract, None))
         if service_override is not None:
             continue
@@ -218,8 +227,13 @@ def _create_exposure_router(
             )
             route_method = _inspect_route_method(
                 registration.contract,
-                compiled_method.implementation_method,
                 method_registration.name,
+                compiled_method.implementation_signature,
+            )
+            verb = projection.pop("verb", _conventional_verb(method_registration.name))
+            route_method = _RouteMethod(
+                route_method.signature,
+                tuple(_query_model_parameter(p, verb) for p in route_method.parameters),
             )
             declared_path = projection.pop("path", None)
             if declared_path is not None and provenance["path"] == "method":
@@ -239,7 +253,6 @@ def _create_exposure_router(
                     application._container_for_integration(),
                     infer_services=False,
                 )
-            verb = projection.pop("verb", _conventional_verb(method_registration.name))
             operation_id = projection.pop(
                 "operation_id", _operation_id(registration.contract, method_registration.name)
             )
@@ -362,27 +375,13 @@ def _index_overrides(
 
 def _inspect_route_method(
     contract: type[object],
-    method: Callable[..., Awaitable[object]],
     method_name: str,
+    signature: inspect.Signature,
 ) -> _RouteMethod:
     """在真实 FastAPI app 变更前解析并收窄动态 typing boundary。"""
 
-    try:
-        annotations = get_type_hints(method, include_extras=True)
-    except (NameError, TypeError) as original_error:
-        raise FastApiAdapterError(
-            f"HTTP method annotations cannot be resolved for {contract.__module__}."
-            f"{contract.__qualname__}.{method_name}: {type(original_error).__name__}"
-        ) from original_error
-    signature = inspect.signature(method)
-    resolved_parameters = tuple(
-        parameter.replace(annotation=annotations.get(name, parameter.annotation))
-        for name, parameter in signature.parameters.items()
-    )
-    signature = signature.replace(
-        parameters=resolved_parameters,
-        return_annotation=annotations.get("return", signature.return_annotation),
-    )
+    # 共享方法编译已解释本 Application 的扩展 DTO；HTTP 不另建字段权威。
+    resolved_parameters = tuple(signature.parameters.values())
     parameters = resolved_parameters[1:]
     for parameter in parameters:
         if parameter.kind in (
@@ -407,6 +406,25 @@ def _inspect_route_method(
     return _RouteMethod(signature=signature, parameters=parameters)
 
 
+def _query_model_parameter(parameter: inspect.Parameter, verb: str) -> inspect.Parameter:
+    hint = parameter.annotation
+    metadata = get_args(hint)[1:] if get_origin(hint) is Annotated else ()
+    model = get_args(hint)[0] if metadata else hint
+    if (
+        verb == "GET"
+        and isinstance(model, type)
+        and issubclass(model, BaseModel)
+        and not any(
+            isinstance(value, (FieldInfo, DependsParameter))
+            for value in (*metadata, parameter.default)
+        )
+        and default_parse_dependency(parameter, hint) is None
+    ):
+        # 仅补原生 Query 元数据；字段展开、校验和 OpenAPI 均交给 FastAPI/Pydantic。
+        return parameter.replace(annotation=Annotated[hint, Query()])
+    return parameter
+
+
 def _uses_non_path_binding(parameter: inspect.Parameter) -> bool:
     metadata = (
         get_args(parameter.annotation)[1:] if get_origin(parameter.annotation) is Annotated else ()

python_ddd_framework/fastapi/background.py

@@ -4,6 +4,7 @@ from ..background_execution.management import BackgroundManagementApplicationSer
 from ..background_execution.module import BackgroundManagementModule
 from ..modularity import AppModule
 from .contracts import ApplicationServiceRouteOverride, exposes_application_services
+from .module import FastApiModule
 
 
 @exposes_application_services(
@@ -39,4 +40,4 @@ from .contracts import ApplicationServiceRouteOverride, exposes_application_serv
     ),
 )
 class BackgroundManagementHttpApiModule(AppModule):
-    dependencies = (BackgroundManagementModule,)
+    dependencies = (FastApiModule,)

python_ddd_framework/fastapi/contracts.py

@@ -10,7 +10,7 @@ from fastapi import APIRouter
 
 from ..application_services import ApplicationService, ApplicationServiceContract
 from ..diagnostics import SourceLocation
-from ..modularity import AppModule, ModuleKey
+from ..modularity import AppModule, ModuleDeclaration, ModuleDependency, ModuleKey, ModuleRef
 from .errors import FastApiAdapterError
 
 _ROUTER_METADATA_ATTRIBUTE = "__python_ddd_framework_fastapi_routers__"
@@ -139,11 +139,24 @@ class ApplicationServiceRouteOverride:
 
 
 @dataclass(frozen=True, slots=True)
-class _ApplicationServiceExposure:
+class _ApplicationServiceExposure(ModuleDeclaration):
     target_modules: tuple[type[AppModule], ...]
     root_path: str
     overrides: tuple[ApplicationServiceRouteOverride, ...]
 
+    @property
+    def required_module(self) -> ModuleDependency:
+        return ModuleRef("python_ddd_framework.fastapi.module:FastApiModule")
+
+
+@dataclass(frozen=True, slots=True)
+class _RouterDeclarations(ModuleDeclaration):
+    routers: tuple[APIRouter, ...]
+
+    @property
+    def required_module(self) -> ModuleDependency:
+        return ModuleRef("python_ddd_framework.fastapi.module:FastApiModule")
+
 
 def contributes_routers(*routers: APIRouter) -> Callable[[_ModuleType], _ModuleType]:
     """把 immutable router tuple 附着到当前 Module class，不建立 global registry。"""
@@ -161,7 +174,7 @@ def contributes_routers(*routers: APIRouter) -> Callable[[_ModuleType], _ModuleT
             raise FastApiAdapterError(
                 f"{module_type.__module__}:{module_type.__qualname__} already declares routers"
             )
-        setattr(module_type, _ROUTER_METADATA_ATTRIBUTE, routers)
+        setattr(module_type, _ROUTER_METADATA_ATTRIBUTE, _RouterDeclarations(routers))
         return module_type
 
     return decorate
@@ -172,7 +185,7 @@ def exposes_application_services(
     root_path: str = "",
     overrides: tuple[ApplicationServiceRouteOverride, ...] = (),
 ) -> Callable[[_ModuleType], _ModuleType]:
-    """让 HTTP Module 显式暴露其直接依赖 Module 拥有的 Application Services。"""
+    """选择公开服务并贡献正式 Module 依赖，由统一图处理去重、环和排序。"""
 
     if not target_modules:
         raise FastApiAdapterError(
@@ -208,22 +221,27 @@ def exposes_application_services(
                 f"{module_type.__module__}:{module_type.__qualname__} already declares "
                 "application service exposure"
             )
+        if not isinstance(module_type.dependencies, tuple):
+            raise FastApiAdapterError("dependencies metadata must be an immutable tuple")
         setattr(module_type, _APPLICATION_SERVICE_EXPOSURE_ATTRIBUTE, exposure)
+        module_type.dependencies = (*module_type.dependencies, *target_modules)
         return module_type
 
     return decorate
 
 
 def _routers_for(module_type: type[AppModule]) -> tuple[APIRouter, ...]:
-    raw_metadata = vars(module_type).get(_ROUTER_METADATA_ATTRIBUTE, ())
-    if not isinstance(raw_metadata, tuple) or any(
-        not isinstance(router, APIRouter) for router in raw_metadata
+    raw_metadata = vars(module_type).get(_ROUTER_METADATA_ATTRIBUTE)
+    if raw_metadata is None:
+        return ()
+    if not isinstance(raw_metadata, _RouterDeclarations) or any(
+        not isinstance(router, APIRouter) for router in raw_metadata.routers
     ):
         raise FastApiAdapterError(
             f"{module_type.__module__}:{module_type.__qualname__} router metadata "
             "must remain an immutable tuple of APIRouter instances"
         )
-    return raw_metadata
+    return raw_metadata.routers
 
 
 def _application_service_exposure_for(

python_ddd_framework/fastapi/health.py

@@ -20,7 +20,7 @@ def _create_health_router(application: Application) -> APIRouter:
         return JSONResponse(status_code=200, content={"status": "live"})
 
     async def ready() -> JSONResponse:
-        is_ready = application.readiness.ready
+        is_ready = application.is_ready
         return JSONResponse(
             status_code=200 if is_ready else 503,
             content={"status": "ready" if is_ready else "not_ready"},

python_ddd_framework/fastapi/module.py

@@ -0,0 +1,14 @@
+"""HTTP 调用能力与原生 FastAPI DI 集成的组装 owner。"""
+
+from dishka.integrations.fastapi import FastapiProvider
+
+from ..application_services.module import ApplicationServicesModule
+from ..lifecycle import ConfigureContext
+from ..modularity import AppModule
+
+
+class FastApiModule(AppModule):
+    dependencies = (ApplicationServicesModule,)
+
+    def configure(self, context: ConfigureContext) -> None:
+        context.services.contribute(FastapiProvider(), reason="Native FastAPI request context")

python_ddd_framework/fastapi/parameters.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import inspect
-from typing import Annotated, Any, cast, get_args, get_origin
+from typing import Annotated, cast, get_args, get_origin
 
 from dishka.integrations.base import default_parse_dependency
 from fastapi.dependencies.models import Dependant
@@ -13,23 +13,8 @@ from pydantic import ConfigDict, Field, TypeAdapter, ValidationError
 from pydantic.fields import FieldInfo
 from pydantic_core import CoreSchema, SchemaValidator
 
-from ..application_services.execution import _InvocationArguments
-
-
-def _revalidation_schema(value: Any) -> Any:
-    # 只复制 schema 的容器，不复制模型 class、validator 或默认业务对象。
-    # 显式覆盖每个嵌套模型/数据类，不能改变业务模型的全局配置。
-    if isinstance(value, dict):
-        result = {
-            key: item if key in ("default", "metadata", "config") else _revalidation_schema(item)
-            for key, item in value.items()
-        }
-        if result.get("type") in ("model", "dataclass"):
-            result["revalidate_instances"] = "always"
-        return result
-    if isinstance(value, list):
-        return [_revalidation_schema(item) for item in value]
-    return value
+from ..invocation.execution import _InvocationArguments
+from ..validation.models import _revalidation_schema
 
 
 class _HttpParameterValidator:

python_ddd_framework/fastapi/realtime/connection.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import json
-from collections.abc import Awaitable, Callable, Mapping
+from collections.abc import Awaitable, Callable
 from enum import IntEnum
 from typing import TYPE_CHECKING, Concatenate, ParamSpec, TypeVar, cast
 from uuid import UUID
@@ -19,18 +19,23 @@ from ...application_services import (
 from ...application_services.invocation import _ScopedApplicationServiceInvoker
 from ...authorization import CurrentUser, PermissionDeniedError, UnauthenticatedError
 from ...errors import FrameworkError, ResourceConflictError, ResourceNotFoundError
-from ...realtime import RealtimeDeliveryReport
+from ...realtime import RealtimeDeliveryReport, RealtimeMessage
 
 if TYPE_CHECKING:
     from .runtime import _ConnectionState, _FastApiRealtimeRuntime
 
-_FRAMEWORK_PROBLEM_MESSAGE_TYPE = "framework.problem.v1"
 _TModel = TypeVar("_TModel", bound=BaseModel)
 _TContract = TypeVar("_TContract", bound=ApplicationServiceContract)
 _P = ParamSpec("_P")
 _R = TypeVar("_R")
 
 
+class _FrameworkProblemMessage(RealtimeMessage):
+    message_type = "framework.problem.v1"
+    code: str
+    status: int
+
+
 class _WebSocketCloseCode(IntEnum):
     NORMAL = 1000
     UNSUPPORTED_FRAME = 1003
@@ -136,13 +141,11 @@ class WebSocketConnection:
 
     async def send(
         self,
-        message_type: str,
-        payload: Mapping[str, object],
+        message: RealtimeMessage,
     ) -> RealtimeDeliveryReport:
         return await self._runtime.send_to_connection(
             self.id,
-            message_type=message_type,
-            payload=payload,
+            message,
         )
 
     async def send_problem(self, error: FrameworkError) -> RealtimeDeliveryReport:

python_ddd_framework/fastapi/realtime/module.py

@@ -7,11 +7,14 @@ from dishka import Provider, Scope
 from ...lifecycle import ConfigureContext, InitializeContext, ShutdownContext
 from ...modularity import AppModule
 from ...realtime import RealtimePublisher
+from ..module import FastApiModule
 from .options import FastApiRealtimeOptions
 from .runtime import _FastApiRealtimeRuntime, _realtime_publisher
 
 
 class FastApiRealtimeModule(AppModule):
+    dependencies = (FastApiModule,)
+
     def __init__(self) -> None:
         self._runtime: _FastApiRealtimeRuntime | None = None