一套前后端分离的 Spring Boot 后台管理系统模板:后端 svc/ 用 Maven 多模块,前端 app/ 目前只有占位 README,尚未开工。这里的词都是本模板自造的概念,通用编程名词不收。
starter: 一个技术一个可插拔的自动配置模块(web、cache、concurrent、datasource、job、mybatis、swagger、actuator),只做集成与默认配置,不含业务代码。 Avoid: plugin module, extension module
framework:
聚合层。它依赖若干 starter,把它们的自动配置合起来,并向业务暴露一份统一的 x-boot.framework 配置。
Avoid: core, base module
common: 不含 Spring Boot 自动配置的公共能力:异常体系、返回模型、扩展机制、工具类。业务与 starter 都可依赖它。 Avoid: utils module
dependency:
纯 BOM 模块,只写 dependencyManagement(第三方版本 + 本项目模块版本),不含代码。
Avoid: parent pom(x-boot-parent 是它的子模块,两者别混)
server/main:
唯一可启动的业务服务模块(MainApplication)。全部测试都放这里,测试子包按被测模块分组(common/…、starter/…)。
Avoid: admin(旧名,已重命名)
Extension:
common/extension/ 下四套工具的总称:Pipeline、Plugin、StateMachine、Event。各自有 README。
Avoid: plugin framework(那只是其中一套,且是 Spring 的)
ExtensionType:
所有扩展类型的统一标识接口,getType() 返回类型字符串。Pipeline 与 Plugin 共用同一套业务类型枚举,避免两套类型体系。
Avoid: 枚举类型、业务类型码
Pipeline:
自研的责任链。PipelineExecutor 既是构建器(appendFilter)也是执行入口(execute),一次请求只有一条链。
Avoid: workflow, flow engine
FilterSelector:
决定链上哪些 PipelineFilter 参与本次执行的选择器(Dummy / MatchAll / LocalList)。选择发生在 Filter 内部,不在执行器。
Avoid: route, condition
PluginService:
策略模式的服务接口,继承 Spring Plugin Framework 的 Plugin,靠 supports() 在运行时匹配。
Avoid: strategy interface
PluginContext:
插件上下文,只负责携带 getPluginType() 供匹配,不带业务数据本身。
Avoid: request context
StateMachine:
直接使用 Spring State Machine(spring-statemachine-core),本模板不封装,只在 demo 里给订单状态流转示例。
Avoid: 状态模式、status flow
CacheType:
x-boot.cache.type 的取值,只有 REDIS 与 DL 两种,且必须大写——@ConditionalOnProperty 是精确字符串匹配,写 redis 会导致 CacheManager 不创建。
Avoid: cache mode, backend
DLCache:
双级缓存,L1 是本地 Caffeine,L2 是 Redis。读:本地未命中则查 Redis 并回填;写:先写 Redis,再广播刷新通知,最后写本地。对应 CacheManager bean dlCacheManager。
Avoid: two-level cache, multi-level cache
动态 TTL 后缀:
缓存名带 #<duration> 时的约定,如 user#6。duration 用 Spring DurationStyle 语法(6 是 6ms、5m、2h、1d)。解析器是 DynaTtlNameUtil,以最后一个 # 分割。
Avoid: ttl suffix、cache name pattern(要区分“带后缀的完整缓存名”)
完整缓存名:
含 #ttl 后缀在内的整体名字。@Cacheable 与 @CacheEvict 必须写同一份完整名,否则会创建不同的缓存实例、永远命中不了。
Avoid: base name
刷新通知:
DLCache 写操作后经 Redis pub/sub 广播的本机缓存清理消息,默认主题 cache:dl:refresh:topic,集群内其余节点收到后清掉自己的 L1。
Avoid: invalidate, sync event
动态数据源:
集成 baomidou dynamic-datasource-spring-boot3-starter:配置在 spring.datasource.dynamic.*(primary 指定主库,strict 决定写错 key 是报错还是回落主库),切换用 @DS("key")——同类自调用、事务已开之后都不生效。原自研实现(DynamicDs + @DynamicDs + 配置前缀 x-boot.dynamic-ds)保留为可选方案(x-boot.dynamic-ds.enable 开启,默认关闭);@DynamicDs 可标在类或方法上,方法优先、类兜底。两者都往容器塞 DataSource,同时启用会让 MyBatis-Plus 的 @ConditionalOnSingleCandidate 失配、SqlSessionFactory 与事务管理器都不创建,所以只能二选一。
Avoid: multi datasource, ds routing
BaseEntity:
starter/mybatis 的实体抽象基类,带 create_time/create_user/update_time/update_user 四个 @TableField(fill = …) 字段;继承它的实体,表必须有这四列。用抽象类而非接口,是因为 @TableField 只能标在字段上、且 MyBatis-Plus 收集字段时只沿类继承链走,不遍历接口。
Avoid: base po, super entity
EntityFillResolver:
currentUser() 的 SPI。create_user/update_user 由 BaseEntityFillHandler 经它取值;模板里默认实现返回 null(即不填这两个字段),接入用户模块后提供 bean 覆盖即可。
Avoid: user context, login user holder
数据权限(DataScope):
@DataScope + DataScopeResolver 的组合:注解声明"过滤哪个字段、对哪些表生效",SPI 提供"当前用户能看到哪些范围值",DataScopePermissionHandler 实现 MP 的 MultiDataPermissionHandler,按表回调拼 field IN (...)。未标注解的请求不追加任何条件。
Avoid: row filter, permission interceptor
分页执行者:
本项目分页由 PageHelper 完成(PageHelper.startPage(...).doSelectPageInfo(...))。MP 的 PaginationInnerInterceptor 不注册,selectPage(IPage) 不分页也不报错(返回全表、total 为 0)。两个分页器都改写 SQL,不能同时注册,否则拼出 LIMIT ? LIMIT ?。
Avoid: MP pagination, selectPage
限流注解:
@RateLimit(limitPerSecond, waitTimeout),由 AOP 基于 Guava RateLimiter 实现,可标在类或方法上(方法优先、类兜底),粒度是“每个被切到的方法”。
Avoid: throttle, rate control
上下文透传:
用 TransmittableThreadLocal(TransmitUtil 包装 Executor / Runnable / Callable)把线程上下文带进线程池任务。
Avoid: MDC, trace context
ApiResult:
统一 JSON 返回体,status 与 HTTP 状态码保持一致。
Avoid: response wrapper, Result
ApiFormat:
类或方法上的开关(@ApiFormat(false) 关闭),由 ApiResultAdvisor 据此决定是否把返回值包成 ApiResult。
Avoid: auto wrap
ErrorCode:
异常错误码接口,getCode() / getMessage() / getStatus(),由枚举实现;状态值取自 ApiStatus。
Avoid: error enum
BaseException:
异常基类,message 支持 hutool StrUtil.format 模板传参。业务异常继承它,通用异常是 GeneralException。
Avoid: business exception
ParamEnumConvertible:
让枚举能在请求参数里按自定义值(而非 name())绑定的接口,配合 ParamEnumConvertorFactory 注册到 MVC。
Avoid: enum converter