Struts2 FileUploadInterceptor 文件上傳攔截器完整配置指南

概述

FileUploadInterceptor 是 Struts2 內建的文件上傳攔截器，屬於 defaultStack 一部分。當表單提交包含 enctype="multipart/form-data" 且含 <s:file> 標籤時，攔截器自動將上傳文件封裝到 Action 屬性中。

前端表單編寫

<s:form namespace="/xxx" action="yyy" method="post" enctype="multipart/form-data">
    <s:file name="file" label="YourFile" />
    <s:submit />
</s:form>

Action 接收屬性約定

Action 需提供三組屬性（name 為表單 file 標籤的 name 值）：

• private File file; — 上傳文件對象
• private String fileContentType; — MIME 類型
• private String fileFileName; — 原始文件名

對應的 Setter 方法命名規則：setXxx(File)、setXxxContentType(String)、setXxxFileName(String)。

Action 示例

public class UploadAction extends ActionSupport {
    private File file;
    private String fileContentType;
    private String fileFileName;

    public void setFile(File file) { this.file = file; }
    public void setFileContentType(String fileContentType) { this.fileContentType = fileContentType; }
    public void setFileFileName(String fileFileName) { this.fileFileName = fileFileName; }

    public String execute() {
        // 此處處理文件保存邏輯，如 FileUtils.copyFile(file, new File(targetPath, fileFileName));
        return SUCCESS;
    }
}

限制上傳條件配置

在 struts.xml 中通過 <interceptor-ref> 覆蓋默認參數：

<interceptor-ref name="defaultStack">
    <!-- 限制文件大小，單位 byte，默認 2MB -->
    <param name="fileUpload.maximumSize">6000</param>
    
    <!-- 限制文件擴展名，逗號分隔 -->
    <param name="fileUpload.allowedExtensions">.txt,.jpg,.png</param>
    
    <!-- 限制 MIME 類型，逗號分隔 -->
    <param name="fileUpload.allowedTypes">image/png,text/plain</param>
</interceptor-ref>

錯誤信息國際化與自定義

校驗失敗時，攔截器會根據鍵從 struts-messages.properties 獲取錯誤信息，常見鍵值：

• struts.messages.error.uploading — 通用上傳失敗
• struts.messages.error.file.too.large — 文件過大
• struts.messages.error.content.type.not.allowed — 類型不允許
• struts.messages.error.file.extension.not.allowed — 擴展名不允許

可在項目資源文件中覆蓋這些鍵以自定義提示語。

最佳實踐提醒

1. 生產環境務必設置 maximumSize 防止 OOM。
2. 文件類型校驗建議雙重保障：擴展名 + MIME 類型 + 文件頭魔數檢查。
3. 上傳文件臨時存儲於磁盤，處理完需手動刪除或配置自動清理，避免磁盤佔用。