Spring Boot 4 · JDK 21

企业级能力，
一个依赖就能装上

Loom Boot 是一套面向 Spring Boot 4 / JDK 21 的 Starter 套件：统一响应与异常、缓存、Web、邮件、对象存储、数据源、消息、安全、OIDC 登录与全链路审计， 11 个模块独立可选，全部基于自动装配，引入即可用。

5 分钟接入浏览 11 个模块

version 2.0.0 spring-boot 4.1.0 java 21 license Apache-2.0 modules 11

pom.xml

<!-- 继承父 POM，版本由 dependencyManagement 统一管理 -->
<parent>
  <groupId>cn.devloom</groupId>
  <artifactId>loom-boot-parent</artifactId>
  <version>2.0.0</version>
</parent>

<dependency>
  <groupId>cn.devloom</groupId>
  <artifactId>loom-web-boot-starter</artifactId>
  <!-- 无需写 version -->
</dependency>

11独立 Starter 模块

9统一 loom.* 配置前缀

0启动类改造

1父 POM 统一版本

Design

四条贯穿全部模块的设计原则

不是把工具类打包在一起，而是在自动装配、可覆盖性与降级路径上做统一约定。

零侵入自动装配

每个模块通过 AutoConfiguration.imports 登记配置类，业务应用只需引入依赖，不需要 @Import、@ComponentScan 或任何启动类改动。

默认实现可覆盖

核心 Bean 普遍带 @ConditionalOnMissingBean：应用声明同类型的 Bean，即可整体替换默认实现，不侵入框架代码。

统一配置前缀

全部开关与参数收敛到 loom.*（loom.cache、loom.mail、loom.oidc 等），配置文件一眼能看出哪些属于框架能力。

缺失即降级

Redis 缺失自动退到 Caffeine、RocketMQ 缺失退到进程内实现、OSS/COS 缺失退到本地存储、审计模块拿不到安全栈时自动关闭相关接口——能力不会因为中间件缺席而阻断启动。

Modules

11 个模块，按需组合

每个模块都是独立的 starter，引谁用谁；模块间不强行耦合，只有真正复用的能力才存在依赖。

基础与 Web

loom-common-boot-starter CORE

统一响应与异常体系

全局统一的返回信封、状态码与分层异常，配套断言工具和字段级加解密，让接口契约从第一天就对齐。

R<T> HttpCode BizException Asserts FieldCipher loom.crypto

loom-web-boot-starter WEB

Web 层统一约定

全局异常处理器把异常翻译成统一响应，日期参数自动转换，请求路径匹配策略统一，不需要在每个 Controller 里重复兜底。

GlobalExceptionHandler DateConverterConfig PathMatchConfig

数据、缓存与存储

loom-cache-boot-starter CACHE

统一缓存门面

一套 ICacheService 适配 Redis 与 Caffeine：有 Redis 走 Redis，没有自动降级本地缓存，代码不用改。

ICacheService Redis / Caffeine loom.cache

loom-datasource-boot-starter SQL

数据源与分页

自动装配 MyBatis-Plus 分页拦截器，统一的分页查询工具把分页元数据直接内置到响应信封里，前后端不用再对齐格式。

PageQueryUtil MyBatis-Plus loom.datasource

loom-store-boot-starter STORE

对象存储

上传、下载、删除、预签名 URL 一套 API，底层可在阿里云 OSS、腾讯云 COS 与本地磁盘之间切换，配置还能从数据库动态加载。

StoreService OSS / COS / Local loom.store

邮件与消息

loom-mail-boot-starter MAIL

多服务商动态邮件

模板渲染、附件、地址校验齐全；服务商配置支持数据库热加载与变更监听，运营改配置不用重启应用。

MailService MailTemplateRenderer 动态配置 loom.mail

loom-mq-boot-starter MQ

统一消息门面

发送侧统一 MessageProducer，消费侧一个 @MqListener 注解搞定；内置 RocketMQ 实现，也提供进程内实现用于本地开发。

MessageProducer @MqListener RocketMQ / Local loom.mq

安全、登录与审计

loom-security-boot-starter SEC

认证鉴权底座

会话认证过滤器、两级白名单、RBAC 权限点映射、方法级 @PreAuthorize，401/403 也走统一响应与分段错误码。

SessionAuthenticationFilter RolePermissionResolver SessionStore loom.security

loom-oidc-client-boot-starter OIDC

OIDC 授权码登录

对接自有 IAM：授权码流程、id_token JWKS 验签、令牌只存服务端会话、access_token 到期无感刷新（分布式锁防风暴）。

OidcLoginService IdTokenValidator OidcTokenRefresher loom.oidc

loom-log-boot-starter LOG

全链路审计日志

登录日志与操作日志自动采集、异步落库、traceId 串联；自动建表、敏感字段脱敏、保留策略与查询接口一应俱全。

@OperationLog TraceIdFilter SensitiveDataMasker loom.log

工具链

loom-boot-generator-starter DEV

开发期代码生成器

读 MySQL 表结构，按统一约定生成 entity / mapper / service / serviceImpl / controller。非运行时 starter，只在开发机执行一次。

CodeGenerator GeneratorConfig FreeMarker 模板

loom-boot-parent BOM

版本与依赖统一

父 POM 统一管理 Spring Boot、Spring Security、MyBatis-Plus、RocketMQ、OSS / COS SDK 等版本，并完成与 Maven Central 发布兼容的构建配置。

dependencyManagement revision 统一版本 Apache-2.0

Quick Start

三个步骤完成接入

引入依赖即可生效，不需要任何启动类改造；配置项全部在 loom.* 下，按需开启。

pom.xml（推荐：继承父 POM）

<parent>
  <groupId>cn.devloom</groupId>
  <artifactId>loom-boot-parent</artifactId>
  <version>2.0.0</version>
</parent>

<dependencies>
  <dependency>
    <groupId>cn.devloom</groupId>
    <artifactId>loom-web-boot-starter</artifactId>
  </dependency>
  <dependency>
    <groupId>cn.devloom</groupId>
    <artifactId>loom-security-boot-starter</artifactId>
  </dependency>
</dependencies>

application.yml

loom:
  crypto:
    enabled: true
    secret-key: ${LOOM_CRYPTO_SECRET_KEY}
  cache:
    type: AUTO           # 自动探测：有 Redis 用 Redis，否则退到 Caffeine
  mail:
    default-provider: aliyun-txn
  security:
    whitelist:
      permit-all:
        - /actuator/**
        - /public/**

不写 version

继承 loom-boot-parent 后，所有 starter 的版本由 dependencyManagement 统一控制，升级只需改一处。

不写配置也能跑

默认值均指向“开箱可启动”：缓存退本地、存储退本地目录、消息退进程内，中间件可以后补。

不想要就换掉

声明同类型 Bean 即覆盖默认实现；模块之间只通过接口与 SPI 协作，不存在硬编码绑定。

Capability Map

一份能力全景：从请求进入到数据落库

把 11 个模块按调用链排列，就能看出每个环节由谁负责、缺了谁会退到什么程度。

接入与响应

R<T> 统一信封 HttpCode 状态码全局异常处理断言 Asserts 日期参数转换路径匹配策略

认证与授权

会话认证过滤器两级白名单 RBAC 权限点映射 @PreAuthorize OIDC 授权码登录 id_token JWKS 验签 access_token 无感刷新

缓存与数据

ICacheService 门面 Redis Caffeine MyBatis-Plus 分页拦截器 PageQueryUtil FieldCipher 字段加解密

集成能力

MailService 多服务商模板渲染 + 附件对象存储 OSS / COS / Local 预签名 URL MessageProducer @MqListener RocketMQ / LOCAL

可观测与审计

@OperationLog 切面登录日志事件桥接 traceId 串联敏感字段脱敏异步落库保留策略管理端查询接口

中间件缺席时会发生什么

框架不在启动期逼你准备全部外部依赖，而是给每个能力留一条降级路径。

缺失的条件	自动退化为	对业务的影响
未接入 Redis	Caffeine 进程内缓存	缓存不再跨实例共享，功能本身不缺失
未配置 RocketMQ	LOCAL 进程内实现	消息只在单进程内流转，仅适合本地调试
未配置 OSS / COS	本地磁盘存储	需要保证目录可写、备份与迁移自行安排
未引入 security / oidc	审计降级为匿名	不注册过滤器与查询接口，日志能力不强制绑定安全栈

Matrix

版本矩阵

所有版本由父 POM 的 dependencyManagement 统一收口，业务继承父 POM 后不会出现版本漂移。

组件	版本	说明
Java	21	编译与运行基线，JDK 21（LTS）已验证
Spring Boot	4.1.0	自动装配与依赖管理体系的基础
Spring Security	7.1	security 模块的认证鉴权底座
MyBatis-Plus	3.5.15	datasource 模块的分页拦截器与 SQL 增强
RocketMQ Client	5.3.2	mq 模块的正式消息实现
阿里云 OSS SDK	3.18.2	store 模块的 OSS 提供方
腾讯云 COS SDK	5.6.247	store 模块的 COS 提供方
FreeMarker	父 POM 管理	generator 模块的代码模板引擎
Maven	3.9+	构建与 Maven Central 发布

Publish

发布信息

11 个 artifact 以 Apache-2.0 开源发布，坐标统一收在 cn.devloom 下。

groupIdcn.devloom

version2.0.0

父 POMcn.devloom:loom-boot-parent:2.0.0

分发仓库Maven Central

许可证Apache License 2.0

项目主页https://boot.devloom.cn

把重复的兜底代码，从每个项目里删掉

统一响应、异常、缓存、存储、邮件、消息、安全与审计，11 个模块引谁用谁；升级只改一处，默认实现随时可替换。

立即接入联系我们

企业级能力，一个依赖就能装上