微服务中HTTP状态码应按异常性质分层映射：4xx表客户端可修正错误，5xx表服务端问题，业务语义由响应体code字段承载，前端须忽略状态码、只依据code做业务判断。
微服务中统一规范异常的 HTTP 状态码映射，核心不是“给每个错误配一个状态码”，而是建立分层映射规则：HTTP 状态码表达请求处理的协议层结果（客户端错？服务端临时不可用？还是彻底崩了？），而业务语义（如“库存不足”“用户被禁用”）必须由响应体中的 code 字段承载。状态码只负责告诉调用方“要不要重试”“该不该改请求”，不负责解释“为什么失败”。
按异常性质决定 HTTP 状态码，而非按业务场景硬编码
同一类业务错误，在不同上下文中可能对应不同状态码。比如“用户不存在”：
- 在
GET /users/123接口里，是资源未找到 → 映射为 404 NOT_FOUND - 在
POST /orders中校验收货人 ID 时发现不存在 → 属于参数非法 → 应映射为 400 BAD_REQUEST - 若因下游用户服务完全不可达导致查不到 → 是服务依赖故障 → 应返回 503 SERVICE_UNAVAILABLE 或 504 GATEWAY_TIMEOUT
三类异常的标准状态码映射策略
全局异常处理器（@RestControllerAdvice）应按以下优先级拦截和映射：
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
-
业务异常（如 BusinessException）：由业务逻辑主动抛出，携带明确 ErrorCode。状态码根据其语义动态选择 —— 不用
@ResponseStatus硬绑定，而是在@ExceptionHandler方法内调用response.setStatus(errorCode.getHttpStatus().value()) - Spring 校验异常（如 MethodArgumentNotValidException）：统一转为 400 BAD_REQUEST，并提取字段级错误信息填充 message
- 系统级异常（如 NullPointerException、SQLException、TimeoutException）：一律映射为 500 INTERNAL_SERVER_ERROR 或 503 SERVICE_UNAVAILABLE（后者适用于已知依赖中断场景），绝不暴露原始堆栈，仅记录日志供排查
网关层补全与协同，避免状态码语义被覆盖
单靠 Java 层处理不够。API 网关（如 Spring Cloud Gateway）需做两件事：
立即学习“Java免费学习笔记（深入）”；
- 对所有非 2xx 响应，自动注入
X-Error-Codeheader，值取自响应体中的code字段，方便前端或第三方系统快速识别业务错误类型 - 拦截 5xx 响应时，若判定为下游服务超时或熔断触发，可将原始 500 改写为 504 或 503，并补充重试建议到 response body 的 message 中
前端必须忽略状态码做业务判断，只看 code 字段
这是协议落地的关键约束。前端 SDK 或拦截器收到响应后：
- 只要 HTTP 状态码是 4xx，就认为是客户端可修正问题（如提示用户补全手机号），然后解析 body.code 判断具体原因（如
"PHONE_FORMAT_INVALID"） - 遇到 5xx，先检查 body.code 是否为
"DOWNSTREAM_TIMEOUT"或"CIRCUIT_OPEN"类型，决定是否自动重试；若是"SYSTEM_ERROR"，则展示兜底提示并上报监控 - 绝不能写
if (status === 500) { alert('服务器炸了') }这种代码 —— 它会把所有 500 都当成致命故障，掩盖了可恢复的临时错误
