### 📝 使用 `@Value` 取得屬性的基本寫法
您只需要在任何 Spring Bean（例如 `@Component`, `@Service`, `@Controller` 等）的欄位或方法上使用 `@Value` 註解。
#### 範例 1: 取得單一屬性（欄位注入）
假設您的 `application.properties` 中有以下配置：
```properties
app.name=RicharteExternalSystem
app.version=v1.0.0
app.timeout-seconds=30
```
您可以在 Bean 中這樣注入：
```java
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Service;
@Service
public class AppConfigService {
// 取得字串屬性
@Value("${app.name}")
private String applicationName;
// 取得整數屬性
@Value("${app.timeout-seconds}")
private int timeout;
public void printConfig() {
System.out.println("Application Name: " + applicationName);
System.out.println("Timeout: " + timeout + " seconds");
}
}
```
#### 範例 2: 使用預設值 (Default Value)
如果配置檔案中可能缺少某個屬性，您可以使用 `:` 語法提供一個預設值，避免應用程式啟動失敗。
```java
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;
@Component
public class ExternalService {
// 如果 application.properties 中沒有設定 external.url，則使用預設值 "http://default.api"
@Value("${external.url:http://default.api}")
private String externalApiUrl;
// 如果設定了 external.retries，則使用該值；否則使用 3
@Value("${external.retries:3}")
private int maxRetries;
}
```
-----
### ⚠️ 使用 `@Value` 的注意事項
1. **Scope 限制：** 只能在 **Spring 管理的元件** (Component) 中使用，例如帶有 `@Component`, `@Service`, `@Configuration`, `@Controller` 等註解的類。您不能在普通的 Java 類或靜態欄位中直接使用（除非使用特殊的配置）。
2. **屬性名稱：** 屬性名稱必須使用 `${...}` 語法，其中 `...` 是配置檔案中的完整路徑。
3. **資料類型：** Spring Boot 會自動嘗試將屬性值轉換為您註解的欄位類型（如 `String`, `int`, `boolean` 等）。
### 💡 進階用法：使用 `@ConfigurationProperties` (推薦)
當您需要取得**大量**相關屬性時，更推薦使用 `@ConfigurationProperties`，它可以將一組屬性對映到一個 POJO（Plain Old Java Object），使配置更加清晰和類型安全。
**1. 定義配置類：**
```java
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import java.util.List;
@Component
@ConfigurationProperties(prefix = "db") // 從所有以 db. 開頭的屬性中讀取
public class DatabaseProperties {
private String url;
private String username;
private List<String> hosts; // 可以自動對映列表
// ... 需要有 Getter/Setter
// ...
}
```
**2. `application.properties`：**
```properties
db.url=jdbc:mysql://localhost:3306/ccapp
db.username=admin
db.hosts[0]=server-a
db.hosts[1]=server-b
```
**3. 在服務中使用：**
```java
@Service
public class DataAccessService {
private final DatabaseProperties dbProperties;
// 透過建構函數注入
public DataAccessService(DatabaseProperties dbProperties) {
this.dbProperties = dbProperties;
}
public void connect() {
System.out.println("Connecting to: " + dbProperties.getUrl());
}
}
```
對於簡單的、少量屬性的取得，`@Value` 簡單而有效。對於複雜或結構化的配置，強烈建議使用 `@ConfigurationProperties`。