Kris
00092c818e
本次提交包含多项代码优化与规范修正： 1. 文档与注释优化：修正注释术语、补充注解与FR编号 2. 代码格式调整：统一空格、换行与缩进规范 3. 类型与接口完善：补充__all__导出、修正返回类型注解 4. 错误处理增强：新增领域错误类与校验逻辑 5. 依赖与导入调整：修复路径引用、统一时区导入 6. 协议与契约更新：完善接口文档与一致性注解
189 lines
6.7 KiB
Python
189 lines
6.7 KiB
Python
"""扩展点协议。
|
||
|
||
定义扩展点相关的枚举、不可变值对象与 Stage Protocol，包括冲突策略、
|
||
失败策略、阶段槽位、事件订阅、配置源与管道阶段协议。
|
||
插件通过扩展点向宿主注入自身逻辑，宿主按优先级串联执行。
|
||
|
||
扩展点失败策略（§9.3）：每个扩展点必须声明 ``failure_policy`` 字段，
|
||
标识插件失败时的处理方式（降级 / 熔断 / 隔离），确保插件故障隔离性
|
||
（§9.5"插件失败不得拖垮宿主"）。
|
||
|
||
命名约定：
|
||
- ``FailureStrategy``（本模块）：**阶段执行**失败策略（TERMINATE /
|
||
SKIP / COMPENSATE / DEGRADE），由 ``Stage.failure`` 字段使用，
|
||
描述管道阶段执行失败时的处理方式。
|
||
- ``FailurePolicy``（manifest 模块）：**插件隔离**失败策略
|
||
（DEGRADE / CIRCUIT_BREAK / ISOLATE），由扩展点
|
||
``failure_policy`` 字段使用，描述插件故障时的隔离方式。
|
||
两者语义不同，字段与类型必须一致命名以避免混淆。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass
|
||
from enum import StrEnum
|
||
from typing import Any, Protocol, runtime_checkable
|
||
|
||
from yuxi.channels.contract.dtos.plugin import (
|
||
ConfigDecryptor,
|
||
ConfigLoader,
|
||
EventHandler,
|
||
)
|
||
from yuxi.channels.contract.plugin.manifest import FailurePolicy
|
||
|
||
|
||
class ConflictStrategy(StrEnum):
|
||
"""冲突策略。
|
||
|
||
标识同一锚点多个插件阶段的冲突解决方式。继承 ``str, Enum`` 以支持
|
||
JSON 序列化与字符串比较。
|
||
|
||
取值：
|
||
CHAIN: 链式调用（按优先级串联执行）。
|
||
REJECT: 拒绝（同操作 ID 冲突时拒绝装配）。
|
||
OVERRIDE: 覆盖（后注册者覆盖先注册者）。
|
||
"""
|
||
|
||
CHAIN = "chain"
|
||
REJECT = "reject"
|
||
OVERRIDE = "override"
|
||
|
||
|
||
class FailureStrategy(StrEnum):
|
||
"""阶段失败策略。
|
||
|
||
标识管道阶段执行失败时的处理方式。继承 ``str, Enum`` 以支持 JSON 序列化
|
||
与字符串比较。
|
||
|
||
取值：
|
||
TERMINATE: 终止管道。
|
||
SKIP: 跳过阶段。
|
||
COMPENSATE: 执行补偿。
|
||
DEGRADE: 降级。
|
||
"""
|
||
|
||
TERMINATE = "terminate"
|
||
SKIP = "skip"
|
||
COMPENSATE = "compensate"
|
||
DEGRADE = "degrade"
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class StageSlot:
|
||
"""阶段槽位。
|
||
|
||
描述插件向管道锚点注入的阶段槽位，包括管道名、锚点、阶段实例、优先级、
|
||
是否允许多个阶段共存、冲突策略与失败策略，用于扩展点装配。
|
||
|
||
字段：
|
||
pipeline: 管道名（inbound | outbound | control）。
|
||
anchor: 锚点（阶段名，如 before:route | after:security）。
|
||
stage: Stage Protocol 实例。
|
||
priority: 优先级（默认 100，越小越先执行）。
|
||
multi: 是否允许多个阶段插入同一锚点（默认 False）。
|
||
conflict_strategy: 冲突策略（默认 CHAIN）。
|
||
failure_policy: 插件隔离失败策略（默认 DEGRADE，插件失败时降级
|
||
跳过，不拖垮宿主 §9.5）。
|
||
"""
|
||
|
||
pipeline: str
|
||
anchor: str
|
||
stage: Stage
|
||
priority: int = 100
|
||
multi: bool = False
|
||
conflict_strategy: ConflictStrategy = ConflictStrategy.CHAIN
|
||
failure_policy: FailurePolicy = FailurePolicy.DEGRADE
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class EventSubscription:
|
||
"""事件订阅。
|
||
|
||
描述插件对领域事件的订阅，包括事件类型、处理器、优先级与失败策略，
|
||
用于事件总线分发注册。
|
||
|
||
字段：
|
||
event_type: 事件类型（PairingApproved | ConfigChanged | PluginFailed | ...）。
|
||
handler: 事件处理 Protocol 实例。
|
||
priority: 优先级（默认 100）。
|
||
failure_policy: 插件隔离失败策略（默认 DEGRADE，handler 失败时
|
||
跳过本次调用，不中断其他订阅者 §9.5）。
|
||
"""
|
||
|
||
event_type: str
|
||
handler: EventHandler
|
||
priority: int = 100
|
||
failure_policy: FailurePolicy = FailurePolicy.DEGRADE
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class ConfigSource:
|
||
"""配置源。
|
||
|
||
描述插件提供的配置源，包括源 ID、加载器、可选解密器与失败策略，用于
|
||
配置端口的多源加载。
|
||
|
||
字段：
|
||
source_id: 源 ID。
|
||
loader: 配置加载 Protocol 实例。
|
||
decryptor: 配置解密 Protocol 实例（可选）。
|
||
failure_policy: 插件隔离失败策略（默认 DEGRADE，加载失败时
|
||
跳过此源，回退至其他配置源 §9.5）。
|
||
"""
|
||
|
||
source_id: str
|
||
loader: ConfigLoader
|
||
decryptor: ConfigDecryptor | None = None
|
||
failure_policy: FailurePolicy = FailurePolicy.DEGRADE
|
||
|
||
|
||
@runtime_checkable
|
||
class Stage(Protocol):
|
||
"""管道阶段 Protocol。
|
||
|
||
由插件实现，描述管道阶段的元信息与处理方法。使用
|
||
``@runtime_checkable`` 装饰以支持 ``isinstance`` 检查。阶段处理为
|
||
异步方法，由管道按优先级串联调用。
|
||
|
||
与应用层 ``AppStage`` Protocol 对齐：
|
||
- ``compensate`` 为 ``str | None``，携带补偿阶段名称（如
|
||
"outbox-rollback"），None 表示无补偿；
|
||
- ``process`` 返回 ``bool``：True 表示成功，False 或抛出异常表示
|
||
失败。
|
||
|
||
优先级规则（§7.8）：
|
||
- 1~49：安全/合规相关阶段（必须最先执行），如 DM 安全检查、审计前置。
|
||
- 50~99：业务增强阶段（在核心阶段之前增强上下文），如渠道路由增强、
|
||
身份预解析。
|
||
- 100：默认优先级，大多数插件阶段。
|
||
- 101~200：业务后处理阶段（在核心阶段之后处理），如消息格式化增强、
|
||
指标采集。
|
||
- 201+：可观测性/诊断阶段（必须最后执行），如追踪收尾、诊断快照。
|
||
|
||
冲突解决：
|
||
- 同一锚点、相同优先级的多个插件阶段 **必须** 拒绝装配，并报告冲突详情。
|
||
- 插件 **不得** 使用 ``replace`` 锚点覆盖核心阶段，除非扩展点显式允许。
|
||
"""
|
||
|
||
id: str
|
||
reads: tuple[str, ...]
|
||
writes: tuple[str, ...]
|
||
idempotent: bool
|
||
thread_safe: bool
|
||
failure: FailureStrategy
|
||
compensate: str | None
|
||
|
||
async def process(self, context: Any) -> bool:
|
||
"""处理管道阶段。
|
||
|
||
参数：
|
||
context: 管道上下文。
|
||
|
||
返回：
|
||
True 表示成功，False 或抛出异常表示失败。
|
||
|
||
@consistency: 阶段处理（stage-processed），按 ``Stage.reads`` / ``Stage.writes`` 元信息读写管道上下文；失败时按 ``Stage.failure`` 策略处理。
|
||
@idempotent: 取决于 ``Stage.idempotent`` 字段声明，由阶段实现者明确标注。
|
||
"""
|
||
...
|