值表达式基础

值表达式结合了Spring 表达式语言 (SpEL)和属性占位符解析。它们将程序化表达式的强大评估能力与通过属性占位符解析从 Environment（例如配置属性）获取值的简单性相结合。

表达式应由受信任的输入（例如注解值）定义，而不是由用户输入决定。

范围

值表达式在各种注解的上下文中被使用。Spring Data 在两个主要上下文中提供值表达式评估：

映射模型注解：例如 Spring Data 模块中自带映射模型及相应实体读取器（如 MongoDB, Elasticsearch, Cassandra, Neo4j）中的 @Document, @Field, @Value 等注解。基于提供自身映射模型库（如 JPA, LDAP）的模块不支持在映射注解中使用值表达式。

以下代码演示了如何在映射模型注解的上下文中使用表达式。
示例 1. @Document 注解使用
@Document("orders-#{tenantService.getOrderCollection()}-${tenant-config.suffix}") class Order { // … }

Repository 查询方法：主要通过 @Query。

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

示例 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);
}

请查阅您所用模块的文档，以确定实际的按名称/按索引参数绑定语法。通常，表达式以前缀 :#{…}/:${…} 或 ?#{…}/?${…} 开头。

表达式语法

值表达式可以由单个 SpEL 表达式、属性占位符或包含字面量在内的各种表达式组成的复合表达式定义。

示例 3. 表达式示例

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

1	使用单个 SpEL 表达式的值表达式。
2	使用计算结果为 `2-hello-world` 的静态 SpEL 表达式的值表达式。
3	使用单个属性占位符的值表达式。
4	由字面量 `orders-` 和属性占位符 `${tenant-config.suffix}` 组成的复合表达式。
5	使用 SpEL、属性占位符和字面量的复合表达式。

使用值表达式为您的代码带来了极大的灵活性。这样做需要在每次使用时评估表达式，因此，值表达式评估会对性能造成影响。

Spring 表达式语言 (SpEL)和属性占位符解析详细解释了 SpEL 和属性占位符的语法及功能。

解析与评估

值表达式由 ValueExpressionParser API 解析。ValueExpression 实例是线程安全的，可以缓存供后续使用以避免重复解析。

以下示例展示了值表达式 API 的用法

解析与评估

Java
Kotlin

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);

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)

SpEL 表达式

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

请确保只解析和评估来自受信任来源（如注解）的表达式。接受用户提供的表达式可能会创建一个入口点，用于利用应用上下文和您的系统，从而导致潜在的安全漏洞。

扩展评估上下文

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

扩展实现 EvaluationContextExtension 或 ReactiveEvaluationContextExtension 以提供扩展支持来充实 EvaluationContext。这包括根对象、属性和函数（顶级方法）。

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

实现 EvaluationContextExtension

Java
Kotlin

@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;
	}

}

@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
	}
}

上述扩展注册后，您可以使用其导出的方法、属性和根对象来评估 SpEL 表达式

示例 4. 表达式评估示例

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

1	调用 `MyExtension` 声明的 `add` 方法，结果为 `3`，因为该方法将两个数字参数相加并返回总和。
2	调用 `MyExtension` 声明的 `extensionMethod` 方法，结果为 `Hello World`。
3	调用方法 `aliasedMethod`。该方法作为函数暴露，并重定向到 `MyExtension` 声明的 `extensionMethod` 方法，结果为 `Hello World`。
4	评估属性 `key`，结果为 `Hello`。
5	在根对象实例 `CustomExtensionRootObject` 上调用方法 `rootObjectInstanceMethod`。

您可以在SecurityEvaluationContextExtension中找到真实的上下文扩展示例。

属性占位符

遵循 ${…} 形式的属性占位符通常引用由 PropertySource 通过 Environment 提供的属性。属性可用于解析系统属性、应用配置文件、环境变量或由秘密管理系统贡献的属性源。您可以在Spring Framework 关于 @Value 用法的文档中找到有关属性占位符的更多详细信息。