为何Spring接口接收请求时xSchemaVersion需改为xschemaVersion？

我定义了一个Spring POST接口/v1/message，接收@RequestBody的Message对象。Message类包含xSchemaVersion等字段。当请求体中使用驼峰格式"xSchemaVersion"时，返回400错误提示缺少该参数；将其改为"xschemaVersion"（s小写）则请求成功返回200。请问该现象的原因是什么？

相关代码如下：

接口代码 #

@PostMapping("/v1/message")
@PreAuthorize("#oauth2.isAnyClientId(@authorizeConfig.getIds())")
public void receive(
    @RequestBody @NotNull @Valid final Message message,
    @RequestHeader final HttpHeaders headers) {
  ...
}

Message类代码 #

@Builder
@Getter
@Setter
@EqualsAndHashCode
@NoArgsConstructor
@AllArgsConstructor
@JsonPropertyOrder(alphabetic = true)
public class Message {

  @NotBlank(message = "tenant is empty")
  private String tenant;

  @NotBlank(message = "messageId is empty")
  private String messageId;

  @NotBlank(message = "payload is empty")
  private String payload;

  @NotNull(message = "messageType is empty")
  private MessageType messageType;

  private String xSchemaVersion;
}

错误请求体 #

{
   "tenant":"client1",
   "messageId":"670f13e15d554b2bba56f6d76d33b79c",
   "payload":"",
   "messageType":"MessageType.Email",
   "xSchemaVersion":"2.7.3"
}

成功请求体 #

{
   "tenant":"client1",
   "messageId":"670f13e15d554b2bba56f6d76d33b79c",
   "payload":"",
   "messageType":"MessageType.Email",
   "xschemaVersion":"2.7.3"
}

核心原因 #

这个问题是Jackson默认属性命名策略对特殊前缀字段的处理逻辑导致的：

Jackson默认采用PropertyNamingStrategy.LOWER_CAMEL_CASE（小驼峰）策略，但对于以x开头后接大写字母的字段（比如xSchemaVersion），Jackson会将其反序列化的匹配规则处理为xschemaVersion——它把字段名拆分为前缀x + 首字母大写的SchemaVersion，再按照默认策略将首字母转为小写，最终得到xschemaVersion。

这就导致请求体用xSchemaVersion时，Jackson无法匹配到实体类的xSchemaVersion字段，参数绑定失败后触发400错误。

解决方案 #

有两种常用的解决方式：

• 方式一：给字段显式指定JSON匹配名
  在xSchemaVersion字段上添加@JsonProperty注解，明确指定请求体中对应的字段名：

@JsonProperty("xSchemaVersion")
private String xSchemaVersion;

这样Jackson会严格按照注解指定的名称匹配，不受默认策略影响。

• 方式二：全局修改Jackson命名策略
  如果需要统一处理这类特殊前缀字段，可以在Spring配置中自定义Jackson的属性命名策略：

@Configuration
public class JacksonConfig {
    @Bean
    public ObjectMapper objectMapper() {
        ObjectMapper objectMapper = new ObjectMapper();
        // 直接使用原驼峰格式匹配，不做自动转换
        objectMapper.setPropertyNamingStrategy(PropertyNamingStrategy.UPPER_CAMEL_CASE);
        return objectMapper;
    }
}

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