Spring Boot GraphQL输入类型字段与Java关键字冲突的映射方案问询

在Java 21 + Spring Boot 3.2.2（集成spring-boot-starter-graphql）环境下，针对GraphQL输入字段package与Java关键字冲突的问题，可以通过Spring GraphQL专属的字段映射注解解决，具体方案如下：

核心问题说明 #

Java中package是关键字，无法直接作为类字段名，但GraphQL请求固定使用该字段名。之前尝试的@JsonProperty无效，是因为Spring GraphQL默认不依赖Jackson的JSON映射规则，而是使用自身的字段绑定机制。

解决方案1：使用@GraphQLName注解映射字段 #

在Java输入DTO类的字段上添加@GraphQLName注解，指定对应的GraphQL字段名：

import org.springframework.graphql.data.GraphQLName;

public class MyInput {
    @GraphQLName("package")
    private Boolean pckge;

    // 标准getter/setter
    public Boolean getPckgge() {
        return pckge;
    }

    public void setPckgge(Boolean pckge) {
        this.pckge = pckge;
    }
}

在GraphQL控制器中正常接收该输入类型即可：

import org.springframework.graphql.data.method.annotation.Argument;
import org.springframework.graphql.data.method.annotation.MutationMapping;
import org.springframework.stereotype.Controller;

@Controller
public class MyGraphQLController {
    @MutationMapping
    public String handleInput(@Argument MyInput input) {
        Boolean packageValue = input.getPckgge();
        // 执行业务逻辑
        return "Received package value: " + packageValue;
    }
}

解决方案2：使用Java记录类（Record）简化代码 #

如果使用Java 21的记录类，可以更简洁地实现映射：

import org.springframework.graphql.data.GraphQLName;

public record MyInput(@GraphQLName("package") Boolean pckge) {}

记录类会自动生成构造器、访问方法等，@GraphQLName同样能将GraphQL的package字段绑定到记录的pckge参数上。

为什么@SchemaMapping不适用 #

@SchemaMapping是用于GraphQL输出类型（Object Type）的字段解析逻辑，仅针对响应数据的字段映射。而输入类型（Input Object Type）是请求参数的绑定，需要使用字段级的@GraphQLName注解来完成名称映射，因此之前的尝试会报错。

内容的提问来源于stack exchange，提问作者Ebad