Rust / 系统课时
服务接口如何映射领域错误
服务接口如何映射领域错误
服务层中的领域错误描述业务事实,HTTP 状态码描述传输协议结果,两者不应直接耦合。本节把映射集中在接口边界,让领域模型保持纯净,同时为客户端提供稳定、可演进的错误状态和错误码。
学习目标
- 区分领域错误、应用错误与 HTTP 响应的职责
- 在传输边界把业务失败映射为稳定状态码和错误码
- 避免把数据库、堆栈或内部类型名称直接暴露给客户端
领域错误不应该知道 HTTP
像“订单不存在”“订单状态不允许取消”“库存不足”都属于业务语义。领域层只需要表达这些失败,不需要知道它们最终通过 HTTP、消息队列还是命令行返回。
如果直接在领域对象里写 404、409,领域代码就会被某一种传输协议绑住。更稳妥的做法是:领域层返回自己的错误类型,接口适配层再决定 HTTP 状态、公开错误码和用户可见消息。
在接口边界集中映射
下面的完整 Rust 程序模拟一个服务边界。DomainError 只描述业务失败;ServiceError 还能承载基础设施失败;to_http 是唯一负责生成 HTTP 语义的地方。
#[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
);
}
}
}
}预期结果
程序会把三种领域失败分别映射为 404、409、422;存储故障只在服务端 stderr 保留细节,对客户端映射为通用 500。保存为 main.rs 后运行:
rustc main.rs -o error-map
./error-map预期输出
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。