Class FileResponseBuilder

java.lang.Object
io.leandev.appfuse.file.FileResponseBuilder
public class FileResponseBuilder extends Object

檔案下載 Response 建構器

提供統一的檔案下載回應建構，支援：

  • 完整檔案下載（200 OK）
  • 部分內容下載（206 Partial Content）- 支援 Range Request
  • 影音串流（自動處理 Range Request）
  • 斷點續傳

使用範例

@GetMapping("/products/{id}/image")
public ResponseEntity<Resource> getProductImage(
        @PathVariable String id,
        @RequestHeader(value = "Range", required = false) String rangeHeader) {

    Product product = productService.findById(id);  // 權限檢查
    String partition = TenantContext.getCurrentTenantId();

    return FileResponseBuilder.from(fileStorage, partition, product.getImageFileId())
            .range(rangeHeader)
            .build();
}

影音串流範例

@GetMapping("/videos/{id}")
public ResponseEntity<Resource> streamVideo(
        @PathVariable String id,
        @RequestHeader(value = "Range", required = false) String rangeHeader) {

    Video video = videoService.findById(id);
    String partition = TenantContext.getCurrentTenantId();

    // 影音串流自動支援 Range Request，讓用戶可以拖動進度條
    return FileResponseBuilder.from(fileStorage, partition, video.getFileId())
            .range(rangeHeader)
            .build();
}
See Also:

  • Method Details

    • from

      public static FileResponseBuilder from(FileStorage fileStorage, String partition, String fileId)
      建立 FileResponseBuilder
      Parameters:
      fileStorage - FileStorage 實例
      partition - 儲存分區鍵
      fileId - 檔案 ID
      Returns:
      FileResponseBuilder 實例

    • range

      public FileResponseBuilder range(String rangeHeader)
      設定 Range header（支援部分內容下載）
      Parameters:
      rangeHeader - HTTP Range header 值（如 "bytes=0-1000"），可為 null
      Returns:
      this

    • filename

      public FileResponseBuilder filename(String filename)

      設定下載時的檔名

      若不設定，會使用檔案的原始檔名。

      Parameters:
      filename - 下載時顯示的檔名
      Returns:
      this

    • forceDownload

      public FileResponseBuilder forceDownload()

      強制下載（而非在瀏覽器中開啟）

      設定 Content-Disposition: attachment，讓瀏覽器下載檔案而非直接開啟。

      Returns:
      this

    • ifNoneMatch

      public FileResponseBuilder ifNoneMatch(String ifNoneMatch)

      設定請求的 If-None-Match header（啟用條件式下載）

      傳入後，build() 會以 ETag（見 build() 的 ETag 說明）比對； 相符則在開啟儲存串流之前直接回 304 Not Modified、不送 body， 同時省下傳輸與 storage 讀取。

      Controller 端以 @RequestHeader(value = "If-None-Match", required = false) 取得。

      Parameters:
      ifNoneMatch - 請求的 If-None-Match header 值，可為 null
      Returns:
      this

    • immutable

      public FileResponseBuilder immutable()

      宣告內容不可變，套用長效快取

      設定 Cache-Control: public, max-age=31536000, immutable，讓瀏覽器與共享快取 快取一年且不再回源驗證。適用於以 fileId 定址的 URL（如 /files/{fileId}）—— 因為 fileId 為 write-once（見 FileStorage），同一 fileId 的內容永不改變。

      勿用於「URL 穩定但內容可換」的實體型 URL（如 /products/{id}/image）； 那類請維持預設（no-cache + ETag 每次 revalidate），換圖時才不會拿到舊快取。

      Returns:
      this

    • cacheControl

      public FileResponseBuilder cacheControl(org.springframework.http.CacheControl cacheControl)

      覆寫 Cache-Control 策略

      預設為 CacheControl.noCache（帶 ETag、每次 revalidate、命中回 304）。 需要私有快取、短時效或其他策略時以此覆寫，例如 cacheControl(CacheControl.noCache().cachePrivate())。

      Parameters:
      cacheControl - Cache-Control 策略
      Returns:
      this

    • build

      public org.springframework.http.ResponseEntity<org.springframework.core.io.Resource> build()

      建構 ResponseEntity

      根據 Range header 決定回應類型：

      • If-None-Match 與 ETag 相符 → 304 Not Modified（不開串流、不送 body）
      • 無 Range header → 200 OK（完整檔案）
      • 有效的 Range header → 206 Partial Content（部分內容）
      • 檔案不存在 → 404 Not Found

      ETag：以 fileId 為強驗證器（"{fileId}"）。fileId 為 write-once （見 FileStorage），同一 fileId 的內容永不改變，故可安全作為 ETag。回應一律帶 ETag 與 Cache-Control（預設 no-cache，或 immutable() 的長效策略）。

      Returns:
      ResponseEntity