Class TenantContext

java.lang.Object
io.leandev.appfuse.security.tenant.TenantContext
public final class TenantContext extends Object

租戶上下文工具類

提供取得當前租戶 ID 的靜態方法。租戶 ID 的解析邏輯由 TenantIdResolver 處理，支援多種認證方式。

配置方式（擇一）：

方式 1：使用預設配置（支援 OAuth2 JWT、本地 JWT、Basic Auth）

TenantContext.configureWithDefaults();

方式 2：自訂 resolver

TenantContext.configure(CompositeTenantIdResolver.builder()
    .withJwtClaim("tenant_id")
    .withUserDetails()
    .build());

使用方式：

// 取得租戶 ID（若無法取得則拋出異常）
String tenantId = TenantContext.getCurrentTenantId();

// 嘗試取得租戶 ID（若無法取得則返回 null）
String tenantId = TenantContext.getTenantIdOrNull();

// 檢查是否有租戶上下文
if (TenantContext.hasTenantContext()) {
    // ...
}

測試用途：

@BeforeEach
void setUp() {
    TenantContext.setCurrentTenantId("test-tenant");
}

@AfterEach
void tearDown() {
    TenantContext.clear();
}
See Also:

  • Method Details

    • configure

      public static void configure(TenantIdResolver tenantIdResolver)

      配置租戶 ID 解析器

      應用程式啟動時應呼叫此方法配置解析器。

      Parameters:
      tenantIdResolver - 租戶 ID 解析器

    • configureWithDefaults

      public static void configureWithDefaults()

      使用預設配置

      預設支援：

      • OAuth2 JWT（從 Jwt principal 的 claims 取得）
      • 本地 JWT（從 authentication.details 的 Claims 取得）
      • Basic Auth / Form Login（從 TenantAwareUserDetails 取得）

    • configureWithDefaults

      public static void configureWithDefaults(String claimName)
      使用預設配置，指定 claim 名稱
      Parameters:
      claimName - JWT 中的租戶 ID claim 名稱

    • getCurrentTenantId

      public static String getCurrentTenantId()
      取得當前租戶 ID
      Returns:
      租戶 ID
      Throws:
      IllegalStateException - 如果無法取得租戶 ID

    • getTenantIdOrNull

      public static String getTenantIdOrNull()
      嘗試取得當前租戶 ID（不拋出異常）
      Returns:
      租戶 ID，若無法取得則返回 null

    • hasTenantContext

      public static boolean hasTenantContext()
      檢查當前是否有租戶上下文
      Returns:
      true 如果有租戶上下文

    • setCurrentTenantId

      public static void setCurrentTenantId(String tenantId)

      手動設定當前租戶 ID

      警告：此方法主要用於測試或系統內部操作（如排程任務）。 正常的 HTTP 請求應透過認證機制自動解析租戶 ID。

      Parameters:
      tenantId - 租戶 ID

    • clear

      public static void clear()

      清除當前租戶 ID

      在測試結束或請求結束時應呼叫此方法清除 ThreadLocal。

    • runAs

      public static void runAs(String tenantId, Runnable action)

      在指定租戶上下文中執行動作

      此方法會在執行前設定租戶 ID，執行後自動清除。 適用於排程任務或系統內部操作。

      Parameters:
      tenantId - 租戶 ID
      action - 要執行的動作

    • callAs

      public static <T> T callAs(String tenantId, Callable<T> action) throws Exception

      在指定租戶上下文中執行動作並返回結果

      此方法會在執行前設定租戶 ID，執行後自動清除。 適用於排程任務或系統內部操作。

      Type Parameters:
      T - 返回類型
      Parameters:
      tenantId - 租戶 ID
      action - 要執行的動作
      Returns:
      動作的執行結果
      Throws:
      Exception

    • supplyAs

      public static <T> T supplyAs(String tenantId, Supplier<T> supplier)

      在指定租戶上下文中執行動作並返回結果（不拋出 checked exception）

      此方法會在執行前設定租戶 ID，執行後自動清除。 適用於不需要處理 checked exception 的場景。

      Type Parameters:
      T - 返回類型
      Parameters:
      tenantId - 租戶 ID
      supplier - 要執行的動作
      Returns:
      動作的執行結果