markdown-it demo

clear permalink

### 📝 使用 `@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`。

html source debug