应使用 Optional.orElseThrow() 实现 GraphQL 变量校验的早失败机制，通过链式调用分层校验存在性、类型、格式与业务规则，并统一抛出带 extensions 的 GraphQLVariableException。
在 GraphQL API 中，变量解析失败时直接抛出语义明确的 IllegalArgumentException 或自定义异常（如 VariableValidationException），比返回 null 或默认值更符合其“强契约、早失败”设计哲学。而 Optional.orElseThrow() 正是实现这一目标的简洁、安全且可读性强的核心工具。
用 orElseThrow 替代 null 检查，让错误位置更精准
GraphQL 执行层（如 DGS、GraphQL Java）常将变量映射为 Map<string object></string> 或封装后的 GraphQLContext。若需提取必填变量 id 并确保其非空、类型正确，传统写法易漏判或堆砌 if：
// ❌ 易错：可能忽略类型转换异常，且错误信息模糊
Object rawId = variables.get("id");
if (rawId == null) {
throw new VariableValidationException("Variable 'id' is required");
}
Long id = (Long) rawId; // ClassCastException 隐蔽且堆栈不指向变量层
改用 Optional 封装解析逻辑后，orElseThrow 一次性声明“缺失即失败”，异常直接关联变量名：
// ✅ 清晰：解析失败立刻抛出带上下文的异常
Long id = Optional.ofNullable(variables.get("id"))
.filter(Objects::nonNull)
.map(o -> {
if (o instanceof Number) return ((Number) o).longValue();
throw new VariableValidationException("Variable 'id' must be a number");
})
.orElseThrow(() -> new VariableValidationException("Variable 'id' is required"));
组合多个 orElseThrow 实现分层校验
一个变量往往需满足多重要求：存在 → 类型正确 → 格式合法 → 业务约束（如正数、长度限制）。利用 Optional 链式调用，每步失败都可定制异常细节：
- 第一步用
ofNullable捕获null； - 第二步用
filter检查类型/基础格式； - 第三步用
map转换并嵌入业务规则校验； - 最终
orElseThrow统一兜底，但每步均可提前中断并携带精准提示。
String email = Optional.ofNullable(variables.get("email"))
.filter(Objects::nonNull)
.filter(String.class::isInstance)
.map(String.class::cast)
.filter(e -> e.contains("@") && e.length() <= 254)
.orElseThrow(() -> new VariableValidationException(
"Variable 'email' must be a non-empty string with '@' and ≤254 chars"
));
统一异常类型 + GraphQL 错误分类，提升客户端体验
GraphQL 规范要求错误应包含 extensions 字段，用于传递码（如 "BAD_USER_INPUT"）、字段路径等。建议封装一个继承 RuntimeException 的 GraphQLVariableException：
- 构造时传入变量名、校验阶段、用户友好消息；
- 重写
getExtensions()方法，自动注入{"code": "VARIABLE_REQUIRED", "variableName": "id"}； - 在全局异常处理器（如 Spring 的
@ControllerAdvice）中识别该异常，将其转为标准 GraphQL 错误对象。
这样，前端收到的响应会是：
{
"errors": [{
"message": "Variable 'id' is required",
"locations": [{"line": 1, "column": 1}],
"extensions": {
"code": "VARIABLE_REQUIRED",
"variableName": "id"
}
}]
}
避免 orElseThrow 的常见陷阱
orElseThrow 很好用，但需注意三点：
-
不要传 null Supplier：写成
.orElseThrow(null)会 NPE，必须传 lambda 或方法引用； - Supplier 内部勿做重操作：异常构造本身应轻量，避免在其中查库、发 HTTP 请求；
-
别和 orElse 混用：一旦用了
orElse提供默认值，就违背了“变量必填”的契约，后续校验可能失效——GraphQL 变量要么全有，要么报错，没有“尽力而为”。
