Class FileIdGenerator

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

檔案 ID 生成器

生成可攜且唯一的 ASCII-only 檔案 ID，格式為： {yyyy-MM-dd}/{HH}/{uuid}

範例

輸入：發酵乳.jpeg
輸出：2025-12-26/14/12345678-1234-1234-1234-123456789abc

設計考量

  • 時間維度：方便按日期管理、清理過期檔案
  • ASCII-only：Local、SFTP 與 object storage 共用相同可攜識別碼，不依賴 OS 檔名編碼
  • 完整 UUID：原始檔名不再參與唯一性，仍維持足夠的碰撞安全性
  • 原始檔名：由 FileStorage.FileMetadata 保存，不混入實體路徑或 object key

使用方式

可以透過靜態方法直接使用，或建立實例注入到 FileStorage 實作中。

// 靜態方法
String fileId = FileIdGenerator.generate("rose-bouquet.jpg");

// 實例方法（用於依賴注入）
FileIdGenerator generator = new FileIdGenerator();
String fileId = generator.generateId("rose-bouquet.jpg");

  • Constructor Details

    • FileIdGenerator

      public FileIdGenerator()

      預設建構子

      允許實例化以便在 Builder 模式中使用。

  • Method Details

    • generateId

      public String generateId(String originalFilename)
      生成可攜的檔案 ID（實例方法）
      Parameters:
      originalFilename - 原始檔名（保留參數相容性，不寫入 ID）
      Returns:
      ASCII-only 檔案 ID（如 "2025-12-26/14/12345678-1234-1234-1234-123456789abc"）

    • generateId

      public String generateId(String originalFilename, LocalDateTime dateTime)
      生成可攜的檔案 ID（實例方法，可指定時間）
      Parameters:
      originalFilename - 原始檔名（保留參數相容性，不寫入 ID）
      dateTime - 時間戳記
      Returns:
      檔案 ID

    • generate

      public static String generate(String originalFilename)
      生成可攜的檔案 ID
      Parameters:
      originalFilename - 原始檔名（保留參數相容性，不寫入 ID）
      Returns:
      ASCII-only 檔案 ID

    • generate

      public static String generate(String originalFilename, LocalDateTime dateTime)
      生成可攜的檔案 ID（可指定時間，方便測試）
      Parameters:
      originalFilename - 原始檔名（保留參數相容性，不寫入 ID）
      dateTime - 時間戳記
      Returns:
      檔案 ID

    • extractDatePath

      public static String extractDatePath(String fileId)

      從檔案 ID 提取日期路徑

      範例：2025-12-26/14/12345678-1234-1234-1234-123456789abc → 2025-12-26/14

      Parameters:
      fileId - 檔案 ID
      Returns:
      日期路徑

    • extractFilename

      public static String extractFilename(String fileId)

      從檔案 ID 提取檔名部分

      範例：2025-12-26/14/12345678-1234-1234-1234-123456789abc → 12345678-1234-1234-1234-123456789abc

      Parameters:
      fileId - 檔案 ID
      Returns:
      檔名