Rust / 系统课时

服务接口如何映射领域错误

服务接口如何映射领域错误

服务层中的领域错误描述业务事实,HTTP 状态码描述传输协议结果,两者不应直接耦合。本节把映射集中在接口边界,让领域模型保持纯净,同时为客户端提供稳定、可演进的错误状态和错误码。

学习目标

  • 区分领域错误、应用错误与 HTTP 响应的职责
  • 在传输边界把业务失败映射为稳定状态码和错误码
  • 避免把数据库、堆栈或内部类型名称直接暴露给客户端

领域错误不应该知道 HTTP

像“订单不存在”“订单状态不允许取消”“库存不足”都属于业务语义。领域层只需要表达这些失败,不需要知道它们最终通过 HTTP、消息队列还是命令行返回。

如果直接在领域对象里写 404、409,领域代码就会被某一种传输协议绑住。更稳妥的做法是:领域层返回自己的错误类型,接口适配层再决定 HTTP 状态、公开错误码和用户可见消息。

在接口边界集中映射

下面的完整 Rust 程序模拟一个服务边界。DomainError 只描述业务失败;ServiceError 还能承载基础设施失败;to_http 是唯一负责生成 HTTP 语义的地方。

rust
#[derive(Debug)]
enum DomainError {
    OrderNotFound,
    InvalidOrderState,
    InsufficientStock,
}

#[derive(Debug)]
enum ServiceError {
    Domain(DomainError),
    Storage(String),
}

struct HttpResponse {
    status: u16,
    code: &'static str,
    message: &'static str,
}

fn to_http(error: &ServiceError) -> HttpResponse {
    match error {
        ServiceError::Domain(DomainError::OrderNotFound) => HttpResponse {
            status: 404,
            code: "ORDER_NOT_FOUND",
            message: "order does not exist",
        },
        ServiceError::Domain(DomainError::InvalidOrderState) => HttpResponse {
            status: 409,
            code: "ORDER_STATE_CONFLICT",
            message: "order state does not allow this operation",
        },
        ServiceError::Domain(DomainError::InsufficientStock) => HttpResponse {
            status: 422,
            code: "INSUFFICIENT_STOCK",
            message: "stock is insufficient",
        },
        ServiceError::Storage(_) => HttpResponse {
            // 基础设施细节只记录在服务端,对外统一成稳定的 500 响应。
            status: 500,
            code: "INTERNAL_ERROR",
            message: "internal server error",
        },
    }
}

fn simulate_request(case: &str) -> Result<(), ServiceError> {
    match case {
        "missing" => Err(ServiceError::Domain(DomainError::OrderNotFound)),
        "state" => Err(ServiceError::Domain(DomainError::InvalidOrderState)),
        "stock" => Err(ServiceError::Domain(DomainError::InsufficientStock)),
        "db" => Err(ServiceError::Storage("connection refused".to_string())),
        _ => Ok(()),
    }
}

fn main() {
    for case in ["ok", "missing", "state", "stock", "db"] {
        match simulate_request(case) {
            Ok(()) => println!("{case} -> 204"),
            Err(error) => {
                if let ServiceError::Storage(detail) = &error {
                    eprintln!("internal storage error: {detail}");
                }

                let response = to_http(&error);
                println!(
                    "{case} -> {} {}: {}",
                    response.status, response.code, response.message
                );
            }
        }
    }
}

预期结果

text
程序会把三种领域失败分别映射为 404、409、422;存储故障只在服务端 stderr 保留细节,对客户端映射为通用 500。

保存为 main.rs 后运行:

bash
rustc main.rs -o error-map
./error-map

预期输出

text
ok -> 204
missing -> 404 ORDER_NOT_FOUND: order does not exist
state -> 409 ORDER_STATE_CONFLICT: order state does not allow this operation
stock -> 422 INSUFFICIENT_STOCK: stock is insufficient
internal storage error: connection refused
db -> 500 INTERNAL_ERROR: internal server error

终端合并显示 stdout 与 stderr 时,内部日志那一行的位置可能与其他行略有不同;状态码与公开错误码的映射应保持不变。

状态码表达协议语义,错误码表达业务语义

常见映射可以先按客户端能否修正请求来设计,而不是机械地“一种 Rust 枚举对应一个状态码”。

失败 推荐接口语义 原因
资源不存在 404 Not Found 客户端引用的目标不存在
当前状态冲突 409 Conflict 请求本身可理解,但与当前资源状态冲突
业务校验失败 422 Unprocessable Content 结构合法,但业务条件无法满足
未知内部故障 500 Internal Server Error 服务端无法完成请求,且不应泄露内部原因

HTTP 状态码用于通用协议判断,ORDER_STATE_CONFLICT 这类公开错误码用于客户端做更细的业务分支。公开错误码一旦进入客户端逻辑,也应视为兼容性接口,而不是随内部枚举名称一起改动。

不要把内部错误直接序列化出去

最危险的做法是对任意错误直接调用调试格式,然后原样塞进响应。数据库地址、SQL、文件路径、第三方响应甚至凭据片段,都可能因此泄露。

服务端日志可以保留关联 ID 和内部错误链,客户端响应则只返回稳定字段,例如 code、message 和可选的 request_id。如果需要调试,应通过日志系统用 request_id 反查,而不是扩大公开响应内容。

测试契约而不是实现细节

接口测试应断言“给定业务失败会得到哪个状态码和公开错误码”,而不是断言内部枚举的调试字符串。这样重构 Repository、数据库驱动或错误封装方式时,只要外部契约没有变化,客户端就不需要跟着修改。

当领域错误新增或拆分时,也应先判断客户端是否真的需要感知新的类别。需要时新增稳定公开错误码;不需要时仍可归入现有接口语义,避免把内部模型的每次演进都扩散到 API。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

服务接口如何映射领域错误

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通