Apache BeanUtils 深度解析：屬性填充、類型轉換與自定義 Converter 實戰

簡介

Apache Commons BeanUtils 是 Java Bean 操作的利器，提供屬性獲取/設置、對象拷貝、Map 填充 Bean 等功能，核心優勢在於內建類型轉換機制，能自動處理字符串到基本類型、包裝類、甚至日期等復雜類型的轉換。本文通過實例詳解其核心用法與擴展點。

核心依賴

<dependency>
    <groupId>commons-beanutils</groupId>
    <artifactId>commons-beanutils</artifactId>
    <version>1.9.4</version>
</dependency>
<!-- 日期轉換需額外依賴 commons-collections -->

基礎屬性操作與自動類型轉換

Person p = new Person();
// 設置屬性（字符串自動轉 int）
BeanUtils.setProperty(p, "age", "25");
// 獲取屬性（返回字符串）
String name = BeanUtils.getProperty(p, "username");
// 輸出：25
System.out.println(p.getAge());

默認支持：八大基本類型及包裝類、String、BigDecimal、BigInteger、Class 等。

場景一：使用內建 DateLocaleConverter 處理日期

// 註冊日期轉換器（模式默認 Locale 相關）
ConvertUtils.register(new DateLocaleConverter(), Date.class);

Person p = new Person();
BeanUtils.setProperty(p, "birthday", "1995-05-05");
System.out.println(p.getBirthday()); // 正常解析

缺陷：空字符串會拋出異常，且格式固定，難以適應多樣業務場景。

場景二：自定義 Converter 實現健壯日期轉換

ConvertUtils.register(new Converter() {
    @Override
    public Object convert(Class type, Object value) {
        if (value == null) return null;
        if (!(value instanceof String)) throw new ConversionException("只支持 String 轉換");
        String str = ((String) value).trim();
        if (str.isEmpty()) return null; // 兼容空串

        SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");
        try { return sdf.parse(str); }
        catch (ParseException e) { throw new RuntimeException(e); }
    }
}, Date.class);

// 測試
BeanUtils.setProperty(p, "birthday", "  "); // 空串 → null，不拋異常
BeanUtils.setProperty(p, "birthday", "2020-12-31"); // 正常解析

設計要點：空值防禦、格式可配置化、異常統一包裝。

場景三：Map 批量填充 Bean (populate)

Map map = new HashMap<>();
map.put("username", "李四");
map.put("password", "123456");
map.put("age", "30");
map.put("birthday", "1990-01-01");

// 需先註冊日期轉換器
ConvertUtils.register(new DateLocaleConverter(), Date.class);

Person p = new Person();
BeanUtils.populate(p, map); // 一鍵填充所有匹配屬性
// p 現已包含所有數據

適用場景：Web 表單提交、HTTP 參數綁定、配置映射等。

進階：BeanUtils.copyProperties 対象拷貝

Person src = new Person(); src.setUsername("A"); src.setAge(20);
Person dest = new Person();
BeanUtils.copyProperties(dest, src); // 淺拷貝，同名同類型屬性自動轉換

常見坑與最佳實踐

• 線程不安全：ConvertUtils.register 修改全局註冊表，多線程環境下註冊自定義 Converter 可能衝突。建議啟動時集中註冊，或使用 BeanUtilsBean 實例隔離。
• 性能：反射調用較慢，高頻熱點可緩存 PropertyDescriptor 或改用 MapStruct/手寫 Setter。
• 只讀屬性：無 Setter 的屬性會被忽略，不報錯。
• 嵌套屬性：支持 address.city 級聯設置，需中間對象非 null。

總結

BeanUtils 以「約定優於配置」簡化了 Bean 操作，其 Converter 機制極具擴展性。掌握默認轉換、內建轉換器、自定義 Converter、Map 填充四大核心模式，即可應對 90% 以上的 Bean 數據綁定場景。現代項目中常與 Spring 的 DataBinder、@InitBinder 協同使用，理解其底層原理有助於排查綁定異常。