Class FileDescriptor

java.lang.Object
io.leandev.appfuse.file.FileDescriptor
@Embeddable public class FileDescriptor extends Object

檔案描述符（值物件）

用於統一前後端的檔案資料格式，可嵌入 Entity 作為檔案欄位。

設計特點

  • fileId 儲存識別碼（tempId 或永久 fileId）
  • 包含檔案 metadata（filename, size, mimeType）
  • url 是 transient 欄位，由外層動態設定

fileId 格式

  • 暫存區（tempId）：yyyy-MM-dd/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  • 永久區（fileId）：yyyy-MM-dd/HH/filename-shortUuid.ext

使用流程

// 1. 暫存區上傳後取得 FileDescriptor
FileDescriptor staged = FileDescriptor.ofStaging(tempId, filename, size, mimeType);

// 2. 持久化後取得新的 FileDescriptor
FileDescriptor persisted = FileDescriptor.ofPermanent(fileId, filename, size, mimeType);

// 3. 儲存到 Entity
product.setMainImage(persisted);

// 4. 讀取時設定 url
product.getMainImage().setUrl("/api/v1/products/" + product.getId() + "/image");

  • Constructor Details

    • FileDescriptor

      public FileDescriptor()

  • Method Details

    • ofStaging

      public static FileDescriptor ofStaging(String tempId, String filename, Long size, String mimeType)
      建立暫存區 FileDescriptor
      Parameters:
      tempId - 暫存檔案 ID（格式：{date}/{uuid}）
      filename - 原始檔案名稱
      size - 檔案大小
      mimeType - MIME 類型
      Returns:
      FileDescriptor（url 指向暫存區端點）

    • ofStaging

      public static FileDescriptor ofStaging(String tempId, String filename, Long size, String mimeType, String url)

      建立暫存區 FileDescriptor（含自訂 URL）

      用於 Presigned URL 上傳場景，url 可能是外部 S3 URL。

      Parameters:
      tempId - 暫存檔案 ID（格式：{date}/{uuid}）
      filename - 原始檔案名稱
      size - 檔案大小
      mimeType - MIME 類型
      url - 上傳 URL（可能是 Presigned URL 或後端 API URL）
      Returns:
      FileDescriptor

    • ofPermanent

      public static FileDescriptor ofPermanent(String fileId, String filename, Long size, String mimeType)
      建立永久區 FileDescriptor
      Parameters:
      fileId - 永久檔案 ID（格式：{date}/{hour}/{filename}-{shortUuid}.{ext}）
      filename - 原始檔案名稱
      size - 檔案大小
      mimeType - MIME 類型
      Returns:
      FileDescriptor（url 需由外層設定）

    • ofPermanent

      public static FileDescriptor ofPermanent(String fileId, String filename, Long size, String mimeType, String url)
      建立永久區 FileDescriptor（含 URL）
      Parameters:
      fileId - 永久檔案 ID
      filename - 原始檔案名稱
      size - 檔案大小
      mimeType - MIME 類型
      url - 檔案存取 URL
      Returns:
      FileDescriptor

    • isStaging

      public boolean isStaging()

      判斷是否為暫存區檔案

      透過 fileId 格式判斷：暫存區的 fileId 第二段是完整 UUID（36 字元）

      Returns:
      若為暫存區檔案則為 true

    • isPermanent

      public boolean isPermanent()
      判斷是否為永久區檔案
      Returns:
      若為永久區檔案則為 true

    • isEmpty

      public boolean isEmpty()
      判斷是否為空（無檔案）
      Returns:
      若 fileId 為 null 或空白則為 true

    • getTempId

      public String getTempId()
      取得暫存區 tempId
      Returns:
      tempId，若非暫存區檔案則回傳 null

    • withUrl

      public FileDescriptor withUrl(String url)

      設定業務端點 URL

      方便鏈式呼叫：fd.withUrl("/api/v1/products/123/image")

      Parameters:
      url - 檔案存取 URL
      Returns:
      this

    • copy

      public FileDescriptor copy()
      複製一份 FileDescriptor（不含 url）
      Returns:
      新的 FileDescriptor

    • copyWithUrl

      public FileDescriptor copyWithUrl(String url)
      複製一份 FileDescriptor（含 url）
      Parameters:
      url - 新的 URL
      Returns:
      新的 FileDescriptor

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object