Struts2 實現文件上傳與下載完整指南

Struts2 文件上傳與下載核心機制解析

在 Java Web 開發中，文件上傳與下載是極為常見的業務需求。Struts2 作為經典的 MVC 框架，通過攔截器機制與結果類型封裝了底層的流操作，讓開發者能以極簡的配置完成文件處理。本文將從依賴引入、單/多文件上傳、文件下載三大核心場景，系統梳理實現細節與關鍵配置。

一、 必備依賴包

Struts2 的文件上傳功能底層依賴 Apache Commons FileUpload 解析 multipart/form-data 請求，並借助 Commons IO 簡化流操作。專案中必須引入以下兩個 JAR 包：

• commons-fileupload-1.3.1.jar：核心解析組件
• commons-io-2.2.jar：流處理工具庫

二、 單文件上傳實戰

1. 前端表單構建

JSP 頁面需設置 enctype="multipart/form-data"，並提供 <input type="file" name="upload" /> 控件。name 屬性值將與 Action 中的屬性名對應。

2. Struts.xml 核心配置

在 <action> 節點下通過 <param> 指定服務端保存路徑 savePath，該路徑相對於 Web 應用根目錄。

<action name="upload" class="cn.wz.upload.action.UploadAction">
    <param name="savePath">/upload</param>
    <result name="success">success.jsp</result>
</action>

3. Action 處理類設計

UploadAction 需繼承 ActionSupport，並聲明四個關鍵屬性（Struts2 攔截器會自動注入）：

• File upload：封裝上傳文件的臨時文件對象
• String uploadFileName：原始文件名
• String uploadContentType：文件 MIME 類型
• String savePath：對應配置文件中的保存路徑參數

在 execute() 方法中，通過流拷貝將臨時文件持久化到目標目錄：

public String execute() throws Exception {
    byte[] buffer = new byte[1024];
    FileInputStream fis = new FileInputStream(getUpload());
    // 獲取真實物理路徑
    String realPath = ServletActionContext.getServletContext().getRealPath(getSavePath());
    FileOutputStream fos = new FileOutputStream(realPath + "\\" + getUploadFileName());
    
    int length;
    while ((length = fis.read(buffer)) > 0) {
        fos.write(buffer, 0, length);
    }
    fis.close();
    fos.flush();
    fos.close();
    return SUCCESS;
}

三、 多文件上傳擴展

多文件上傳的核心在於前端表單提供多個 name="upload" 的文件控件，後端 Action 將對應屬性改為數組或 List：

• File[] upload
• String[] uploadFileName
• String[] uploadContentType

處理邏輯只需遍歷數組，逐個執行單文件上傳的流拷貝操作即可：

public String execute() throws Exception {
    byte[] buffer = new byte[1024];
    for (int i = 0; i < upload.length; i++) {
        FileInputStream fis = new FileInputStream(upload[i]);
        String realPath = ServletActionContext.getServletContext().getRealPath(savePath);
        FileOutputStream fos = new FileOutputStream(realPath + "\\" + uploadFileName[i]);
        
        int length;
        while ((length = fis.read(buffer)) > 0) {
            fos.write(buffer, 0, length);
        }
        fis.close();
        fos.flush();
        fos.close();
    }
    return SUCCESS;
}

四、 文件下載機制詳解

Struts2 提供 Stream Result Type 專門處理文件下載，其核心是由 Action 提供一個 InputStream，框架負責將流內容寫入 HTTP 響應體。

1. Stream 結果類型關鍵參數

2. 下載 Action 實現

DownAction 需提供以下屬性：

• String inputPath：文件存儲相對路徑（對應上傳的 savePath）
• String fileName：下載文件名
• InputStream inputStream：文件輸入流（通過 getter 方法惰性創建）
• String contentType：文件 MIME 類型

public InputStream getInputStream() throws FileNotFoundException {
    String path = ServletActionContext.getServletContext().getRealPath(inputPath);
    return new BufferedInputStream(new FileInputStream(path + "\\" + fileName));
}

3. Struts.xml 下載配置範例

<action name="down" class="cn.wz.upload.action.DownAction">
    <param name="inputPath">/upload</param>
    <result name="success" type="stream">
        <param name="contentType">application/msword</param>
        <param name="inputName">inputStream</param>
        <param name="contentDisposition">attachment;filename="${fileName}"</param>
        <param name="bufferSize">4096</param>
    </result>
</action>

4. 常見文件類型對應的 ContentType 速查表

五、 最佳實踐與注意事項

1. 文件名編碼處理：中文文件名在下載時需經過 ISO-8859-1 或 URLEncoder 編碼，避免瀏覽器顯示亂碼。
2. 大文件優化：生產環境建議使用 File.renameTo() 或 NIO Files.move() 替代流拷貝，提升性能；或引入分片上傳、斷點續傳機制。
3. 安全防範：嚴格校驗文件類型、大小、副本名；存儲路徑應置於 Web 根目錄之外，防止惡意腳本直接訪問執行。
4. 臨時文件清理：Struts2 上傳攔截器產生的臨時文件需確保在異常情況下也能被刪除，避免磁盤佔用。

掌握上述核心配置與代碼模式，即可在 Struts2 專案中靈活實現文件上傳下載功能。實際專案中建議封裝通用的文件服務組件，進一步解耦業務邏輯與框架細節。