excode 0.1.4

统一的异常与错误码管理包

excode

统一的异常与错误码管理Python包，提供标准化的异常类、错误码枚举以及错误处理工具函数。

安装

pip install excode

快速开始

from excode import ExCodeError, ErrorCode, raise_for_error

# 根据错误码自动抛出对应异常
try:
    raise_for_error(ErrorCode.AUTHENTICATION_ERROR)
except ExCodeError as e:
    print(e)  # [1002] 认证失败，API Key 无效或过期

错误码一览

错误码	枚举值	说明
0	ErrorCode.SUCCESS	成功
1000	ErrorCode.UNKNOWN_ERROR	未知错误
1001	ErrorCode.SERVICE_ERROR	服务错误
1002	ErrorCode.AUTHENTICATION_ERROR	认证失败,API Key 无效或过期
1003	ErrorCode.RATE_LIMIT	请求频率超限，请稍后重试
1004	ErrorCode.QUOTA_EXCEEDED	配额/余额不足
1005	ErrorCode.SERVICE_TIMEOUT	服务超时，请稍后重试
1006	ErrorCode.SERVICE_BUSY	服务繁忙，请稍后再试！
2001	ErrorCode.INVALID_PARAMS	请求参数无效
3001	ErrorCode.PROMPT_BANNED	提示词包含违禁内容
3002	ErrorCode.IMAGE_BANNED	图片包含违禁内容
3003	ErrorCode.CONTENT_POLICY_VIOLATION	您的请求包含违反平台政策的内容,请调整图像或提示词后重试
4001	ErrorCode.INVALID_IMAGE	图片无效或损坏
4002	ErrorCode.IMAGE_GENERATE_FAIL	图片生成失败，请稍后重试
4003	ErrorCode.NO_IMAGE_RESULT	模型未返回图片结果,请调整图像或提示词后重试

异常类层级

所有异常均继承自 ExCodeError，可通过 except ExCodeError 统一捕获。

ExCodeError
├── ServiceError                # 通用服务错误
├── AuthenticationError         # 认证失败
├── RateLimitError              # 请求频率超限
├── QuotaExceededError          # 配额/余额不足
├── ServiceTimeoutError         # 服务超时
├── ServiceBusyError            # 服务繁忙
├── InvalidParamsError          # 请求参数无效
├── PromptBanError              # 提示词违禁
├── ImageBanError               # 图片违禁
├── ContentPolicyViolationError # 违反平台政策
├── InvalidImageError           # 图片无效或损坏
├── ImageGenerateFailError      # 图片生成失败
└── NoImageResultError          # 模型未返回图片结果

使用方式

1. 直接抛出异常

from excode import AuthenticationError

raise AuthenticationError("API Key 已过期", extra_data={"key_id": "abc123"})
# 输出: [1002] API Key 已过期 [{'key_id': 'abc123'}]

2. 根据错误码抛出（工厂函数）

from excode import ErrorCode, raise_for_error

# 使用默认描述
raise_for_error(ErrorCode.RATE_LIMIT)
# 输出: [1003] 请求频率超限，请稍后重试

# 使用自定义描述
raise_for_error(ErrorCode.RATE_LIMIT, error_msg="当前接口调用次数已达上限")
# 输出: [1003] 当前接口调用次数已达上限

3. 统一捕获并处理

from excode import ExCodeError, ErrorCode, raise_for_error

try:
    raise_for_error(ErrorCode.QUOTA_EXCEEDED)
except ExCodeError as e:
    print(e.error_code)       # ErrorCode.QUOTA_EXCEEDED
    print(e.error_code.value) # 1004
    print(e.error_msg)        # 配额/余额不足
    print(e.extra_data)       # {}

4. 分类捕获

from excode import AuthenticationError, RateLimitError, ExCodeError

try:
    # 业务逻辑
    ...
except AuthenticationError as e:
    # 处理认证失败
    refresh_api_key()
except RateLimitError as e:
    # 处理限流
    wait_and_retry()
except ExCodeError as e:
    # 兜底处理其他 excode 异常
    log_error(e)

5. 携带额外上下文

from excode import InvalidParamsError

raise InvalidParamsError(
    "参数校验失败",
    extra_data={"field": "width", "value": -1, "reason": "必须为正整数"}
)
# 输出: [2001] 参数校验失败 [{'field': 'width', 'value': -1, 'reason': '必须为正整数'}]

6. 特殊异常的扩展属性

from excode import PromptBanError, InvalidImageError

# PromptBanError 携带命中的违禁词列表
raise PromptBanError("提示词违禁", data=["暴力", "色情"])

# InvalidImageError 携带图片尺寸和原始异常
raise InvalidImageError("图片无法解码", image_size=2048, original_error=decode_err)

7. 获取错误码描述

from excode import ErrorCode, get_error_message

msg = get_error_message(ErrorCode.SERVICE_TIMEOUT)
print(msg)  # 服务超时，请稍后重试

8. 注册自定义错误码映射

from enum import IntEnum
from excode import ExCodeError, ErrorCode, raise_for_error, register_error_code

# 定义自定义异常
class NetworkError(ExCodeError):
    error_code = ErrorCode.UNKNOWN_ERROR  # 可复用或自行扩展

# 注册映射
register_error_code(ErrorCode.SERVICE_ERROR, NetworkError)

# 之后 raise_for_error 会使用你注册的异常类
raise_for_error(ErrorCode.SERVICE_ERROR, error_msg="网络连接失败")

9. 自定义错误码（CustomErrorCode）

当内置 ErrorCode 枚举无法满足需求时，可使用 CustomErrorCode 定义字符串类型的错误码：

from excode import CustomErrorCode, ServiceResult, raise_for_error

# 直接创建
MY_ERROR = CustomErrorCode("MY_ERROR", "自定义错误消息")

# 用于 ServiceResult
result = ServiceResult.fail(MY_ERROR)
print(result.code)  # CustomErrorCode('MY_ERROR', '自定义错误消息')
print(result.msg)   # 自定义错误消息

# 用于 raise_for_error（将抛出 ExCodeError）
raise_for_error(MY_ERROR)

10. 错误码注册表（ErrorCodeRegistry）

提供全局注册和查找自定义错误码的能力：

from excode import ErrorCodeRegistry

# 注册自定义错误码
MY_ERROR = ErrorCodeRegistry.register("MY_ERROR", "自定义错误消息")

# 查找已注册的错误码
found = ErrorCodeRegistry.get("MY_ERROR")
print(found)  # CustomErrorCode('MY_ERROR', '自定义错误消息')

# 列出所有已注册的错误码
all_codes = ErrorCodeRegistry.list_all()

# 清空注册表（主要用于测试）
ErrorCodeRegistry.clear()

11. 服务结果封装（ServiceResult）

使用 ServiceResult 以返回值代替异常，统一表示成功或失败：

from excode import ServiceResult, ErrorCode, CustomErrorCode

# 成功
result = ServiceResult.success(data={"id": 1, "name": "test"})
print(result.is_success)  # True
print(result.data)        # {'id': 1, 'name': 'test'}

# 失败 - 使用内置错误码
result = ServiceResult.fail(ErrorCode.AUTHENTICATION_ERROR)
print(result.is_success)  # False
print(result.code)        # ErrorCode.AUTHENTICATION_ERROR
print(result.msg)         # 认证失败,API Key 无效或过期

# 失败 - 使用自定义错误码
my_error = CustomErrorCode("BIZ_ERROR", "业务错误")
result = ServiceResult.fail(my_error)
print(result.code)  # CustomErrorCode('BIZ_ERROR', '业务错误')

# 布尔判断
if result:
    print("成功")
else:
    print("失败")

# 转为字典
d = result.to_dict()
# {'is_success': False, 'code': 'BIZ_ERROR', 'msg': '业务错误', 'data': None}

# 从异常创建
try:
    ...
except Exception as e:
    result = ServiceResult.from_exception(e)