graphql变量校验应在解析阶段快速失败，java中用optional.orelsethrow实现契约式校验，结合自定义validationerror异常返回符合规范的结构化错误响应。
在 GraphQL 服务端（尤其是 Java 生态）中，变量解析阶段属于请求错误（Request Error）范畴——它发生在查询执行前，由变量类型不匹配、必填变量缺失或格式非法等引起。这类错误不应进入字段执行流程，而应在解析/校验环节快速失败，并返回符合 GraphQL 规范的结构化错误响应。Java 的 Optional.orElseThrow 正是实现这一“契约式校验”的理想工具：它语义明确、延迟构造异常、避免空值穿透，且天然契合“变量必须存在/合法，否则即错误”的业务契约。
变量校验场景与orElseThrow的精准匹配
GraphQL 变量需满足三重约束：存在性（非 null）、类型兼容性（如 Int! 不接受 "abc"）、业务有效性（如 ID 必须为正整数）。这些都属于“空值即非法”的强契约场景：
- 用
Optional.ofNullable(inputVar)封装原始变量值，立即排除 null - 用
filter链式校验类型或范围（如.filter(v -> v instanceof Integer && (Integer)v > 0)） - 用
orElseThrow在任一校验失败时抛出定制异常，不走默认分支
构建符合 GraphQL 错误规范的自定义异常
直接抛出 RuntimeException 不够——GraphQL 要求错误包含 message、locations、path 和可选的 extensions。因此需封装一个实现 GraphQLError 接口（或继承 ExecutionError）的异常类：
- 在异常构造时注入变量名、预期类型、实际值等上下文（如
"Variable \"$userId\" of type \"Int!\" was expected, but got \"null\""） - 通过
extensions字段补充错误码（如"VARIABLE_NULL"）、错误分类（"validation"）和时间戳 - 确保该异常被 GraphQL 执行器自动识别并序列化为标准
errors数组项
实战代码示例（Spring + GraphQL Java）
以解析必填整型变量 $id 为例：
// 在 DataFetcher 或 Input Coercion 层
public User getUser(DataFetchingEnvironment env) {
Object rawId = env.getVariables().get("id");
Integer userId = Optional.ofNullable(rawId)
.filter(v -> v instanceof Integer)
.map(Integer.class::cast)
.filter(id -> id > 0)
.orElseThrow(() -> new ValidationError(
"Variable \"$id\" must be a positive integer",
"VARIABLE_INVALID",
List.of(new Location(1, 15)), // 来自查询文档位置（可从 env 获取）
List.of("id") // path 表示变量作用域
));
return userService.findById(userId);
}
此处 ValidationError 是你自定义的异常类，继承自 GraphQLError，其 toSpecification() 方法返回含 message、locations、path 和 extensions 的 Map。这样客户端收到的就是完全合规的响应：
{
"errors": [{
"message": "Variable \"$id\" must be a positive integer",
"locations": [{"line": 1, "column": 15}],
"path": ["id"],
"extensions": {
"code": "VARIABLE_INVALID"
}
}],
"data": null
}
为什么不用 if + throw 或 orElse？
对比其他写法：
-
if (rawId == null) throw new ValidationError(...)：需手动判空+类型+业务逻辑，分散且易漏；orElseThrow一条链完成全部校验 -
orElse(new RuntimeException())：违反“空值即错误”语义，且会创建无用异常实例，影响性能 -
orElseGet(() -> { throw ... })：语法冗余，不如orElseThrow直观专一
用 orElseThrow 不仅写出更少、更安全的代码，还让变量校验意图一目了然，天然对齐 GraphQL 的早期失败（fail-fast）原则。
