Spring Boot XML 反序列化中处理未知属性的策略

在 Spring Boot 应用中，当使用 Jackson 处理 XML 请求体时，默认情况下会静默忽略数据传输对象（DTO）中未定义的未知属性。这可能导致潜在的数据完整性问题和意料之外的行为。本文将详细探讨此默认行为及其原因，并提供配置 Jackson 以在遇到未知属性时抛出异常的解决方案，从而提升 API 的健壮性和安全性。

理解 Spring Boot 与 Jackson 的 XML 反序列化行为

Spring Boot 框架在处理 RESTful API 请求时，广泛依赖 Jackson 库进行 JSON 或 XML 数据的序列化与反序列化。当接收到 Content-Type: application/xml 的请求时，Spring Boot 会自动使用 Jackson 的 XML 模块（jackson-dataformat-xml）将 XML 请求体解析为对应的 Java 对象。

默认情况下，Jackson 在反序列化过程中对未知属性采取了宽容策略。这意味着如果传入的 XML 数据包含 DTO 中没有定义的元素或属性，Jackson 会简单地忽略这些未知部分，而不会抛出任何异常。这种行为虽然在某些场景下提供了灵活性，但在要求严格数据契约的 API 设计中，却可能成为一个隐患。例如，一个恶意或错误的请求可能会包含额外的、不应被处理的数据，而服务器却默默地接受了它，这可能掩盖了潜在的业务逻辑错误或安全漏洞。

考虑以下 Spring Boot 控制器和数据传输对象（DTO）示例：

// Controller
@RestController
class DataController {

    @PostMapping("/data", consumes = [MediaType.APPLICATION_XML_VALUE])
    fun pushMasterData(@RequestBody data: Data): Data {
        // 业务逻辑处理
        return data
    }
}

// DTO
data class Data(
   val item: String
)

当接收到如下 XML 请求体时：

<items>
   <item>foo</item>
   <trash>This should not be allowed!</trash>
</items>

默认情况下，Data 对象只会成功地包含 item 属性的值 "foo"，而 <trash> 元素则会被悄无声息地忽略。

配置 Jackson 以拒绝未知属性

为了强制 Jackson 在遇到未知属性时抛出异常，从而阻止不符合预期的请求，可以通过 Spring Boot 的配置属性进行全局设置。核心配置项是 spring.jackson.deserialization.fail-on-unknown-properties。

解决方案：

在 application.properties 或 application.yml 配置文件中添加以下配置：

序列猴子开放平台

具有长序列、多模态、单模型、大数据等特点的超大规模语言模型

0

查看详情

application.properties

spring.jackson.deserialization.fail-on-unknown-properties=true

application.yml

spring:
  jackson:
    deserialization:
      fail-on-unknown-properties: true

将此配置设置为 true 后，当 Jackson 尝试将包含未知属性的 XML（或 JSON）数据反序列化为 Java 对象时，如果目标 Java 类中没有对应的字段，它将抛出 UnrecognizedPropertyException。Spring Boot 会将此异常转换为 HTTP 400 Bad Request 响应，明确告知客户端请求数据格式不符合预期。

示例与效果

假设已经应用了上述配置，再次发送包含未知属性的 XML 请求：

<items>
   <item>foo</item>
   <trash>This should not be allowed!</trash>
</items>

此时，服务器将不再静默接受，而是返回类似以下内容的错误响应（具体格式可能因 Spring Boot 版本和错误处理配置而异）：

{
    "timestamp": "...",
    "status": 400,
    "error": "Bad Request",
    "message": "JSON parse error: Unrecognized field \"trash\" (class com.example.demo.Data), not marked as ignorable; nested exception is com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException: Unrecognized field \"trash\" (class com.example.demo.Data), not marked as ignorable (through reference chain: com.example.demo.Data[\"trash\"])",
    "path": "/data"
}

（注意：尽管是 XML 请求，Jackson 异常信息中可能会提及 "JSON parse error"，这是因为 Jackson 内部处理机制的通用性。）

注意事项与高级考量

1. 全局性影响： spring.jackson.deserialization.fail-on-unknown-properties=true 是一个全局配置，它会影响所有通过 Jackson 进行反序列化的请求，无论是 XML 还是 JSON。在大多数情况下，这种严格性是期望的，但如果某些端点需要更宽松的策略，则需要考虑局部覆盖。
2. 局部覆盖： 如果需要对特定的 DTO 或控制器方法进行更细粒度的控制，可以使用 Jackson 提供的注解。例如，在 DTO 类上使用 @JsonIgnoreProperties(ignoreUnknown = false) 可以达到同样的效果，但仅限于该类。如果希望允许特定 DTO 忽略未知属性，可以使用 @JsonIgnoreProperties(ignoreUnknown = true)。
3. 其他 XML 解析器： 虽然 Spring Boot 默认使用 Jackson 处理 XML，但在某些特殊情况下，项目可能引入了其他的 XML 解析库或自定义了消息转换器。在这种情况下，上述 Jackson 配置可能不会生效，需要检查实际使用的解析器及其配置。
4. 契约优先原则： 在设计 API 时，遵循“契约优先”原则是非常重要的。明确定义请求和响应的数据结构，并强制执行这些契约，有助于提高 API 的稳定性和可维护性。拒绝未知属性是实现这一原则的关键一步。

总结

通过在 application.properties 或 application.yml 中设置 spring.jackson.deserialization.fail-on-unknown-properties=true，可以有效地增强 Spring Boot 应用程序在处理 XML（以及 JSON）请求时的健壮性。此配置确保了传入数据严格遵循定义的 DTO 结构，避免了因未知或意外属性导致的潜在问题。这不仅有助于提高数据处理的准确性，也为构建安全、可靠的 API 提供了重要的保障。

以上就是Spring Boot XML 反序列化中处理未知属性的策略的详细内容，更多请关注php中文网其它相关文章！