API错误码生成引擎·专业版

输入 / 输出

输入：模块码、HTTP类别、错误消息、可选序号；输出：标准错误码字符串、解析结果、标准响应体、按模块清单。

使用示例

from error_code import ErrorCodeRegistry
reg = ErrorCodeRegistry()
code = reg.generate('USER', 404, '用户不存在')  # USER-404-001
body = reg.response_body(code, trace_id='t-1')

引擎代码：error_code.py

# -*- coding: utf-8 -*-
"""API 错误码设计与生成引擎：统一错误码结构 MODULE-HTTP-SEQ（如 USER-404-001）。

提供：标准类别注册表、错误码生成（自动序号、防重复）、反解析、标准响应体构造。
"""
import re

# 标准 HTTP 错误类别与默认语义
CATEGORY = {
    "400": "BAD_REQUEST",
    "401": "UNAUTHORIZED",
    "403": "FORBIDDEN",
    "404": "NOT_FOUND",
    "409": "CONFLICT",
    "422": "UNPROCESSABLE_ENTITY",
    "429": "TOO_MANY_REQUESTS",
    "500": "INTERNAL_ERROR",
    "503": "SERVICE_UNAVAILABLE",
}

_CODE_RE = re.compile(r"^([A-Z]{2,8})-(\d{3})-(\d{3})$")


class ErrorCodeRegistry:
    def __init__(self):
        self._codes = {}

    def generate(self, module, http_code, message, seq=None):
        module = module.upper().strip()
        if not re.match(r"^[A-Z]{2,8}$", module):
            raise ValueError("模块码需为 2-8 位大写字母")
        http_code = str(http_code)
        if http_code not in CATEGORY:
            raise ValueError(f"不支持的 HTTP 类别: {http_code}")
        if not message or not message.strip():
            raise ValueError("错误消息不能为空")
        if seq is None:
            used = [int(k.split("-")[2]) for k in self._codes
                    if k.startswith(f"{module}-{http_code}-")]
            seq = (max(used) + 1) if used else 1
        seq = int(seq)
        if not (1 <= seq <= 999):
            raise ValueError("序号需在 1-999")
        code = f"{module}-{http_code}-{seq:03d}"
        if code in self._codes:
            raise ValueError(f"错误码已存在: {code}")
        self._codes[code] = {
            "code": code,
            "module": module,
            "http": int(http_code),
            "category": CATEGORY[http_code],
            "message": message.strip(),
        }
        return code

    def parse(self, code):
        m = _CODE_RE.match(code)
        if not m:
            raise ValueError(f"错误码格式非法: {code}")
        return self._codes.get(code) or {
            "code": code, "module": m.group(1),
            "http": int(m.group(2)), "category": CATEGORY.get(m.group(2), "UNKNOWN"),
            "message": None,
        }

    def response_body(self, code, detail=None, trace_id=None):
        rec = self._codes[code]
        body = {"code": rec["code"], "message": rec["message"]}
        if detail is not None:
            body["detail"] = detail
        if trace_id is not None:
            body["trace_id"] = trace_id
        return body

    def list_codes(self, module=None):
        if module:
            module = module.upper()
            return [v for k, v in sorted(self._codes.items()) if v["module"] == module]
        return [v for _, v in sorted(self._codes.items())]

测试（6 正例 + 5 边界（test_error_code.py 实跑全过）：首个码自动001、同类别递增、跨模块独立编号、响应体构造、按模块列出、小写模块归一；重复码、非法模块、非法HTTP类别、空消息、序号越界、非法格式均报错。）

硬性规则

• 确定性输出：相同输入必得相同结果，时间/随机量通过参数注入；
• 非法输入（负数、越界、格式错误）一律抛 ValueError，不静默吞掉；
• 本引擎为算法/计算参考，集成到业务时请结合真实参数与压测，不替代专业判断。