1. 简介
Spring 框架中的 @Value 注解是一种将配置文件中的属性值注入到类中的强大机制。它在 Kotlin 中的使用方式与 Java 大体一致，但由于 Kotlin 自身的语言特性——比如✅ 空安全（null safety） 和 ✅ 默认构造函数——在实际使用时会有一些需要注意的细节。
本文将带你掌握如何在 Kotlin 环境下正确使用 @Value 注解，避免踩坑。
2. @Value 的基本用法
@Value 可以直接将 application.properties 或 application.yml 中的配置项注入到 Spring Bean 的字段中。⚠️ 关键点：Kotlin 字符串支持 $ 符号进行字符串插值（string interpolation），因此我们必须对占位符中的 $ 进行转义，否则会被 Kotlin 编译器误解析。
来看一个典型示例：
@Component
class MyBean {
@Value("\${some.property}")
lateinit var propertyValue: String
}
✅ 解析：
- 使用
@Value("\${some.property}")正确读取配置项。 - 字段使用
lateinit var声明，适用于可变字段的字段注入。 - 配置来源可以是
application.properties中的：
some.property=hello-world
❌ 踩坑提醒：如果写成 "${some.property}"（未转义），Kotlin 会尝试做字符串插值，导致编译错误或运行时异常。
3. 构造函数注入（推荐）
Kotlin 推崇不可变性（immutability），因此更推荐使用构造函数注入，尤其是当你希望属性一旦初始化就不能更改时。
@Component
class MyBean(@Value("\${some.property}") val propertyValue: String)
✅ 优势：
propertyValue是val，不可变，线程安全。- 避免了
lateinit的潜在空指针风险。 - 更符合函数式编程和依赖注入的最佳实践。
💡 小贴士：Spring Boot 2.2+ 已默认支持 Kotlin 构造函数参数的自动注入，无需额外配置。
4. 设置默认值
Spring 支持在 @Value 中通过冒号 : 指定默认值，当配置项不存在时使用该值。这在环境差异化配置中非常实用。
@Component
class MyBean(@Value("\${some.property:default}") val propertyValue: String)
✅ 行为说明：
- 若
some.property存在，使用其值； - 若不存在，则
propertyValue = "default"； - ⚠️ 注意：即使有默认值，类型仍不能为
String?（除非你显式允许 null），否则可能引发类型不匹配。
❌ 错误认知澄清：
“可以用 Kotlin 的默认参数代替
@Value的默认值？”
不行！ 下面这种写法 ❌ 无效：
// ❌ 不生效！Spring 不会识别 Kotlin 默认参数作为 @Value 的 fallback
@Component
class MyBean(@Value("\${some.property}") val propertyValue: String = "default")
原因是 @Value 的解析由 Spring 容器完成，而 Kotlin 默认参数是在编译期处理的，两者不联动。
5. 处理 null 值（空安全）
Kotlin 的空安全机制要求我们明确区分可空类型（String?）和非空类型（String）。如果某个配置项可能不存在，且你不希望设置默认字符串，而是接受 null，则必须将其声明为可空类型。
但直接写 @Value("\${some.property}") val prop: String? 会报错，因为 Spring 无法注入 null 到非 SpEL 表达式的占位符中。
✅ 正确做法是使用 Spring Expression Language (SpEL) 显式指定 null 默认值：
@Component
class MyBean(@Value("\${some.property:#{null}}") val propertyValue: String?)
✅ 解析：
\${some.property:#{null}}表示：读取some.property，若不存在则返回null。- 类型为
String?，兼容null，符合 Kotlin 类型系统。 - ✅ 安全且清晰。
❌ 若错误地声明为非空类型且无默认值：
@Value("\${missing.property}") val value: String
启动时会抛出类似以下异常：
Constructor threw exception; nested exception is java.lang.NullPointerException:
Parameter specified as non-null is null
这是 Kotlin 编译器生成的防空校验，防止运行时出现隐式空指针。
6. 高级用法：结合 SpEL
@Value 支持完整的 Spring Expression Language（SpEL），可用于更复杂的场景，例如读取系统属性、环境变量、调用静态方法等。
示例 1：读取系统属性
@Component
class MyBean(@Value("#{systemProperties['user.home']}") val homeDir: String)
Spring 会注入 JVM 启动时的 -Duser.home 值，如 /Users/zhangsan。
示例 2：读取环境变量
@Component
class MyBean(@Value("#{environment['HOME']}") val homePath: String)
从操作系统环境变量中读取 HOME。
示例 3：条件表达式
@Component
class MyBean(
@Value("#{\${feature.enabled:false} ? 'prod-mode' : 'dev-mode'}")
val mode: String
)
- 如果
feature.enabled=true，mode = "prod-mode"； - 否则，默认为
"dev-mode"。
⚠️ 注意：SpEL 中嵌套的 ${} 也需要转义，所以写成 \${feature.enabled:false}。
7. 总结
@Value 在 Kotlin + Spring 生态中依然强大，但必须结合 Kotlin 的语言特性谨慎使用：
✅ 最佳实践清单：
| 场景 | 推荐写法 |
|---|---|
| 基本注入 | @Value("\${key}")（记得转义 $） |
| 构造函数注入 | ✅ 优先使用，保证不可变性 |
| 默认值 | @Value("\${key:default}") |
| 允许 null | @Value("\${key:#{null}}") val prop: String? |
| 高级逻辑 | 使用 SpEL：#{...} |
⚠️ 牢记：
- 不要用 Kotlin 默认参数替代
@Value默认值； - 非空类型必须确保配置存在或提供默认值；
- 所有
$占位符必须转义为\$。
本文所有代码示例均已上传至 GitHub：https://github.com/baeldung/kotlin-tutorials/tree/master/spring-boot-kotlin-2
（原链接指向 Baeldung 示例仓库，已恢复真实地址）