企业级应用应统一错误构造、分层捕获、结构化日志与前端协同：定义继承Error的语义化错误类，含code/status/meta/message字段；Controller层统一兜底并返回标准响应；日志需注入traceId等上下文；前端按code驱动文案、重试与上报。
统一错误构造：用自定义错误类封装业务语义
企业级应用中，不建议直接抛出字符串或原生 Error 实例。应定义继承自 Error 的层级化错误类，如 BusinessError、ValidationError、NetworkError，并强制携带标准字段：
-
code：机器可读的错误码（如
"USER_NOT_FOUND"），用于前端分流、监控告警和多语言映射 -
status：HTTP 状态码（如
404、422），便于网关/中间件统一处理 -
meta：结构化上下文（如
{ userId: "u_123", traceId: "t-abc" }），支持问题定位与链路追踪 - message：面向开发者的简明英文描述（非用户提示），保持一致性，避免拼写/时态混乱
示例：
class ValidationError extends Error {constructor(message, code, meta = {}) {
super(message);
this.name = 'ValidationError';
this.code = code;
this.status = 422;
this.meta = { ...meta };
}
}
分层捕获策略：按职责边界明确 try/catch 位置
不是所有地方都该写 try/catch。企业架构中应遵循“谁创建上下文，谁负责兜底”原则：
-
Controller 层：唯一允许向客户端返回错误响应的位置。统一用
try/catch捕获所有下游异常，转换为标准 JSON 响应（含code、message、traceId） -
Service 层：不主动
catch，但可抛出语义化错误（如throw new InsufficientBalanceError(...)），让上层决定如何响应 -
DAO / SDK 层：将原始异常（如数据库超时、Axios reject）包装为领域错误，隐藏技术细节，例如把
axios timeout转为NetworkTimeoutError
避免在工具函数、纯计算逻辑中捕获并静默吞掉错误——这会切断调用链，增加排查成本。
立即学习“Java免费学习笔记（深入）”；
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
日志契约：结构化输出 + 上下文注入
日志不是 console.error(e) 就完事。需建立日志规范，确保每条错误日志包含：
-
固定字段：
level="error"、timestamp、service="user-service"、traceId（来自请求头或生成）、spanId（如使用 OpenTelemetry） -
错误主体：序列化
e.code、e.status、e.message、e.stack（生产环境可裁剪敏感行） -
运行时上下文：当前用户 ID、请求路径、方法、关键入参（脱敏后）、Node 版本、部署环境（
prod/staging）
推荐使用 pino 或 winston 配合 cls-hooked（或 async_hooks）实现请求生命周期内的上下文自动注入，避免手动传递 traceId。
前端协同：错误码驱动的用户反馈与重试机制
后端错误码需与前端约定映射表，形成双向契约：
- 前端根据
error.code决定展示文案（通过 i18n key 查表），而非依赖message字符串匹配 - 对幂等性明确的错误码（如
"ORDER_ALREADY_PAID"），前端可自动跳转，不弹通用报错 - 对临时性错误（如
"NETWORK_TIMEOUT"、"RATE_LIMIT_EXCEEDED"），前端 SDK 自动触发退避重试，无需业务代码重复判断 - 所有未识别的
code必须上报监控系统，并触发告警，防止契约漂移
可在构建时校验前后端 error code 枚举是否一致，作为 CI 检查项之一。
