外观
Base 重点文件与方法
重点覆盖响应构造、会话身份、任务执行以及请求读取。HTTP 协议和默认 Bean 见使用与配置，线程池配置见上下文与异步任务。
本页按重点文件查阅方法；表内方法名可打开源码。重载共享的约束写在表前，差异在各行说明。源码链接固定到核对版本，接入前提见快速开始。
R
源码：R。
Controller 中使用的静态响应工厂。普通 success 新建 ResultModel，不直接设置 HTTP 状态。TRUE / FALSE 是共享可变实例，不用于每次请求的响应。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| success() | 返回 data 未赋值的成功 ResultModel<T>。 | 不是 boolean true；需要业务数据时传 data。 |
| success(T data) | 新建成功模型并设置 data。 | data=false 仍是成功响应；ResponseMessage/UpdateModel 实参会优先选专用重载。 |
| success(T data, String message) | 新建成功模型并替换展示消息。 | 不会改变默认业务码。 |
| success(ResponseMessage responseCode) | 用消息对象构造业务码和消息。 | 即使传失败码，success 仍先设 true。 |
| success(ResponseMessage responseCode, T data) | 指定业务码、消息及数据。 | 失败响应还需明确 setSuccess(false)。 |
| success(UpdateModel<T> model) | 按 model.flag 选择结果。 | flag=null 会拆箱失败；false 分支的 success 布尔值不能仅凭业务码推断。 |
| fail(String message) | 直接抛 BusinessSimpleException，默认码 E0001。 | 虽声明返回 ResultModel<T>，实际上没有返回失败对象。 |
| resolveForJson(String content, Class<T> clazz) | Fastjson2 读取 data，再恢复外层 code、message、success、traceId、t。 | t 必须符合 yyyy-MM-dd HH:mm:ss，缺失或格式不合法会失败。 |
| resolveForJson(String content, Function<JSONObject,T> function) | 把完整 JSONObject 交给 function 取得 data。 | 回调异常直接传播；不是任意远端 JSON 的容错适配器。 |
ResultModel
源码：ResultModel。
统一数据响应。data() 与 Lombok getData() 读取同一字段；setData(T) 可链式设置，普通字段 setter 不重新判断业务是否成功。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| ResultModel() | 默认成功码与消息，data=null。 | 构造时冻结当前时间和 MDC TraceId。 |
| ResultModel(T t) | 成功响应，t 参数是业务数据。 | 参数名 t 不代表响应时间字段。 |
| ResultModel(T t, String message) | 成功数据与自定义消息。 | 仅替换 message。 |
| ResultModel(ResponseMessage responseCode) | 从消息对象读取 code/message。 | responseCode 不能 null；布尔标识初始化 true。 |
| ResultModel(ResponseMessage responseCode, T t) | 指定消息对象和 data。 | 不根据消息码推导 success。 |
| ResultModel(Boolean flag, T t) | flag=true 使用 FAILURE；flag=false 才写成功码与 data。 | 此构造器方向与一般预期相反；null 拆箱失败，优先使用 R 工厂。 |
| ResultModel(UpdateModel<T> model) | flag=true 取成功数据；false 用 OPERATION_FAILURE 或自定义错误文本。 | 失败分支不写 data；success 仍可能 true，详见使用与配置。 |
| data() | 返回 T，等价于读取 data 字段。 | 没有复制或校验，可能 null。 |
BaseResponseModel
响应基类，Lombok 提供无参构造及普通字段 get/set。无参构造不设置业务码；通常由 ResultModel 的构造器完成初始化。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| BaseResponseModel(String code, String message) | 设置文本、当前本地时间、success=true 和当前 MDC TraceId。 | 不通过消息覆盖缓存查找文案。 |
| BaseResponseModel(ResponseMessage responseCode) | 委托 responseCode(...) 初始化。 | 消息对象不可 null。 |
| responseCode(ResponseMessage responseCode) | 重设 code/message/t/traceId，并将 success 改为 true。 | 若调用前标为失败，该标识会被覆盖。 |
| content(String code, String message) | 直接重设码和文本，同时更新时间和 TraceId。 | 同样重设 success=true；不是仅修改两段字符串。 |
以下代码放入 Controller 方法；import 为 com.own.component.base.model.R、com.own.component.base.model.ResultModel。
java
ResultModel<String> result = R.success("ready");
result.setCode("DEMO_REJECTED");
result.setMessage("当前记录不能操作");
result.setSuccess(false); // 最后明确失败，避免初始化逻辑覆盖
return result;SessionUserProvider
Base 与身份来源的接口。应用提供唯一可选择的 Provider；Base 本身没有默认身份来源。指定 userId 的方法只是查询契约，不自动验证调用者能否访问该用户。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| loginUser() | 提供当前 BaseLoginUser；未登录允许返回 null。 | 实现负责校验凭证，不可直接信任客户端 userId。 |
| permissionUser() | 提供当前 BasePermissionUser。 | Base 不负责加载角色或操作权限。 |
| loginUser(Long userId) | 查询指定用户的登录身份列表，默认空列表。 | 如需实现应说明会话/客户端范围；返回值不是当前会话切换。 |
| permissionUser(Long userId) | 查询指定用户权限身份列表，默认空列表。 | 不会顺便调用 loginUser(userId)。 |
| isLoginVerification() | 默认 true，决定取当前用户时是否拒绝匿名。 | 不会改变显式 checkLogin 的规则。 |
SessionUserUtil
源码：SessionUserUtil。
静态读取入口；请求覆盖值优先于 Provider。没有 Provider 时，读取可能抛 IllegalStateException，即使 checkLogin=false 也一样。身份检查失败抛 U0009。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| isLogin() | 读取 getLoginUser(false)，检查非 null 且 isLogin()。 | 不是“任何异常都转换 false”。 |
| checkLogin() | 未登录直接抛业务异常，成功返回 void。 | 即使 Provider 关闭自动校验，此显式检查仍执行。 |
| getLoginUser() | 等价于 getLoginUser(true)。 | Provider 是否启用校验会影响匿名时抛异常还是返回 null。 |
| getLoginUser(boolean checkLogin) | 优先读取请求覆盖用户，否则访问 Provider。 | checkLogin=false 仅跳过登录校验，不生成匿名对象。 |
| getPermissionUser() | 等价于 getPermissionUser(true)。 | 覆盖身份必须实现 BasePermissionUser 才会命中权限覆盖路径。 |
| getPermissionUser(boolean checkLogin) | 读取当前权限身份并按策略校验。 | 普通 BaseLoginUser 覆盖不会替换 Provider 的权限身份。 |
| loginUser(Long userId) | 委托 Provider 查询指定用户的身份列表。 | 不注入或替换当前用户。 |
| permissionUser(Long userId) | 委托指定用户权限查询。 | 调用者自行验证目标用户访问权。 |
| setLoginUser(BaseLoginUser loginUser) | 设置当前 Servlet request attribute。 | 非 Servlet 上下文抛异常；不生成 Token，不写持久化会话。 |
| clearLoginUser() | 移除本请求的身份覆盖，无上下文则无操作。 | 不是退出登录，也不会恢复更早的一层覆盖。 |
ExecutorUtil
源码：ExecutorUtil。
注入默认 customAsyncExecutor 后提交任务。默认装饰器复制 MDC 并共享 RequestAttributes 引用，不传播数据库事务；请求结束后的任务请显式传入独立业务参数。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| ExecutorUtil(ThreadPoolTaskExecutor customAsyncExecutor) | 以传入线程池构造门面。 | 通常直接注入自动配置的 ExecutorUtil，手动线程池的装饰器由应用负责。 |
| get(Future<T> future) | 阻塞直到结果，返回 T。 | 中断时恢复中断标记并包装 RuntimeException；ExecutionException 也包装。 |
| get(Future<T> future, long timeout, TimeUnit unit) | 在指定单位和时长内等待结果。 | 超时抛 BusinessSimpleException，不自动 cancel；参数遵循 Future.get。 |
| newVirtualThreadPerTaskExecutor() | 创建每任务一个虚拟线程的 ExecutorService。 | 调用者负责 close；无默认 MDC/request 装饰，不等价于实例池。 |
| execute(Runnable runnable) | 提交无返回值任务，相当于 execute(true, runnable)。 | 任务拒绝或任务中异常按线程池策略处理。 |
| execute(boolean condition, Runnable runnable) | condition=false 时跳过，否则提交。 | 默认饱和策略可能在当前线程执行，不能保证总是异步。 |
| submit(Callable<T> task) | 提交并返回 Future<T>，由调用方等待或取消。 | 不自动等待，不自动续签身份。 |
静态 VIRTUAL_THREAD_PER_TASK_EXECUTOR 是共享执行器，任意调用方关闭它会影响其他使用者。实例池、共享虚拟池和新建虚拟池的资源所有权不同，见上下文与异步任务。
RequestUtil
源码：RequestUtil。
操作真实 Servlet 请求；不是可重复读请求包装器。请求参数、Cookie 和 Header 可能包含敏感信息，调用方只提取业务需要的字段。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| header(HttpServletRequest request) | 返回 Header 名称到单个值的 Map。 | 重复 Header 不保留所有值，request 不能 null。 |
| headerForDecode(HttpServletRequest request) | 对每个值执行 URI 解码后返回 Map。 | 单个转换异常记录日志并跳过，不保证结果完整。 |
| header(HttpServletRequest request, Function<String,String> valueFunction) | 按自定义函数转换每个 Header 值。 | 回调逐值执行，异常不会中断整个遍历。 |
| cookies(HttpServletRequest request) | 返回名称到值 Map，无 Cookie 时为空。 | 同名 Cookie 后值覆盖前值，不包含 Path 等属性。 |
| body(ServletRequest request) | 按 UTF-8 读取并连接所有文本行，返回 String。 | 关闭输入流并丢失原换行；IOException 返回空串。不可用于字节级签名校验或再交给下游读一次。 |
FileMd5Util
源码：FileMd5Util。
计算小写 MD5 摘要，用于内容比对；不能作为密码存储或可信身份校验方案。
| 方法 / 重载 | 用途、参数与返回值 | 注意事项 |
|---|---|---|
| get(File file) | 读取本地文件并通过内存映射计算摘要。 | IOException 包装业务异常，不返回空摘要。 |
| get(String content) | 将字符串按 UTF-8 编码再计算摘要。 | 参数是正文，不是文件路径；null 失败。 |
| get(byte[] bytes) | 直接计算字节数组摘要。 | 需要传完整字节；不会处理输入流。 |
| get(MultipartFile file) | 先 getBytes 再计算摘要。 | 整文件载入内存，大文件需考虑开销；读失败抛业务异常。 |
| checkPassword(String password, String md5PwdStr) | 计算 password 的 MD5 并比较字符串，返回 boolean。 | 没有盐、慢哈希和恒定时间比较；仅解释已有行为，不用于新增密码方案。 |