Kris
00092c818e
本次提交包含多项代码优化与规范修正： 1. 文档与注释优化：修正注释术语、补充注解与FR编号 2. 代码格式调整：统一空格、换行与缩进规范 3. 类型与接口完善：补充__all__导出、修正返回类型注解 4. 错误处理增强：新增领域错误类与校验逻辑 5. 依赖与导入调整：修复路径引用、统一时区导入 6. 协议与契约更新：完善接口文档与一致性注解
79 lines
2.7 KiB
Python
79 lines
2.7 KiB
Python
"""生命周期 DTO。
|
||
|
||
定义插件生命周期端口的命令与结果值对象，包括生命周期命令与生命周期结果。
|
||
所有 DTO 均为 ``dataclass(frozen=True)``，仅依赖标准库，用于插件的加载、
|
||
启动、暂停、恢复、停止、卸载、重载等生命周期操作的命令传递与结果返回。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from dataclasses import dataclass
|
||
from typing import Any, Literal
|
||
|
||
from yuxi.channels.contract.errors import ValidationError
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class LifecycleCmd:
|
||
"""生命周期命令（PLG-001）。
|
||
|
||
由生命周期端口方法引用，描述一次插件生命周期操作请求，携带事件类型、
|
||
插件 ID 与操作参数。事件类型覆盖 load / start / pause / resume / stop /
|
||
unload / reload 等场景。
|
||
|
||
字段：
|
||
event: 生命周期事件（load | start | pause | resume | stop | unload | reload）。
|
||
plugin_id: 插件 ID。
|
||
params: 操作参数（可选）。
|
||
"""
|
||
|
||
event: Literal["load", "start", "pause", "resume", "stop", "unload", "reload"]
|
||
plugin_id: str
|
||
params: dict[str, Any] | None = None
|
||
|
||
def __post_init__(self) -> None:
|
||
"""校验必填字段非空与事件取值。
|
||
|
||
``plugin_id`` 必须非空，``event`` 必须为 ``load`` / ``start`` /
|
||
``pause`` / ``resume`` / ``stop`` / ``unload`` / ``reload`` 之一，
|
||
在构造时即抛出 ``ValidationError``，adapter 不再做该校验（INV-8）。
|
||
"""
|
||
if not self.plugin_id:
|
||
raise ValidationError("plugin_id", "must not be empty")
|
||
if self.event not in (
|
||
"load",
|
||
"start",
|
||
"pause",
|
||
"resume",
|
||
"stop",
|
||
"unload",
|
||
"reload",
|
||
):
|
||
raise ValidationError(
|
||
"event",
|
||
"must be one of: load, start, pause, resume, stop, unload, reload",
|
||
)
|
||
|
||
|
||
@dataclass(frozen=True)
|
||
class LifecycleResult:
|
||
"""生命周期结果（PLG-001）。
|
||
|
||
描述插件生命周期操作的执行结果，携带状态与错误信息，用于结果汇报与
|
||
异常归因。状态覆盖 discovered / resolved / loaded / initialized / started /
|
||
paused / stopped / unloaded / failed 等场景。
|
||
|
||
字段：
|
||
state: 生命周期状态。
|
||
error: 错误信息（可选）。
|
||
error_code: 错误码（用例服务捕获异常时填充，默认空字符串）。
|
||
trace_id: 追踪 ID（用例服务捕获异常时填充，默认空字符串）。
|
||
"""
|
||
|
||
state: Literal[
|
||
"discovered", "resolved", "loaded", "initialized", "started", "paused", "stopped", "unloaded", "failed"
|
||
]
|
||
error: str | None = None
|
||
error_code: str = ""
|
||
trace_id: str = ""
|