让异常成为接口的一部分:Python 服务的结构化错误边界

举报
yd_215017870 发表于 2026/11/13 17:55:26 2026/11/13
【摘要】 在一个小型 Python 服务里,异常处理很容易从“把错误记到日志里”开始,最后却变成几层互相覆盖的 try/except。调用方收到 500,却不知道是参数不合法、资源不存在,还是服务暂时不可用;日志里又只有一行“request failed”,排查时只能重新猜测现场。更稳妥的做法不是让每个函数都捕获所有异常,而是把错误当作接口的一部分来设计:底层负责保留原因,中间层负责把原因映射到稳定的...

在一个小型 Python 服务里,异常处理很容易从“把错误记到日志里”开始,最后却变成几层互相覆盖的 try/except。调用方收到 500,却不知道是参数不合法、资源不存在,还是服务暂时不可用;日志里又只有一行“request failed”,排查时只能重新猜测现场。

更稳妥的做法不是让每个函数都捕获所有异常,而是把错误当作接口的一部分来设计:底层负责保留原因,中间层负责把原因映射到稳定的业务分类,边界层负责生成对外安全的响应,同时给日志附上可关联的上下文。这样,错误处理不会遮住真正的问题,也不会把内部堆栈泄露给调用方。

本文用 Python 标准库展示一套受限的错误边界。示例只讨论 HTTP 服务中的设计方法,不连接数据库、不调用云服务,也不声称已经在某个生产环境验证过。

一、先区分三种信息

同一个失败事件通常同时包含三种信息:

  1. 对用户有用的信息:例如“请求体不是合法 JSON”或“订单不存在”。
  2. 对运维有用的信息:例如底层超时、上游响应码和异常链。
  3. 对攻击者不应暴露的信息:文件路径、SQL 片段、访问令牌和完整堆栈。

如果直接把异常文本放进响应,三种信息就被混在一起了。一个文件找不到的异常可能带出服务器目录;一个数据库异常可能暴露表名;一个第三方 SDK 的错误文本可能包含请求参数。

因此,边界层应该使用“错误类型到公开错误码”的白名单映射,而不是把异常文本当作 API 合同。公开错误码需要稳定,内部原因可以变化。

二、用有限的错误类型表达业务语义

先定义服务边界真正关心的类别。不要一开始就为每个函数创建一个异常类;类型过多会让调用方必须了解内部实现。下面的四类足以覆盖这个示例:

from dataclasses import dataclass
from typing import Any


@dataclass
class ServiceError(Exception):
    code: str
    message: str
    status: int = 400
    details: dict[str, Any] | None = None


class ResourceMissing(ServiceError):
    def __init__(self, resource: str) -> None:
        super().__init__(
            code="resource_not_found",
            message=f"{resource} 不存在",
            status=404,
        )


class InvalidInput(ServiceError):
    def __init__(self, message: str, details: dict[str, Any] | None = None) -> None:
        super().__init__(
            code="invalid_input",
            message=message,
            status=400,
            details=details,
        )


class DependencyUnavailable(ServiceError):
    def __init__(self) -> None:
        super().__init__(
            code="dependency_unavailable",
            message="依赖服务暂时不可用",
            status=503,
        )

这里的 message 是面向调用方的短句,不是底层异常的替身。底层异常应通过异常链保留:

try:
    value = dependency.fetch(key)
except TimeoutError as exc:
    raise DependencyUnavailable() from exc

使用 raise … from exc 有两个好处:日志处理器仍能看到根因,边界响应却只使用 DependencyUnavailable 的安全字段。不要为了“看起来干净”而抹掉诊断信息。

三、把输入校验放在边界附近

输入校验越晚发生,错误越容易被误认为内部故障。解析请求体、检查字段类型和验证范围,应尽可能在进入业务函数前完成。业务函数因此可以接收更明确的类型,而不是一边执行一边猜测输入。

下面的解析函数故意只接受一个对象,并且只检查本示例真正使用的字段:

import json
from collections.abc import Mapping


def parse_create_request(raw: bytes) -> dict[str, str]:
    try:
        payload = json.loads(raw)
    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
        raise InvalidInput("请求体不是合法 JSON") from exc

    if not isinstance(payload, Mapping):
        raise InvalidInput("请求体必须是 JSON 对象")

    name = payload.get("name")
    if not isinstance(name, str) or not name.strip():
        raise InvalidInput(
            "name 必须是非空字符串",
            details={"field": "name"},
        )

    return {"name": name.strip()}

返回的 details 也要经过设计。它可以指出哪个字段需要修改,但不应回显完整输入,更不能包含密码、令牌或未经筛选的对象表示。对于批量接口,还应限制错误明细数量,避免一个超大请求生成超大的错误响应。

四、在唯一边界统一响应格式

如果每个路由各自拼响应,格式迟早会分裂。可以让一个边界处理器只做四件事:识别公开错误、选择状态码、记录上下文、返回统一结构。

import logging
import uuid

logger = logging.getLogger(__name__)


def error_response(exc: Exception, request_id: str | None = None) -> tuple[dict, int]:
    rid = request_id or str(uuid.uuid4())

    if isinstance(exc, ServiceError):
        logger.info(
            "request rejected",
            extra={"request_id": rid, "error_code": exc.code},
        )
        body = {
            "error": {
                "code": exc.code,
                "message": exc.message,
                "request_id": rid,
            }
        }
        if exc.details:
            body["error"]["details"] = exc.details
        return body, exc.status

    logger.exception("unexpected request failure", extra={"request_id": rid})
    return {
        "error": {
            "code": "internal_error",
            "message": "服务暂时无法处理请求",
            "request_id": rid,
        }
    }, 500

生产框架的适配层可以把这个函数接到异常中间件或错误处理钩子上。关键点不在于具体框架,而在于:未知异常统一返回安全的 500;日志保留堆栈;响应带有可供支持人员查询的 request_id。

request_id 不是秘密,也不应该被当作认证凭据。它的作用是把一次请求的入口日志、依赖调用和最终响应关联起来。若服务跨多个进程,还应在调用下游时传递同一个关联标识,并限制其长度和字符集。

五、不要把“可重试”混进错误类型

“发生了什么”和“下一步能不能重试”是两个维度。资源不存在通常不应重试,但依赖服务超时可能可以重试;然而,即使是超时,写操作也要先确认是否已经在下游生效。

可以在内部元数据里保存重试建议,但不要仅凭 HTTP 500 就让所有客户端无限重试:

from dataclasses import dataclass


@dataclass(frozen=True)
class FailurePolicy:
    retryable: bool
    max_attempts: int


POLICIES = {
    "dependency_unavailable": FailurePolicy(True, 2),
    "resource_not_found": FailurePolicy(False, 0),
    "invalid_input": FailurePolicy(False, 0),
    "internal_error": FailurePolicy(False, 0),
}

重试策略还需要考虑退避、幂等键、请求预算和服务端负载。错误分类只是输入,不是自动重试的充分条件。尤其是创建、扣款和发送通知这类操作,必须把幂等语义单独设计,不能因为错误码叫“暂时不可用”就重复执行副作用。

六、测试错误边界,而不只测试成功路径

错误处理的测试应检查对外合同,而不是把内部堆栈写死。可以为每类已知错误验证三件事:状态码稳定、公开错误码正确、响应不包含敏感内部文本。

def test_missing_resource_is_safe():
    body, status = error_response(ResourceMissing("项目"), "req-123")

    assert status == 404
    assert body["error"]["code"] == "resource_not_found"
    assert body["error"]["request_id"] == "req-123"
    assert "Traceback" not in str(body)


def test_unknown_error_hides_details():
    body, status = error_response(
        RuntimeError("/srv/app/private-config.toml"), "req-456"
    )

    assert status == 500
    assert body["error"]["code"] == "internal_error"
    assert "private-config.toml" not in str(body)

还应测试边界本身的失败:错误对象缺少可序列化的 details、日志格式化失败、请求标识为空或过长等。不能让“处理异常的代码”再抛出一个未处理异常。

测试时不必断言日志的全部自然语言内容。更有价值的是检查结构化字段,例如 request_id 和 error_code 是否存在。这样既能约束可观测性,也不会让日志措辞成为不必要的兼容负担。

七、逐步落地的检查清单

如果已有服务的异常处理比较混乱,可以按下面的顺序改造,而不是一次性重写所有路由:

  1. 先盘点当前对外返回的错误格式和状态码,列出必须兼容的字段。
  2. 选择少量稳定的公开错误码,并为旧响应建立迁移映射。
  3. 在入口处统一生成或接收 request_id,先改善日志关联能力。
  4. 把输入解析和校验从业务函数前移,去掉重复的底层参数检查。
  5. 为已知业务失败建立异常链,保留根因但不回显根因。
  6. 增加未知异常的安全兜底和敏感信息回归测试。
  7. 最后再评估客户端重试、监控告警和错误预算,避免把响应格式改造误当成重试方案。

结语

结构化错误边界的目标不是让所有失败都变得“好看”,而是让失败在不同受众面前承担正确的职责:用户得到可行动的提示,调用方得到稳定的错误码,运维得到可关联的根因,服务内部信息不被意外暴露。

当错误类型、响应格式、日志字段和测试断言彼此对应时,异常处理就不再是散落在路由里的补丁,而会成为服务接口中可以持续演进的一部分。

【声明】本内容来自华为云开发者社区博主,不代表华为云及华为云开发者社区的观点和立场。转载时必须标注文章的来源(华为云社区)、文章链接、文章作者等基本信息,否则作者和本社区有权追究责任。如果您发现本社区中有涉嫌抄袭的内容,欢迎发送邮件进行举报,并提供相关证据,一经查实,本社区将立刻删除涉嫌侵权内容,举报邮箱: cloudbbs@huaweicloud.com
  • 点赞
  • 收藏
  • 关注作者

评论(0)

0/1000
抱歉,系统识别当前为高风险访问,暂不支持该操作

全部回复

上滑加载中

设置昵称

在此一键设置昵称,即可参与社区互动!

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。

*长度不超过10个汉字或20个英文字符,设置后3个月内不可修改。