Java 自定義 Enum 轉換器 (Apache Commons BeanUtils)

通用 Enum 轉換器：字串 ⇄ Enum 互轉

在使用 Apache Commons BeanUtils 進行表單綁定、屬性複製時，預設不支援直接將請求參數（字串）轉為 Enum 型別。實作 `org.apache.commons.beanutils.Converter` 介面即可實現通用 Enum 自動轉換。

Maven 依賴

<dependency>
    <groupId>commons-beanutils</groupId>
    <artifactId>commons-beanutils</artifactId>
    <version>1.9.4</version>
</dependency>

轉換器實作

import org.apache.commons.beanutils.Converter;

public class EnumConverter implements Converter {

    @Override
    public Object convert(Class type, Object value) {
        if (value == null) return null;
        if (!type.isEnum()) throw new IllegalArgumentException("目標型別必須是 Enum: " + type);

        String strVal = value.toString().trim();
        if (strVal.isEmpty()) return null;

        try {
            // Enum.valueOf 需精確匹配 Enum 常數名稱 (大小寫敏感)
            return Enum.valueOf((Class) type, strVal);
        } catch (IllegalArgumentException e) {
            // 可選：支援忽略大小寫
            for (Enum eNum : type.getEnumConstants()) {
                if (eNum.name().equalsIgnoreCase(strVal)) return eNum;
            }
            throw new ConversionException("無法轉換 '" + strVal + "' 為 " + type.getSimpleName(), e);
        }
    }
}

註冊與使用

import org.apache.commons.beanutils.ConvertUtilsBean;
import org.apache.commons.beanutils.BeanUtilsBean;

// 1. 註冊 (應用啟動時一次即可)
ConvertUtilsBean convertUtils = new ConvertUtilsBean();
convertUtils.register(new EnumConverter(), Status.class); // 針對特定 Enum
// 或註冊通用 (BeanUtils 1.9.2+ 支援)
convertUtils.register(new EnumConverter(), Enum.class); // 所有 Enum

BeanUtilsBean.getInstance().setConvertUtils(convertUtils);

// 2. 使用範例
public class OrderForm {
    private Status status; // Enum: PENDING, PAID, SHIPPED, CANCELLED
    // getter/setter
}

// 請求參數 status=PAID 自動轉為 Status.PAID
OrderForm form = new OrderForm();
BeanUtils.populate(form, request.getParameterMap()); // status 字串自動轉 Enum
System.out.println(form.getStatus()); // PAID

Spring MVC 整合 (替代方案)

若使用 Spring MVC，建議使用內建的 `ConversionService` 或 `@InitBinder` 註冊 `Formatter`，更符合 Spring 生態：

@Component
public class EnumFormatter implements Formatter {
    @Override public Enum parse(String text, Locale locale) {
        return Enum.valueOf((Class) getTargetType(), text.toUpperCase());
    }
    @Override public String print(Enum object, Locale locale) { return object.name(); }
}

// WebMvcConfigurer
@Override public void addFormatters(FormatterRegistry registry) {
    registry.addFormatterForFieldType(Status.class, new EnumFormatter());
}

注意事項

• 大小寫：`Enum.valueOf` 預設大小寫敏感，建議統一前端傳輸大寫或在轉換器處理 `equalsIgnoreCase`。
• null/空字串：回傳 `null` 讓後續驗證框架（如 Bean Validation `@NotNull`）處理。
• 執行緒安全：`Converter` 實例需無狀態，可共用單例。
• 效能：`Enum.valueOf` 內部使用 `Map` 查找，O(1) 極快。