值表达式基础

QWen Flash 中英对照 Value Expressions Fundamentals

Value Expressions 是 Spring Expression Language (SpEL) 和 Property Placeholder Resolution 的组合。它们将程序化表达式的强大求值能力与 property-placeholder 解析的简洁性相结合，以便从 Environment 获取值，例如配置属性。

Expressions 预期应由 annotation value 等受信任的输入定义，而不应由 user input 决定。

范围

Value Expressions 用于注解的多种上下文中。Spring Data 在两个主要上下文中提供 Value Expression 求值：

• 映射模型注解: 例如 @Document、@Field、@Value 以及其他注解，这些注解存在于自带映射模型及其相应 Entity Reader 的 Spring Data 模块中，例如 MongoDB、Elasticsearch、Cassandra、Neo4j。基于提供自身映射模型的库（JPA、LDAP）构建的模块不支持映射注解中的 Value Expressions。

  以下代码演示了如何在映射模型注解的上下文中使用表达式。

  示例 1. @Document 注解用法

  @Document("orders-#{tenantService.getOrderCollection()}-${tenant-config.suffix}")
  class Order {
    // …
  }

  java

• 仓储查询方法: 主要通过 @Query。

  以下代码演示了如何在仓储查询方法的上下文中使用表达式。

  示例 2. @Query 注解用法

  class OrderRepository extends Repository<Order, String> {
  
    @Query("select u from User u where u.tenant = ?${spring.application.name:unknown} and u.firstname like %?#{escape([0])}% escape ?#{escapeCharacter()}")
    List<Order> findContainingEscaped(String namePart);
  }

  java

备注

请查阅您所在模块的文档，以确定实际的参数 by-name/by-index 绑定语法。通常，表达式以 :#{…}/:${…} 或 ?#{…}/?${…} 为前缀。

表达式语法

Value Expressions 可由单个 SpEL Expression、Property Placeholder 或混合了包括 literals 在内的各种表达式的复合表达式定义。

示例 3. 表达式示例

#{tenantService.getOrderCollection()}                          // <1>
#{(1+1) + '-hello-world'}                                      // <2>
${tenant-config.suffix}                                        // <3>
orders-${tenant-config.suffix}                                 // <4>
#{tenantService.getOrderCollection()}-${tenant-config.suffix}  // <5>

none

• 使用单个 SpEL 表达式的 Value Expression。

• 使用静态 SpEL 表达式并求值为 2-hello-world 的 Value Expression。

• 使用单个 Property Placeholder 的 Value Expression。

• 由字面量 orders- 和 Property Placeholder ${tenant-config.suffix} 组成的 Composite expression。

• 使用 SpEL、Property Placeholders 和字面量的 Composite expression。

备注

使用值表达式会为代码带来很大的灵活性。这样做需要在每次使用时对表达式进行求值，因此值表达式的求值会影响性能概况。

Spring Expression Language (SpEL) 和 Property Placeholder Resolution 详细说明了 SpEL 和 Property Placeholders 的语法与功能。

解析与求值

Value Expressions 由 ValueExpressionParser API 解析。ValueExpression 实例是线程安全的，可以缓存以供后续使用，从而避免重复解析。

以下示例展示了 Value Expression API 的用法:

Java

ValueParserConfiguration configuration = SpelExpressionParser::new;
ValueEvaluationContext context = ValueEvaluationContext.of(environment, evaluationContext);

ValueExpressionParser parser = ValueExpressionParser.create(configuration);
ValueExpression expression = parser.parse("Hello, World");
Object result = expression.evaluate(context);

java

Kotlin

val configuration = ValueParserConfiguration { SpelExpressionParser() }
val context = ValueEvaluationContext.of(environment, evaluationContext)

val parser = ValueExpressionParser.create(configuration)
val expression: ValueExpression = parser.parse("Hello, World")
val result: Any = expression.evaluate(context)

kotlin

SpEL 表达式

SpEL Expressions 遵循 Template 风格，其中表达式预期被包含在 #{…} 格式中。表达式使用由 EvaluationContextProvider 提供的 EvaluationContext 进行评估。上下文本身是一个强大的 StandardEvaluationContext，允许广泛的操作、访问静态类型和上下文扩展。

备注

请务必仅解析和求值来自 annotations 等可信来源的表达式。接受用户提供的表达式可能会创建入口路径，从而利用应用上下文和系统，导致潜在的安全漏洞。

扩展 Evaluation Context

EvaluationContextProvider 及其响应式变体 ReactiveEvaluationContextProvider 提供对 EvaluationContext 的访问。ExtensionAwareEvaluationContextProvider 及其响应式变体 ReactiveExtensionAwareEvaluationContextProvider 是默认实现，用于从应用上下文确定上下文扩展，具体来说是 ListableBeanFactory。

扩展实现 EvaluationContextExtension 或 ReactiveEvaluationContextExtension，以使用以下内容填充 EvaluationContext：根对象、命名属性和函数（顶级方法）。

下面的示例展示了一个上下文扩展，它提供了根对象、属性、函数和一个别名函数。

Java

@Component
public class MyExtension implements EvaluationContextExtension {

    @Override
    public String getExtensionId() {
        return "my-extension";
    }

    @Override
    public Object getRootObject() {
        return new CustomExtensionRootObject();
    }

    @Override
    public Map<String, Object> getProperties() {

        Map<String, Object> properties = new HashMap<>();

        properties.put("key", "Hello");

        return properties;
    }

    @Override
    public Map<String, Function> getFunctions() {

        Map<String, Function> functions = new HashMap<>();

        try {
            functions.put("aliasedMethod", new Function(getClass().getMethod("extensionMethod")));
            return functions;
        } catch (Exception o_O) {
            throw new RuntimeException(o_O);
        }
    }

    public static String extensionMethod() {
        return "Hello World";
    }

    public static int add(int i1, int i2) {
        return i1 + i2;
    }

}

public class CustomExtensionRootObject {

	public boolean rootObjectInstanceMethod() {
		return true;
	}

}

java

Kotlin

@Component
class MyExtension : EvaluationContextExtension {

    override fun getExtensionId(): String {
        return "my-extension"
    }

    override fun getRootObject(): Any? {
        return CustomExtensionRootObject()
    }

    override fun getProperties(): Map<String, Any> {
        val properties: MutableMap<String, Any> = HashMap()

        properties["key"] = "Hello"

        return properties
    }

    override fun getFunctions(): Map<String, Function> {
        val functions: MutableMap<String, Function> = HashMap()

        try {
            functions["aliasedMethod"] = Function(javaClass.getMethod("extensionMethod"))
            return functions
        } catch (o_O: Exception) {
            throw RuntimeException(o_O)
        }
    }

    companion object {
        fun extensionMethod(): String {
            return "Hello World"
        }

        fun add(i1: Int, i2: Int): Int {
            return i1 + i2
        }
    }
}

class CustomExtensionRootObject {
	fun rootObjectInstanceMethod(): Boolean {
		return true
	}
}

kotlin

一旦注册上述所示扩展，你就可以使用其导出的方法、属性和根对象来求值 SpEL 表达式：

示例 4. 表达式求值示例

#{add(1, 2)}                                             // <1>
#{extensionMethod()}                                     // <2>
#{aliasedMethod()}                                       // <3>
#{key}                                                   // <4>
#{rootObjectInstanceMethod()}                            // <5>

none

• 调用由 MyExtension 声明的 add 方法，结果为 3，因为该方法将两个数值参数相加并返回其和。

• 调用由 MyExtension 声明的 extensionMethod 方法，结果为 Hello World。

• 调用 aliasedMethod 方法。该方法作为函数暴露，并重定向到由 MyExtension 声明的 extensionMethod 方法，结果为 Hello World。

• 计算 key 属性，结果为 Hello。

• 在根对象实例 CustomExtensionRootObject 上调用 rootObjectInstanceMethod 方法。

你可以在 SecurityEvaluationContextExtension 中找到真实场景下的上下文扩展。

属性占位符

属性占位符遵循 ${…} 的形式，引用通常由 PropertySource 通过 Environment 提供的属性。属性可用于针对系统属性、应用程序配置文件、环境配置或密钥管理系统提供的属性源进行解析。你可以在 Spring Framework 关于 @Value 使用的文档 中找到有关属性占位符的更多详细信息。