Struts 2 類型轉換：為集合屬性指定泛型元素類型（*-conversion.properties）

問題背景

Struts 2 通過 OGNL 表達式將請求參數自動填充到 Action 屬性。對於集合類型屬性（List、Set、Map），框架無法從泛型擦除後的字節碼獲取元素類型，導致類型轉換失敗或轉換為錯誤類型。

核心機制：局部類型轉換配置文件

• 命名規則：Action類名-conversion.properties
• 放置位置：與 Action 類同包同目錄
• 文件格式：標準 Properties 鍵值對

一、List/Set 集合元素類型指定

Action 類

package com.example.action;

import java.util.List;

public class LoginAction {
    private List users; // 無泛型或泛型擦除後無法識別元素類型
    
    public List getUsers() { return users; }
    public void setUsers(List users) { this.users = users; }
    
    public String execute() { return "success"; }
}

配置文件：LoginAction-conversion.properties

# 語法：Element_屬性名 = 元素全限定類名
Element_users=com.example.domain.User

效果

Struts 2 將請求參數轉換為 List<User>，每個元素自動實例化為 User 對象並調用其 setter 填充屬性。

二、Map 集合 Key/Value 類型指定

Action 類

public class ProductAction {
    private Map productMap; // Map 或 Map
    
    public Map getProductMap() { return productMap; }
    public void setProductMap(Map productMap) { this.productMap = productMap; }
}

配置文件：ProductAction-conversion.properties

# Map Key 類型：Key_屬性名 = Key全限定類名
Key_productMap=java.lang.String

# Map Value 類型：Element_屬性名 = Value全限定類名
Element_productMap=com.example.domain.Product

三、完整鍵名規則速查表

四、全局類型轉換配置 (xwork-conversion.properties)

若多個 Action 共用同類型集合，可在 src 根目錄創建 xwork-conversion.properties 定義全局規則：

# 全局：所有名為 users 的 List 皆為 User 元素
Element_users=com.example.domain.User

# 全局：所有名為 productMap 的 Map 皆為 String->Product
Key_productMap=java.lang.String
Element_productMap=com.example.domain.Product

五、底層原理：OGNL 類型轉換器

1. 請求參數（字符串）到達 Action
2. OGNL 根據屬性類型查找轉換器
3. 集合類型 → CollectionConverter / MapConverter
4. 讀取 *-conversion.properties 獲取元素類型
5. 遞歸調用元素類型的轉換器（如 UserConverter）
6. 實例化元素對象，填充屬性

六、常見坑與最佳實踐

1. 文件名大小寫敏感：LoginAction-conversion.properties 必須與類名完全一致
2. 路徑必須同包：Maven 結構下放在 src/main/resources/com/example/action/
3. 類全限定名無誤：包名+類名，無 .class 後綴
4. 優先使用泛型：private List<User> users; Struts 2.5+ 支持泛型反射獲取，無需配置文件
5. 複雜嵌套：List<Map<String, List<Product>>> 建議拆分為獨立 DTO 類，避免配置地獄

七、現代替代方案

Struts 2 已淘汰，現代框架（Spring MVC、Spring Boot）通過泛型反射直接獲取集合元素類型，無需額外配置：

@PostMapping("/users")
public Result<List<User>> batchCreate(@RequestBody List<User> users) {
    // 直接獲得 List，Jackson 自動反序列化每個元素
    return Result.success(userService.batchSave(users));
}

總結：Struts 2 因泛型擦除無法感知集合元素類型，通過 ActionName-conversion.properties 指定 Element_屬性名（List/Set/數組）或 Key_屬性名/Element_屬性名（Map）。現代開發請直接使用 Spring MVC + Jackson，框架自動處理泛型類型轉換。