属性路径

Doubao 中英对照 Property Paths

本章介绍属性路径的概念。属性路径是一种遍历领域类的导航形式，用于在与模型交互的上下文中应用某些方面。应用代码向数据访问组件提供属性路径，以表达诸如在查询中选择属性、构成谓词或应用排序等意图。属性路径源自其所属类型，可由一个或多个段组成。

提示

遵循领域驱动设计原则，构成持久化领域模型骨干、并通过 Spring Data 访问的类称为实体。对象图的入口点称为聚合根。

了解如何导航和引用这些属性，对于使用仓库和查询操作至关重要。

属性路径概述

属性路径提供了一种简单的、基于文本的机制来导航领域模型属性。本节介绍属性路径导航的基础知识，并演示基于字符串的方式与类型安全方式之间的权衡。

Java

class Person {
  String firstname, lastname;
  int age;
  Address address;
  List<Address> previousAddresses;

  String getFirstname() { … } // other property accessors omitted for brevity

}

class Address {
  String city, street;

  // accessors omitted for brevity

}

Kotlin

class Person {
  var firstname: String? = null
  var lastname: String? = null
  var age: Int = 0
  var address: Address? = null
  var previousAddresses: List<Address> = emptyList()
}

class Address {
  var city: String? = null
  var street: String? = null
}

属性路径使用点号表示法来表达贯穿 Spring Data 各项操作的属性引用，例如排序和过滤：

Sort.by("firstname", "address.city")

属性路径由一个或多个以点号（.）分隔的段组成。接受属性路径的方法支持单段引用（顶层属性）和多段导航，除非另有说明。

集合和数组属性支持透明遍历到其组件类型，从而可以直接引用嵌套属性：

Sort.by("address.city")             // <1>

Sort.by("previousAddresses")        // <2>

Sort.by("previousAddresses.city")   // <3>

• 从顶层 address 属性导航到 city 字段。

• 引用整个 previousAddresses 集合（某些技术支持基于集合的排序）。

• 遍历该集合，按每个地址的 city 字段排序。

基于字符串的属性路径简单易用且可广泛应用，但也有需要权衡之处：

• 灵活性：属性路径非常灵活，可以由常量字符串、配置构造，或作为用户输入的结果构造。

• 无类型：字符串路径不携带编译期类型信息。作为文本内容，它们不依赖底层领域类型。

• 重构风险：重命名领域属性通常需要手动更新字符串字面量；IDE 无法可靠地跟踪这些引用。

为提高重构安全性和类型一致性，建议优先使用方法引用这种类型安全的属性引用。这种方式将属性路径与编译期类型信息关联起来，并支持编译器校验和 IDE 驱动的重构。详细信息请参阅类型安全属性引用。

备注

有关实现细节，请参阅属性路径内部原理以了解更多信息。

属性路径内部原理

org.springframework.data.core 包是 Spring Data 跨领域类进行导航的基础。TypeInformation 接口提供类型自省能力，能够解析属性的类型。PropertyPath 表示通过领域类的文本导航路径。

它们共同提供：

• 泛型类型解析与自省

• 属性路径的创建与校验

• 集合和映射等复杂属性的实际类型解析

类型安全属性引用

类型安全属性引用消除了数据访问代码中一类常见错误来源：脆弱的、基于字符串的属性引用。本节说明如何使用方法引用表达对重构安全的属性路径。

属性路径虽然是对象导航的简单表示，但基于字符串的属性路径在重构过程中天然脆弱：随着属性定义与使用位置之间距离的增加，它们很容易被遗漏。通过 TypedPropertyPath 的类型安全替代方案从方法引用派生属性路径，使编译器能够校验属性名，并使 IDE 能够支持重构操作。

Java

// Inline usage with Sort
Sort.by(Person::getFirstName, Person::getLastName);

// Composed navigation
Sort.by(TypedPropertyPath.of(Person::getAddress).then(Address::getCity),
            Person::getLastName);

Kotlin

// Inline usage with Sort
Sort.by(Person::firstName, Person::lastName)

// Composed navigation
Sort.by(Person::address / Address::city, Person::lastName)

类型安全属性路径与查询抽象和条件构建器无缝集成，无需基于字符串的属性引用即可实现声明式查询构造。

采用类型安全属性引用与现代 Spring 开发原则相一致。提供声明式、类型安全且流式的 API，可以简化对数据访问的推理，并通过 IDE 重构支持和编译器对无效属性的早期反馈，消除一整类潜在 bug。

Lambda 自省会被缓存以提高效率，支持重复使用。JVM 会复用静态 lambda 实例，使得一次性解析的开销降至最低。

如果您需要一种类型安全的变体，使其受益于编译器校验和 IDE 支持，且用于不直接与 Spring Data API 集成的场景，可以单独使用 TypedPropertyPath：

Java

import static org.springframework.data.core.TypedPropertyPath.path;

// Static import variant
path(Person::getAddress)
                 .then(Address::getCity);

// Fluent composition
TypedPropertyPath.of(Person::getAddress)
                 .then(Address::getCity);

Kotlin

// Kotlin API
TypedPropertyPath.of(Person::address / Address::city)

// as extension function
(Person::address / Address::city).toPath()

类型安全属性引用 API 建议

在使用（或构建）基于类型安全属性引用的 API 时，请考虑以下建议：

• 使用方法引用：接受方法引用（例如 Person::getFirstName）而非字符串，以利用编译期校验和 IDE 重构支持。方法引用更受青睐，因为它们在 Java 和 Kotlin 中具有相似的表示。此外，由于方法引用表示更简单，与 lambda 相比还能提供更好的性能基线。

• 利用 TypedPropertyPath 的 T 类型：每当接受类型化属性路径时，请考虑使用 TypedPropertyPath<T, P> 的泛型类型 T。将属性路径限制为当前操作中使用的特定领域类型，可以减少误用其他类型中意外属性的可能性。

  每当接受或提供多个属性路径时，请考虑使用 TypedPropertyPath<T, ?>，以允许在所属类型 T 的上下文中使用属性，从而将属性路径限制为共同的所属类型。

备注

GraalVM 原生映像编译需要可序列化 TypedPropertyPath lambda 的可达性元数据。Spring Data 通过 org.springframework.data.core.TypedPropertyPathFeature 内置了一个 feature。该 feature 自动激活，并为 lambda 解析及所引用的反射成员（字段和方法）注册所需的序列化和反射元数据。另请注意，当使用 lambda 表达式而非方法引用时，您需要自行在原生映像配置中包含该 lambda 表达式所在类的 Java 源代码。