java.lang.Object

io.leandev.appfuse.file.local.LocalFileStorage

All Implemented Interfaces:: FileStorage

public class LocalFileStorage extends Object implements FileStorage

本地檔案儲存實作

將檔案儲存在本地檔案系統。適用於開發環境或單機部署。

fileId 格式

yyyy-MM-dd/HH/filename-shortUuid.ext

目錄結構

{basePath}/
├── staging/                           # 暫存區
│   └── {tenantId}/
│       └── {date}/{uuid}.bin          # 暫存檔案
│       └── {date}/{uuid}.meta         # metadata
└── files/                             # 永久區
    └── {tenantId}/
        └── {yyyy-MM-dd}/
            └── {HH}/
                └── {filename-shortUuid}.{ext}

使用方式

FileStorage fileStorage = LocalFileStorage.builder()
    .basePath(Path.of("/data/files"))
    .stagingBaseUrl("/api/v1/staging/files")
    .maxFileSize(50 * 1024 * 1024)  // 50MB
    .idGenerator(new FileIdGenerator())
    .build();

檔案大小限制

可選的 maxFileSize 參數用於限制檔案大小。設定後會在 prepareStaging 和 store 時檢查。若未設定（值為 0 或負數），則不進行大小限制。

Nested Class Summary

Nested Classes

Modifier and Type

Class

Description

static class

LocalFileStorage.Builder

Nested classes/interfaces inherited from interface FileStorage
FileStorage.FileMetadata, FileStorage.StagingUploadInfo
Method Summary

Modifier and Type

Method

Description

static LocalFileStorage.Builder

builder()

void

completeStagingUpload(String tenantId, String tempId, InputStream content, long size)

完成暫存上傳 - 統一上傳流程的第二步

void

delete(String tenantId, String fileId)

刪除永久區檔案

void

deleteStaged(String tenantId, String tempId)

刪除暫存檔案

boolean

exists(String tenantId, String fileId)

檢查永久區檔案是否存在

boolean

existsStaged(String tenantId, String tempId)

檢查暫存檔案是否存在

InputStream

getInputStream(String tenantId, String fileId)

取得永久區檔案的 InputStream

Optional<FileStorage.FileMetadata>

getMetadata(String tenantId, String fileId)

取得永久區檔案的 Metadata

InputStream

getStagedInputStream(String tenantId, String tempId)

取得暫存檔案的 InputStream

Optional<FileStorage.FileMetadata>

getStagedMetadata(String tenantId, String tempId)

取得暫存檔案的 Metadata

String

getStorageType()

取得儲存類型名稱

String

getUrl(String tenantId, String fileId)

本地儲存不支援 URL 存取

String

persist(String tenantId, String tempId)

將暫存檔案持久化到永久區

FileStorage.StagingUploadInfo

prepareStaging(String tenantId, String filename, String contentType, long size)

準備暫存上傳 - 統一上傳流程的第一步

String

store(String tenantId, String filename, InputStream content, String contentType, long size)

直接儲存檔案到永久區（跳過暫存）

Methods inherited from class Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details
- builder
  
  public static LocalFileStorage.Builder builder()
- prepareStaging
  
  public FileStorage.StagingUploadInfo prepareStaging(String tenantId, String filename, String contentType, long size)
  
  Description copied from interface: FileStorage
  
  準備暫存上傳 - 統一上傳流程的第一步
  
  前端先呼叫此方法取得上傳 URL，再透過 PUT 上傳檔案內容。此設計讓所有儲存類型（Local、Database、S3）使用統一的前端上傳邏輯。
  
  Specified by:
  
  prepareStaging in interface FileStorage
  
  Parameters:
  
  tenantId - 租戶 ID
  
  filename - 原始檔名
  
  contentType - MIME 類型
  
  size - 檔案大小
  
  Returns:
  
  StagingUploadInfo（含 tempId 和上傳 URL）
- completeStagingUpload
  
  public void completeStagingUpload(String tenantId, String tempId, InputStream content, long size)
  
  Description copied from interface: FileStorage
  
  完成暫存上傳 - 統一上傳流程的第二步
  
  接收 PUT 請求的檔案內容，完成暫存區上傳。此方法由 Controller 在收到 PUT 請求時呼叫。
  
  Specified by:
  
  completeStagingUpload in interface FileStorage
  
  Parameters:
  
  tenantId - 租戶 ID
  
  tempId - 暫存檔案 ID（由 prepareStaging 回傳）
  
  content - 檔案內容的 InputStream
  
  size - 檔案大小
- getStagedMetadata
  
  public Optional<FileStorage.FileMetadata> getStagedMetadata(String tenantId, String tempId)
  
  Description copied from interface: FileStorage
  
  取得暫存檔案的 Metadata
  
  Specified by:
  
  getStagedMetadata in interface FileStorage
  
  Parameters:
  
  tenantId - 租戶 ID
  
  tempId - 暫存檔案 ID
  
  Returns:
  
  檔案 Metadata，若不存在則回傳 empty
- getStagedInputStream
  
  public InputStream getStagedInputStream(String tenantId, String tempId) throws FileNotFoundException
  
  Description copied from interface: FileStorage
  
  取得暫存檔案的 InputStream
  
  Specified by:
  
  getStagedInputStream in interface FileStorage
  
  Parameters:
  
  tenantId - 租戶 ID
  
  tempId - 暫存檔案 ID
  
  Returns:
  
  InputStream（呼叫端負責關閉）
  
  Throws:
  
  FileNotFoundException - 若檔案不存在
- existsStaged
  
  public boolean existsStaged(String tenantId, String tempId)
  
  Description copied from interface: FileStorage
  
  檢查暫存檔案是否存在
  
  Specified by:
  
  existsStaged in interface FileStorage
  
  Parameters:
  
  tenantId - 租戶 ID
  
  tempId - 暫存檔案 ID
  
  Returns:
  
  是否存在
- deleteStaged
  
  public void deleteStaged(String tenantId, String tempId)
  
  Description copied from interface: FileStorage
  
  刪除暫存檔案
  
  Specified by:
  
  deleteStaged in interface FileStorage
  
  Parameters:
  
  tenantId - 租戶 ID
  
  tempId - 暫存檔案 ID
- persist
  
  public String persist(String tenantId, String tempId)
  
  Description copied from interface: FileStorage
  
  將暫存檔案持久化到永久區
  
  自動生成唯一的 fileId，格式為 yyyy-MM-dd/HH/filename-shortUuid.ext。業務層只需儲存回傳的 fileId，不需關心檔案實際儲存位置。
  
  Specified by:
  
  persist in interface FileStorage
  
  Parameters:
  
  tenantId - 租戶 ID
  
  tempId - 暫存檔案 ID
  
  Returns:
  
  fileId（唯一識別碼，同時也是可讀的路徑格式）
- store
  
  public String store(String tenantId, String filename, InputStream content, String contentType, long size)
  
  Description copied from interface: FileStorage
  
  直接儲存檔案到永久區（跳過暫存）
  
  Specified by:
  
  store in interface FileStorage
  
  Parameters:
  
  tenantId - 租戶 ID
  
  filename - 原始檔名（用於生成 fileId）
  
  content - 檔案內容的 InputStream
  
  contentType - MIME 類型
  
  size - 檔案大小
  
  Returns:
  
  fileId
- getMetadata
  
  public Optional<FileStorage.FileMetadata> getMetadata(String tenantId, String fileId)
  
  Description copied from interface: FileStorage
  
  取得永久區檔案的 Metadata
  
  Specified by:
  
  getMetadata in interface FileStorage
  
  Parameters:
  
  tenantId - 租戶 ID
  
  fileId - 檔案 ID
  
  Returns:
  
  檔案 Metadata，若不存在則回傳 empty
- getInputStream
  
  public InputStream getInputStream(String tenantId, String fileId) throws FileNotFoundException
  
  Description copied from interface: FileStorage
  
  取得永久區檔案的 InputStream
  
  Specified by:
  
  getInputStream in interface FileStorage
  
  Parameters:
  
  tenantId - 租戶 ID
  
  fileId - 檔案 ID
  
  Returns:
  
  InputStream（呼叫端負責關閉）
  
  Throws:
  
  FileNotFoundException - 若檔案不存在
- exists
  
  public boolean exists(String tenantId, String fileId)
  
  Description copied from interface: FileStorage
  
  檢查永久區檔案是否存在
  
  Specified by:
  
  exists in interface FileStorage
  
  Parameters:
  
  tenantId - 租戶 ID
  
  fileId - 檔案 ID
  
  Returns:
  
  是否存在
- delete
  
  public void delete(String tenantId, String fileId)
  
  Description copied from interface: FileStorage
  
  刪除永久區檔案
  
  Specified by:
  
  delete in interface FileStorage
  
  Parameters:
  
  tenantId - 租戶 ID
  
  fileId - 檔案 ID
- getUrl
  
  public String getUrl(String tenantId, String fileId)
  
  本地儲存不支援 URL 存取
  
  檔案下載應由業務層 Controller 實作，以確保權限控管。
  
  Specified by:
  
  getUrl in interface FileStorage
  
  Parameters:
  
  tenantId - 租戶 ID
  
  fileId - 檔案 ID
  
  Returns:
  
  存取 URL（僅雲端儲存支援）
  
  Throws:
  
  UnsupportedOperationException - 永遠拋出此例外
- getStorageType
  
  public String getStorageType()
  
  Description copied from interface: FileStorage
  
  取得儲存類型名稱
  
  Specified by:
  
  getStorageType in interface FileStorage
  
  Returns:
  
  儲存類型（例如 "local", "azure", "s3", "database", "sftp"）

Class LocalFileStorage

Nested Class Summary

Nested classes/interfaces inherited from interface FileStorage

Method Summary

Methods inherited from class Object

Method Details

builder

prepareStaging

completeStagingUpload

getStagedMetadata

getStagedInputStream

existsStaged

deleteStaged

persist

store

getMetadata

getInputStream

exists

delete

getUrl

getStorageType