跳到主要内容

API 分层说明

分层结构​

1. API 基础抽象​

位置：

  • IGeekFan.FreeKit.Infrastructure/Application/KitApiControllerBase.cs

职责：

  • 提供 ApiController 基线
  • 提供控制器公共基础能力
  • 不包含鉴权策略
  • 不包含业务语义

2. 通用鉴权 API 抽象​

位置：

  • IGeekFan.FreeKit.Infrastructure/Application/FreeKitController.cs

职责：

  • 继承 KitApiControllerBase
  • 提供默认 JWT 鉴权语义
  • 作为需要统一鉴权策略的业务控制器基类

3. 业务域 API 抽象​

位置示例：

  • src/Services/Identity/FreeKit.Identity/Controllers/IdentityTokenControllerBase.cs

职责：

  • 放置特定业务域的控制器共性
  • 承担该业务域专有 API 能力

当前 IdentityTokenControllerBase 负责：

  • token 写入 cookie

使用约定​

使用 KitApiControllerBase​

适用于：

  • 只需要标准 API 控制器能力
  • 不需要默认 JWT 鉴权
  • 不依赖特定业务域能力

使用 FreeKitController​

适用于：

  • 需要默认 JWT 鉴权
  • 需要通用 API 控制器基类
  • 不需要身份域专有行为

使用业务域控制器基类​

适用于：

  • 控制器包含明确的业务域专属行为
  • 该行为不应进入全局 API 抽象

当前示例​

Identity 域​

以下控制器使用 IdentityTokenControllerBase：

  • AccountController
  • TenantController
  • OAuth2Controller
  • TwoStepVerificationController

非业务化 API​

以下控制器直接使用 KitApiControllerBase：

  • FreeKit.MessageHandler.Host/Controllers/SyncController.cs

分层原则​

  1. 最上层只放所有 API 都可能复用的抽象
  2. 中间层放跨业务通用的 API 约定
  3. 下层放明确属于业务域的 API 能力
  4. 业务语义不进入全局控制器基类