96 lines
3.0 KiB
Python
96 lines
3.0 KiB
Python
"""事务基础设施异常。
|
||
|
||
定义事务控制链路的稳定错误码与异常类型，全部继承自
|
||
``yuxi.channels.contract.errors.base.Error``，复用 UnifiedError 协议
|
||
（``status_code`` / ``error_code`` / ``message`` / ``details`` / ``trace_id``），
|
||
不重新实现协议字段。
|
||
|
||
错误码：
|
||
- ``TX_BEGIN_ERROR``：事务开启失败
|
||
- ``TX_COMMIT_ERROR``：事务提交失败
|
||
- ``TX_ROLLBACK_ERROR``：事务回滚失败
|
||
- ``TX_INACTIVE_ERROR``：事务已关闭时操作
|
||
|
||
HTTP 状态码：四个错误码均未注册到 ``CHANNEL_ERROR_STATUS_MAP``，基类
|
||
``Error.status_code`` 查表未命中时返回 500。
|
||
|
||
诊断字段：每个异常携带 ``transaction_id`` 与 ``session_state``，通过覆写
|
||
``to_dict()`` 纳入序列化结果；基类 ``details`` property 从 ``to_dict()``
|
||
提取（排除 ``error_code`` / ``message`` / ``trace_id``），因此这两个字段
|
||
自动进入 ``details``。
|
||
"""
|
||
|
||
from __future__ import annotations
|
||
|
||
from typing import Any
|
||
|
||
from yuxi.channels.contract.errors.base import Error
|
||
|
||
|
||
class _TransactionError(Error):
|
||
"""事务异常内部基类。
|
||
|
||
为四个事务异常提供共享的 ``transaction_id`` / ``session_state`` 诊断字段，
|
||
覆写 ``to_dict()`` 将其纳入序列化结果。不直接实例化，由具体子类继承，
|
||
复用 ``Error`` 已实现的 UnifiedError 协议（``status_code`` / ``details``）。
|
||
"""
|
||
|
||
def __init__(
|
||
self,
|
||
message: str,
|
||
*,
|
||
transaction_id: str = "",
|
||
session_state: str = "",
|
||
trace_id: str | None = None,
|
||
) -> None:
|
||
super().__init__(message, trace_id=trace_id)
|
||
self.transaction_id = transaction_id
|
||
self.session_state = session_state
|
||
|
||
def to_dict(self) -> dict[str, Any]:
|
||
"""序列化为字典，在基础字段外补充事务诊断字段。"""
|
||
base = super().to_dict()
|
||
base["transaction_id"] = self.transaction_id
|
||
base["session_state"] = self.session_state
|
||
return base
|
||
|
||
|
||
class TransactionBeginError(_TransactionError):
|
||
"""事务开启失败。
|
||
|
||
在 ``TransactionContext.__aenter__`` 中 ``session.begin()`` 抛错时抛出，
|
||
``error_code`` 为 ``TX_BEGIN_ERROR``。
|
||
"""
|
||
|
||
error_code = "TX_BEGIN_ERROR"
|
||
|
||
|
||
class TransactionCommitError(_TransactionError):
|
||
"""事务提交失败。
|
||
|
||
在 ``commit()`` 或 ``__aexit__`` 提交阶段抛错时抛出，
|
||
``error_code`` 为 ``TX_COMMIT_ERROR``。
|
||
"""
|
||
|
||
error_code = "TX_COMMIT_ERROR"
|
||
|
||
|
||
class TransactionRollbackError(_TransactionError):
|
||
"""事务回滚失败。
|
||
|
||
在 ``rollback()`` 或 ``__aexit__`` 回滚阶段抛错时抛出，
|
||
``error_code`` 为 ``TX_ROLLBACK_ERROR``。
|
||
"""
|
||
|
||
error_code = "TX_ROLLBACK_ERROR"
|
||
|
||
|
||
class TransactionInactiveError(_TransactionError):
|
||
"""事务已关闭时操作。
|
||
|
||
在事务已提交/回滚后再次执行需要活动事务的操作时抛出，
|
||
``error_code`` 为 ``TX_INACTIVE_ERROR``。
|
||
"""
|
||
|
||
error_code = "TX_INACTIVE_ERROR"
|