在 Spring GraphQL 中，OptionalInt 或 Optional 不能直接用作 @Argument 方法参数，因其不被框架原生支持；应改用可为 null 的 Integer 类型，并通过 == null 判断是否传入，避免类型转换异常与空指针风险。
在 spring boot 集成 graphql（如 spring graphql 1.2+）时，开发者常误以为 `optionalint` 或 `optional
✅ 正确做法：使用 Integer（而非 Optional）
GraphQL 规范中，标量字段（如 Int）天然支持 null 值。Spring GraphQL 会将未提供的参数自动绑定为 null（前提是 Java 类型允许），因此最简洁、安全且符合框架约定的方式是直接声明为可空的包装类型：
@QueryMapping
public List<customer> getCustomers(
@Argument Integer start,
@Argument Integer end
) {
List<customer> customers = customerRepository.findAll();
// 安全检查：仅当两个参数均非 null 时执行切片
if (start != null && end != null) {
try {
// 确保索引合法（防止越界）
int fromIndex = Math.max(0, Math.min(start, customers.size()));
int toIndex = Math.max(fromIndex, Math.min(end, customers.size()));
return customers.subList(fromIndex, toIndex);
} catch (IndexOutOfBoundsException e) {
return Collections.emptyList(); // 推荐使用不可变空列表
}
}
return customers;
}</customer></customer>
? 关键说明：
- @Argument Integer start 能正确接收 GraphQL 查询中缺失或显式传 null 的 start 参数，值为 null；
- OptionalInt 和 Optional
均无对应 GraphQL 输入类型映射，强制使用会导致 typeMismatch 绑定失败； - 不要尝试调用 start.isPresent() 或 start.getAsInt()——此时 start 是 null，调用会直接抛 NullPointerException。
? GraphQL Schema 与查询示例
确保你的 schema 定义保持一致（已正确声明为可选）：
type Query {
getCustomers(start: Int, end: Int): [Customer!]!
getCustomer(dni: String!): Customer
}
合法调用方式包括：
# 仅传 start
{ getCustomers(start: 0, end: null) { name surname } }
# 两者都不传（等价于省略）
{ getCustomers { name surname } }
# 两者都传
{ getCustomers(start: 2, end: 5) { name surname } }
⚠️ 注意事项与最佳实践
-
避免 Optional 作为控制器参数：不仅限于 GraphQL，Spring MVC/WebFlux 的 @RequestParam/@PathVariable 同样不支持 Optional
作为方法参数（除非配合 @Nullable 注解，但推荐直接用 T）。Optional 更适合作为返回值类型或领域模型内部封装，而非输入契约。 - 边界校验不可省略：即使参数非 null，subList(from, to) 要求 0 ≤ from ≤ to ≤ list.size()。建议使用 Math.max/min 进行防御性截断，而非依赖 try-catch 处理业务逻辑错误。
- 性能提示：若数据量大，customerRepository.findAll() 全量加载再内存分页效率低下。推荐改用 JpaRepository 的 Pageable 支持（如 findAll(Pageable)），结合 @SchemaMapping 或自定义分页参数实现数据库级分页。
综上，摒弃 OptionalInt 等包装类幻想，拥抱 Integer + null 检查，既是 Spring GraphQL 的标准用法，也是清晰、健壮、可维护的服务端设计原则。
