Authentication 重点文件与方法

重点覆盖身份适配、请求内缓存、登录信息读写和认证扩展。用户接口与权限模型的装配前提见使用与配置，业务角色数据来源见权限与状态扩展。

本页按重点文件查阅方法；表内方法名可打开源码。重载共享的约束写在表前，差异在各行说明。源码链接固定到核对版本，接入前提见快速开始。

ParentGetUtil

源码：ParentGetUtil。

将 ParentAuthenticationLoginUser 接到 Base 的 SessionUserProvider。构造器依赖父认证实现和 SecurityProperty，交给 Spring 注入；不要在业务方法里手动创建第二个实例。

方法 / 重载	用途、参数与返回值	注意事项
ParentGetUtil(ParentAuthenticationLoginUser parentAuthenticationLoginUser, SecurityProperty securityProperty)	保存身份来源与安全配置。	两个依赖需有效，构造器本身不验证登录。
init()	@PostConstruct 将当前实例放入静态 INSTANCE。	生命周期入口，不是刷新用户状态的方法；多容器会共享静态值。
loginUser()	委托父认证层获取当前身份。	实际凭证解析由 AuthenticationLoginUser 完成。
permissionUser()	委托父认证层获取当前权限身份。	不独立查询角色数据库。
loginUser(Long userId)	委托指定用户的身份列表查询。	不会切换当前会话。
permissionUser(Long userId)	委托指定用户的权限身份列表查询。	此入口自身没有目标用户访问校验。
isLoginVerification()	返回 SecurityProperty.loginVerification。	此配置默认 false，与 SessionUserProvider 接口默认 true 不同。

ParentAuthenticationDefaultCacheLoginUser

源码：ParentAuthenticationDefaultCacheLoginUser。

默认请求内身份缓存。缓存保存在当前 request attribute，不是 Store，也不是 Token 生命周期缓存。同一请求中身份数据变化后不会自动刷新已命中对象。

方法 / 重载	用途、参数与返回值	注意事项
ParentAuthenticationDefaultCacheLoginUser(AuthenticationLoginUser authenticationLoginUser, HttpServletRequest request)	绑定身份解析器和请求对象。	由自动配置构造，依赖有效 Servlet 请求。
loginUser()	优先返回请求缓存，未命中委托真实解析器。非 null 结果缓存。	解析为 null 时返回 DefaultLoginUser.DEFAULT，但不缓存该默认值；后续读取可能再次解析。
permissionUser(BaseLoginUser loginUser)	委托权限解析并缓存，空结果返回 DefaultPermissionUser.DEFAULT。	缓存键不含 userId；同一请求先后传不同用户仍可能取第一次的结果。
loginUser(Long userId)	通过 BaseUtil 委托指定用户列表查询。	不走上述请求缓存；真实解析器返回 null 时 BaseUtil 抛业务异常，空列表则原样返回。
permissionUser(Long userId)	委托指定用户权限列表查询。	不缓存到当前用户的 request key。

LoginInfoUtil

源码：LoginInfoUtil。

为登录类型、账号和验证码提供三个独立 request attribute 槽位。构造器接收 HttpServletRequest；只在当前请求内交换数据，不写 Cookie、Token 或会话数据库。

方法 / 重载	用途、参数与返回值	注意事项
LoginInfoUtil(HttpServletRequest request)	创建基于该请求的访问门面。	通常注入 Bean，不保存到后台任务跨请求使用。
type()	返回登录类型的 LoginInfoFunction。	本身不读取类型，也不验证是否属于已支持登录方式。
account()	返回账号槽位访问器。	不查询账号是否存在。
code()	返回验证码槽位访问器。	不发送、比较或一次性消费验证码。

LoginInfoFunction

源码：LoginInfoFunction。

每次访问绑定 request 和 key。此类的 get/set 操作的是 String，不具备加密或校验行为。

方法 / 重载	用途、参数与返回值	注意事项
LoginInfoFunction(HttpServletRequest request, String key)	绑定请求属性名。	直接构造时 key 冲突会覆盖其他属性，优先通过 LoginInfoUtil 获得。
set(String content)	写入 request attribute，返回 void。	不清理其他槽位；Servlet 对 null 的属性语义由请求实现处理。
get()	读取并强制转为 String，未设置时 null。	如果其他代码同 key 写入非字符串，会发生类型转换异常。

已注入 LoginInfoUtil loginInfo 的认证方法中可以这样交换本次请求信息；这些值需由实际登录流程继续验证：

loginInfo.type().set("password");
loginInfo.account().set("demo-account");
String account = loginInfo.account().get(); // demo-account

UserUtil

源码：UserUtil。

直接读取请求凭证并委托指定解析函数，不自动验签或去除 Bearer 前缀。

方法 / 重载	用途、参数与返回值	注意事项
UserUtil(HttpServletRequest request)	保存请求引用。	通常由 Spring 注入。
getLoginUser(String token, GetLoginUserFunction function)	token 为 null 抛“token信息异常”，否则调用 function.get(token) 并返回 BaseLoginUser。	空串不被此方法拒绝；凭证有效性、过期和用户状态由回调负责。
getAuthToken(String space, String key)	space 为 cookie/header/parameter 时读取相应位置的值。无请求上下文或值缺失返回 null。	space 区分字面值，null/其他值抛“token获取位置异常”；返回原始值。

嵌套函数接口 UserUtil.GetLoginUserFunction.get(String token) 由应用实现，输入原始 Token、输出 BaseLoginUser。它不提供默认实现；私有的 Cookie/Header/Parameter 读取方法仅负责选取位置。

PermissionCacheService

源码：PermissionCacheService。

保存权限变更版本，供业务决定何时刷新角色权限。记录内容是 UTC 时钟的毫秒字符串，没有 TTL；只写版本，不主动清除请求内身份缓存。

方法 / 重载	用途、参数与返回值	注意事项
PermissionCacheService(StoreTemplate<String> store)	使用系统 UTC 时钟构造。	自动配置使用隔离的权限命名空间，不要与任意业务缓存混用。
setGlobalTimestamp()	覆盖全局版本，用于菜单、角色等影响全部用户的变更。	毫秒内多次调用可能相同，不是严格单调序列。
getGlobalTimestamp()	读取全局版本字符串，未写入时 null。	本地 Store 的版本仅在本进程有效。
setUserRoleTimestamp(Long userId)	覆盖指定用户角色版本。	userId 必须 >0，否则 IllegalArgumentException；不会删除权限记录。
getUserRoleTimestamp(Long userId)	返回指定用户版本，未设置为 null。	同样要求 userId >0。

RoleHook

源码：RoleHook。

由业务提供角色和模块操作名；继承 BaseSequenceHook.sequence()，默认顺序为 0。注册 Bean 后仍需调用方汇总，接口自身不执行权限拦截。

方法 / 重载	用途、参数与返回值	注意事项
listRoleName(BaseLoginUser loginUser)	返回该身份可用的角色名称集合。	根据可信 userId/client 限定范围；返回空集合表达没有角色，避免 null。
listOperationByModule(BaseLoginUser loginUser, String module)	返回身份在指定模块的操作标识集合。	module 是权限模块标识；需要过滤禁用角色、禁用菜单，不能仅凭绑定记录判定有效。

UserDetailHook

源码：UserDetailHook。

给用户详情响应增加一项自定义信息；继承 sequence() 决定扩展排序。

方法 / 重载	用途、参数与返回值	注意事项
detail(BaseLoginUser loginUser)	返回业务详情对象。	只包含可公开的字段，避免返回 Token 或数据库内部对象。
detailKey()	返回详情对象在响应中的键名。	使用稳定且唯一的业务键；重名如何处理由实际调用方决定。

LoginOperationHook

源码：LoginOperationHook。

定义登录前后的扩展点；此接口没有顺序契约，也不自行触发。具体登录业务负责何时调用。

方法 / 重载	用途、参数与返回值	注意事项
before()	登录前处理，返回 void。	若实现抛异常是否中断登录取决于调用链，不应假设异常被隔离。
after()	登录后的处理，返回 void。	不能据名字推断数据库事务已经提交。

LoginSecurityHook

源码：LoginSecurityHook。

检查特定客户端的登录风险。此组件提供接口，调用和拒绝逻辑由登录业务编排。

方法 / 重载	用途、参数与返回值	注意事项
check(String client, Long userId, ConstantAccount.UserTypeEnum userType, HttpServletRequest request)	接收客户端、用户 ID/类型与请求，返回 LoginSecurityHookEntity。	回调应按实际主体检查，返回对象不等价于自动拒绝登录，需看编排方如何处理。
client()	返回适用客户端数组，默认 null。	默认 null 的覆盖范围由调用方解释，不在接口层自动匹配全部客户端。

UserStatusHook

源码：UserStatusHook。

状态清理 SPI；实现 clear 后由 UserStatusSpringHook 或业务入口显式触发。

方法 / 重载	用途、参数与返回值	注意事项
clear(BaseLoginUser loginUser)	清理该身份关联的应用状态，返回 void。	不默认删除 Token/权限版本，需由实现明确清理范围。

UserStatusSpringHook

源码：UserStatusSpringHook。

构造器接收已注入的 Hook 列表；按列表实际顺序同步执行，不自动按 BaseSequenceHook 排序。

方法 / 重载	用途、参数与返回值	注意事项
UserStatusSpringHook(List<UserStatusHook> userStatusHookList)	保存清理器列表并记录注册日志。	列表及元素应非 null。
clear(BaseLoginUser loginUser)	逐个调用所有清理器的 clear。	任一抛异常会终止后续执行；无重试、事务或异常隔离。