Class KnoluxS3OperationSpec

java.lang.Object
com.knolux.s3.KnoluxS3OperationSpec
public final class KnoluxS3OperationSpec extends Object
動態 S3 操作規格，用於執行期間從請求 Payload 組裝完整的 S3 操作參數。

靜態 vs 動態模式

  • 靜態模式 — 直接注入 KnoluxS3Template 使用 Properties 預設值， 無需建立此物件。
  • 動態模式 — 從 REST API body 或 Message Queue Payload 取得欄位， 透過
    invalid reference 
    #builder()
    組裝，必須呼叫 mergeDefaults(KnoluxS3Properties) 填補 null 欄位並鎖定部署級別設定。

欄位分類

  • 動態欄位（endpoint、region、accessKey、 secretKey、bucket、key）— payload 可覆寫； null 時由 mergeDefaults(KnoluxS3Properties) 以 Properties 填補。
  • 部署級別設定（forcePathStyle、removePathPrefix、 pathPrefix、trustSelfSigned）— 一律以 Properties 為準， 防止呼叫端透過 payload 繞過部署配置。

MQ Handler 使用範例

KnoluxS3OperationSpec spec = KnoluxS3OperationSpec.builder()
    .endpoint(message.getS3Endpoint())   // null 時 fallback 至 Properties
    .region(message.getS3Region())
    .accessKey(message.getSecretId())    // SeaweedFS 稱為 secretId
    .secretKey(message.getSecretKey())
    .bucket(message.getBucket())
    .key(message.getObjectKey())
    .build()
    .mergeDefaults(s3Properties);        // 必填；填補 null 並鎖定部署設定

s3Template.download(spec, AsyncResponseTransformer.toBytes());

REST API 使用範例

@PostMapping("/download")
public ResponseEntity<byte[]> download(@RequestBody S3DownloadRequest req) {
    KnoluxS3OperationSpec spec = KnoluxS3OperationSpec.builder()
        .endpoint(req.endpoint())
        .bucket(req.bucket())
        .key(req.key())
        .accessKey(req.accessKey())
        .secretKey(req.secretKey())
        .build()
        .mergeDefaults(s3Properties);

    byte[] content = s3Template.download(spec, AsyncResponseTransformer.toBytes())
        .join()
        .asByteArray();
    return ResponseEntity.ok(content);
}
See Also:

  • Constructor Details

    • KnoluxS3OperationSpec

      public KnoluxS3OperationSpec()

  • Method Details

    • mergeDefaults

      public KnoluxS3OperationSpec mergeDefaults(KnoluxS3Properties defaults)
      以靜態 KnoluxS3Properties 填補 null 欄位，回傳完整 spec。

      動態欄位規則：若 payload 已提供非 null 值則保留， 否則以 defaults 對應欄位填補。

      部署級別設定規則：forcePathStyle、removePathPrefix、 pathPrefix、trustSelfSigned 一律以 defaults 為準， 防止呼叫端透過 payload 覆寫部署設定（潛在安全風險）。

      Parameters:
      defaults - 注入的 KnoluxS3Properties，不可為 null
      Returns:
      所有欄位均已填滿的新 spec
      Throws:
      NullPointerException - 若 defaults 為 null
      IllegalStateException - 若 merge 後 bucket 或 key 仍為 null