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(纯内存模式)。它决定两件事:getIsRecordIndex()------是否维护"用户 → Key 列表"索引(默认true);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));
}
}
三个设计要点:
- 按命名空间懒加载、缓存模板 :
getTemplate(namespace)用computeIfAbsent保证每个 namespace 只创建一个SaApiKeyTemplateDatabase,既隔离数据(不同 namespace 互不可见),又不重复建对象。 afterSingletonsInstantiated全局替换 :在所有单例 Bean 创建完成后,把SaApiKeyManager的全局模板与数据加载器 换成数据库实现。此后SaApiKeyUtil、@SaCheckApiKey等"请求期校验"入口读到的 Key 数据同样来自数据库,与后台管理写入的数据是同一份。- 默认命名空间常量 :框架在
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 控制器与转换器的源码级拆解,看"创建 → 更新 → 查询 → 删除"每一步是如何在数据库与缓存之间保持一致性的。