091-功能模块-API Key 管理功能模块解析:feature-sa-token 架构设计与数据库持久化

091-功能模块-API Key 管理功能模块解析:feature-sa-token 架构设计与数据库持久化

本文章代码: gitee , gitcode , github

1. 引言

API Key(应用程序编程接口密钥)是机器与机器之间最常用的身份凭证:调用方拿着一个形如 AK-xxxxxxxx 的密钥访问开放接口,服务端据此识别"谁在调用、有什么权限、何时过期"。

在 tutorials4j 中,API Key 的能力被拆成了两层:

  • 插件层(能力提供方) :sa-token-apikey 是 Sa-Token 官方插件,负责 API Key 的生成、校验、过期管理、Scope 授权等运行时语义;
  • 功能层(业务落地方) :framework/framework-feature/feature-sa-token 把插件的"内存态"能力改造成 "数据库持久化 + REST 管理接口 + 演示页面" 的完整功能模块,即本文主角。

为什么需要"数据库化"?插件默认把 API Key 保存在 Sa-Token 的缓存中(内存/Redis),重启即丢、无法按用户分页检索、难以做审计与后台管理。feature-sa-token 通过 JPA 持久化 + 覆写模板方法 + 替换全局数据加载器 三招,让 API Key 变成"可创建、可查询、可更新、可回收"的一等业务资源。

本文(上篇)聚焦模块的架构骨架与持久化设计 ;下篇(092)深入创建/更新/查询/删除的全生命周期实现与一致性细节。


2. 模块全景:位置、依赖与包结构

2.1 在聚合工程中的位置

feature-sa-token 隶属于 framework-feature(功能模块),与签到(feature-sign-in)、任务(feature-schedule)、文件存储(feature-file-storage-spring)等并列,最终被 feature-spring-boot-starter 聚合进业务工程:

r 复制代码
framework-feature (父POM)
├── feature-core
├── feature-sign-in
├── feature-schedule
├── feature-file-storage-spring
├── feature-sa-token        ← 本文
└── feature-spring-boot-starter   # 聚合以上全部 feature 并提供 FeatureAutoConfiguration

2.2 直接依赖(pom.xml)

依赖 提供的能力
feature-core 功能模块基础(EnableFeature 等通用约定)
oauth-sa-token Sa-Token 与框架的桥接:登录会话拦截、异常转 Result、日志桥接等
data-hibernate JPA 基础设施:BaseEntity(雪花主键/乐观锁/审计)、BaseRepository、BaseService

其中 oauth-sa-token 又传递引入 sa-token-spring-boot3-starter 与 sa-token-apikey 插件------这正是 API Key 运行时语义的来源。

2.3 包结构与职责

less 复制代码
feature-sa-token/src/main/java/tutorials4j/framework/feature/satoken/
├── annotation
│   └── EnableSaTokenFeature.java        // 一键启用注解:@Import 自动配置
├── autoconfigure
│   └── SaTokenFeatureConfiguration.java  // 组件扫描 + JPA 仓库/实体 + 模板工厂 Bean
├── model                               // 领域对象
│   ├── ApiKeyEntity.java                // JPA 实体:feat_api_key 表
│   ├── ApiKeyCreateModel / ApiKeyUpdateModel / ApiKeyQuery / ApiKeySpecification
│   └── ValidGroup.java                  // 校验分组:AdminGroup / UserGroup
├── component                           // 核心组件
│   ├── ApiKeyComponent.java             // 业务编排:创建/更新/列表/删除
│   ├── SaApiKeyTemplateDatabase.java    // 覆写模板:数据库读写模板
│   ├── SaApiKeyDataLoaderDatabase.java  // 数据加载器:缓存未命中时回源 DB
│   ├── SaApiKeyTemplateFactory.java     // 按命名空间缓存模板的工厂
│   └── ApiKeyModelConverter.java        // ApiKeyModel ↔ ApiKeyEntity 双向转换
├── service                             // 数据访问层
│   ├── ApiKeyRepository.java            // Spring Data JPA 仓库
│   └── ApiKeyService.java               // 分页查询服务
└── web                                 // REST 接口层
    ├── ApiKeyController.java            // 管理端(可指定 loginId)
    ├── CurrentApiKeyController.java     // 当前登录用户(从会话取 loginId)
    └── QueryApiKeyController.java       // 查询端(分页/按 ID)

分层非常规整:model 定义数据、component 承载业务、service 访问 DB、web 暴露 REST,每层只依赖下一层,便于单测与替换。


3. 背景知识:Sa-Token API Key 插件的"内存态"语义

要理解模块为何要覆写若干方法,先看插件的默认设计(sa-token-apikey v1.46.0 源码):

  • ApiKeyModel :API Key 的领域对象,字段包括 title / intro / apiKey / loginId / createTime / expiresTime / isValid / scopes / extraData;
  • SaApiKeyTemplate :操作模板。saveApiKey 把模型写入 Sa-Token 缓存(Key 形如 ${tokenName}:${namespace}:${apiKey},TTL 等于剩余有效期);getApiKey 遵循"先缓存、后数据库、命中后回填缓存"的路径;
  • SaApiKeyDataLoader :数据库加载器接口,默认实现返回 null(纯内存模式)。它决定两件事:
    1. getIsRecordIndex()------是否维护"用户 → Key 列表"索引(默认 true);
    2. getApiKeyModelFromDatabase(namespace, apiKey)------缓存未命中时从数据库取回模型。
  • SaApiKeyManager :全局组件管理器,持有配置、模板与加载器的静态单例 ,SaApiKeyUtil、@SaCheckApiKey 注解都经由它工作。

默认实现依赖缓存 + 索引,因此 getApiKeyList(loginId)、deleteApiKeyByLoginId(loginId) 这类"按用户枚举/批量回收"能力只有开启索引才可用,而索引与缓存一样是易失的。这正是 feature-sa-token 的改造点:数据库为唯一事实来源,缓存只做读加速。


4. 启用与自动装配:从注解到 Bean

4.1 一键启用注解

java 复制代码
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Import(SaTokenFeatureConfiguration.class)
public @interface EnableSaTokenFeature {}

使用方在配置类上标注即可(示例工程 SaTokenConfig 就是这么做的):

java 复制代码
@EnableSaTokenFeature
@Configuration
@Profile("sa-token")
@ComponentScan(basePackages = {"tutorials4j.framework.examples.satoken"})
public class SaTokenConfig {}

4.2 自动配置类

SaTokenFeatureConfiguration 把三件"容器接入"一次办齐:

java 复制代码
@Configuration(proxyBeanMethods = false)
@ComponentScan(
    basePackages = {
      "tutorials4j.framework.feature.satoken.service",
      "tutorials4j.framework.feature.satoken.component",
      "tutorials4j.framework.feature.satoken.web"
    })
@EnableJpaRepositories(basePackages = {"tutorials4j.framework.feature.satoken.service"})
@EntityScan(basePackages = {"tutorials4j.framework.feature.satoken.model"})
public class SaTokenFeatureConfiguration {
  @Bean
  @ConditionalOnMissingBean
  SaApiKeyTemplateFactory saApiKeyTemplateFactory(ApiKeyRepository apiKeyRepository) {
    return new SaApiKeyTemplateFactory(apiKeyRepository);
  }
}
  • @ComponentScan 把 component / service / web 三包的 Bean(含 ApiKeyComponent、三个 Controller、Repository 之外的组件)纳入容器;
  • @EnableJpaRepositories + @EntityScan 让 ApiKeyRepository 与 ApiKeyEntity 参与 JPA 管理,表结构可由 ddl-auto 自动维护;
  • SaApiKeyTemplateFactory 以 @ConditionalOnMissingBean 装配并注入 ApiKeyRepository------使用者可以声明自己的工厂覆盖默认实现。

说明:模块的启用是显式注解驱动的(而不是 Starter 全自动),这样业务方可以自主决定是否引入这组 API Key 管理能力,避免与自己的 Sa-Token 配置冲突。


5. 实体与持久化设计

5.1 表结构与字段

ApiKeyEntity 对应数据表 feat_api_key:

java 复制代码
@Data
@Entity
@Table(
    name = "feat_api_key",
    indexes = {@Index(name = "feat_api_key_idx0", columnList = "namespace, loginId")},
    uniqueConstraints = {@UniqueConstraint(name = "feat_api_key_idx1", columnNames = "api_key")})
@EqualsAndHashCode(callSuper = false)
public class ApiKeyEntity extends BaseEntity {

  @Column private String namespace;
  @Column private String title;
  @Column private String intro;
  @Column(nullable = false) private String apiKey;
  @Column(nullable = false) private String loginId;
  @Column private Long expiresTime;
  @Column private Boolean isValid;

  @Column
  @Convert(converter = ListConverter.class)
  private List<String> scopes = new ArrayList<>();

  @Column
  @Convert(converter = HashMapConverter.class)
  private Map<String, String> extraData = new HashMap<>();
}
设计点 说明
业务字段 namespace(命名空间隔离)、apiKey(密钥明文)、loginId(归属账号)、title/intro(备注)、expiresTime(13 位毫秒时间戳,-1 永不过期)、isValid(禁用标记)
复杂类型列 scopes 经 ListConverter 存为 JSON 文本;extraData 经 HashMapConverter 存为 JSON 文本,读取时还原(框架统一用 Gson),避免为 KV 扩展信息建一堆列
复合索引 (namespace, loginId)------支撑"某用户在某命名空间下的 Key 列表/批量删除"查询
唯一约束 api_key 全局唯一------API Key 本身就是身份,天然不可重复
继承字段 来自 BaseEntity:雪花算法 String 主键、@Version 乐观锁、createDate/lastModifiedDate/createBy/lastModifiedBy 审计(AuditingEntityListener 自动填充)

ApiKeyModel(插件模型)的 createTime 与实体的审计字段是一一对应的:入库前由转换器把 13 位毫秒时间戳写入实体的 createDate,读回时再还原成毫秒。

5.2 仓库与服务层

ApiKeyRepository 继承框架的 BaseRepository(组合 JpaRepository + JpaSpecificationExecutor),按使用场景定义了四个查询与一个批量删除:

java 复制代码
public interface ApiKeyRepository extends BaseRepository<ApiKeyEntity, String> {
  List<ApiKeyEntity> findByNamespaceAndLoginId(String namespace, String loginId);
  Optional<ApiKeyEntity> findByNamespaceAndApiKeyAndLoginId(String namespace, String apiKey, String loginId);
  Optional<ApiKeyEntity> findByNamespaceAndApiKey(String namespace, String apiKey);
  Optional<ApiKeyEntity> findByApiKey(String apiKey);
  long deleteByNamespaceAndLoginId(String namespace, String loginId);
}

ApiKeyService 仅做一件事------把动态查询对象翻译成分页查询:

java 复制代码
public Page<ApiKeyEntity> findByPage(ApiKeyQuery query, Pageable pageable) {
  return apiKeyRepository.findAll(query.buildSpecification(), pageable);
}

5.3 动态查询(Specification 模式)

ApiKeyQuery 支持 6 个可选条件:命名空间、标题(模糊)、loginId、有效状态、创建时间起止;每个条件由 ApiKeySpecification 的静态工厂构建,空条件自动退化为恒真条件(cb.conjunction()),最后用 reduce(Specification::and) 组合:

java 复制代码
public Specification<ApiKeyEntity> buildSpecification() {
  List<Specification<ApiKeyEntity>> specList = new ArrayList<>();
  specList.add(ApiKeySpecification.titleLike(title));
  specList.add(ApiKeySpecification.namespaceEqual(namespace));
  specList.add(ApiKeySpecification.loginIdEqual(loginId));
  specList.add(ApiKeySpecification.isValidEqual(isValid));
  specList.add(ApiKeySpecification.createTimeBegin(createTimeBegin));
  specList.add(ApiKeySpecification.createTimeEnd(createTimeEnd));
  return specList.stream()
      .filter(Objects::nonNull)
      .reduce(Specification::and)
      .orElse((root, query, cb) -> cb.conjunction());
}

标题模糊匹配复用框架的 JPAUtils.like(),统一产出 %xxx% 格式。整套逻辑与 087 篇的文件存储查询一脉相承,是 framework 的标准查询套路。

设计提示:创建时间区间谓词直接引用实体属性 createTime。若后续基础实体字段命名演进(如改为审计字段 createDate),请同步调整此处谓词路径,避免运行时"属性找不到"------这也是把"查询条件"与"实体字段"解耦到 Specification 工厂里的意义:改一处即可全局生效。


6. 命名空间与模板工厂:多实例隔离的基石

SaApiKeyTemplateFactory 是"按命名空间取模板"的门面,并实现了 SmartInitializingSingleton 在容器就绪后替换 Sa-Token 全局组件:

java 复制代码
public class SaApiKeyTemplateFactory implements SmartInitializingSingleton {
  private final ConcurrentMap<String, SaApiKeyTemplate> cacheMap = new ConcurrentHashMap<>();
  private final ApiKeyRepository apiKeyRepository;

  public SaApiKeyTemplate getDefaultTemplate() {
    return cacheMap.computeIfAbsent(
        SaTokenOauthConsts.DEFAULT_NAMESPACE, (namespace) -> SaApiKeyManager.getSaApiKeyTemplate());
  }

  public SaApiKeyTemplate getTemplate(String namespace) {
    Assert.hasText(namespace, "namespace is not be null or empty");
    return cacheMap.computeIfAbsent(namespace, this::createTemplate);
  }

  private SaApiKeyTemplate createTemplate(String namespace) {
    return new SaApiKeyTemplateDatabase(apiKeyRepository, namespace);
  }

  @Override
  public void afterSingletonsInstantiated() {
    // 用数据库模板与加载器替换 Sa-Token 全局单例
    SaApiKeyManager.setSaApiKeyTemplate(new SaApiKeyTemplateDatabase(apiKeyRepository));
    SaApiKeyManager.setSaApiKeyDataLoader(new SaApiKeyDataLoaderDatabase(apiKeyRepository));
  }
}

三个设计要点:

  1. 按命名空间懒加载、缓存模板 :getTemplate(namespace) 用 computeIfAbsent 保证每个 namespace 只创建一个 SaApiKeyTemplateDatabase,既隔离数据(不同 namespace 互不可见),又不重复建对象。
  2. afterSingletonsInstantiated 全局替换 :在所有单例 Bean 创建完成后,把 SaApiKeyManager 的全局模板与数据加载器 换成数据库实现。此后 SaApiKeyUtil、@SaCheckApiKey 等"请求期校验"入口读到的 Key 数据同样来自数据库,与后台管理写入的数据是同一份。
  3. 默认命名空间常量 :框架在 SaTokenOauthConsts 中定义了 DEFAULT_NAMESPACE = "_master_apikey_",管理接口与 DTO 在不指定 namespace 时使用它;而 Sa-Token 插件自身的默认命名空间是 "apikey"。二者都可以在业务上对齐(例如页面/接口显式传同一个 namespace),保证"在哪建、就在哪验"。

生产提示:若你的开放接口需要"一套 Key 走多个业务",请显式给每个业务命名空间并保持管理接口与校验注解(@SaCheckApiKey 等)使用同一 namespace;多租户场景甚至可以把 tenantId 拼进 namespace 进一步隔离。


7. 总结与展望

上篇可以提炼出 feature-sa-token 的四条设计主线:

  • 只做"落地层",不做"语义层":生成、过期、Scope 校验等交给 Sa-Token 插件,模块只解决"存哪里、怎么管";
  • 数据库为唯一事实来源:JPA 实体 + 仓库 + 动态查询,让 API Key 可检索、可审计、可持久;
  • 模板 + 加载器双钩子接入插件 :覆写 SaApiKeyTemplate 四个生命周期方法 + 实现 SaApiKeyDataLoader,并利用 SmartInitializingSingleton 时机替换全局单例,改动面最小、无侵入;
  • 命名空间 + 工厂缓存:一套代码支持任意 namespace 的 Key 池,天然适配多业务/多租户。

下篇将进入 ApiKeyComponent、SaApiKeyTemplateDatabase、三个 REST 控制器与转换器的源码级拆解,看"创建 → 更新 → 查询 → 删除"每一步是如何在数据库与缓存之间保持一致性的。

相关推荐
行百里er22 分钟前
【Spring Insight 技术分享】如何给 AI 接口调用做滑动窗口限流
spring boot·后端·spring cloud
有个傻瓜27 分钟前
一次「查到别家门店订单」的线上事故:Spring Boot 3 + MyBatis-Plus 多租户隔离踩坑复盘
spring boot·mybatis-plus·多租户·ruoyi-vue-plus·线上故障复盘
学长毕设15 小时前
基于SpringBoot智慧养老服务平台设计与实现-附源码
java·spring boot·后端
千寻技术帮17 小时前
10454_基于Springboot的企业购销链管理系统
spring boot·mysql·vue·毕业设计·进销存
Forget the Dream18 小时前
Spring AI 2.0 系列(二):第一个 ChatClient——从注入到一次完整调用
java·人工智能·spring boot·ai·springai
她的男孩20 小时前
设计器能拖抄送,一点发布却报 flowable-servicetask-invalid-type:Forge Admin 部署前改写节点属性
spring boot·低代码·工作流引擎
学长毕设2 天前
基于SpringBoot社区快递驿站物流配送系统-附源码
java·spring boot·后端
雾隐隐o2 天前
优搭校园 01|项目概览、技术选型与初始化
spring boot·mysql·vue
雪芽蓝域zzs2 天前
第 10 章:Maven 打包
spring boot