Spring Boot 模块化单体快速开发模板

基于 Spring Boot 3.5 + Java 17 + MyBatis + Maven 多模块 的可复用后端模板，内置认证鉴权、两级缓存、分布式锁、限流风控等基础设施。项目采用模块化单体：一个启动入口、一个部署产物，业务能力拆到独立 Maven module 中开发。

内置能力

能力	实现方式	所在包
JWT 认证 + RBAC 授权	Spring Security + jjwt	security/auth/
限流	Redis 滑动窗口	security/rate/
风控	多维度阈值检测	security/risk/
两级缓存	Caffeine(L1) + Redis(L2)	cache/
分布式锁	Redisson + @Lock AOP	infrastructure/aop/lock/
幂等控制	@Idempotent AOP + Redis	infrastructure/aop/idempotent/
统一响应格式	Result<T> + PageResponse	common/api/
统一异常处理	GlobalExceptionHandler	infrastructure/exception/
链路追踪	TraceId 自动注入	infrastructure/log/
异步任务	ThreadPoolTaskExecutor	infrastructure/config/
Docker 部署	docker-compose + Dockerfile	根目录

快速开始

环境要求

• JDK 17+
• Docker (运行 MySQL + Redis)

启动

# 1. 启动 MySQL 和 Redis
docker compose up -d

# 2. 启动应用
./mvnw -pl ainovel-app spring-boot:run

# 3. 验证
curl http://localhost:8080/actuator/health

测试

./mvnw test    # 使用 H2 内存库，无需外部数据库
./mvnw -pl ainovel-app -am package    # 构建可执行 JAR

项目结构

pom.xml                       # Maven reactor parent
ainovel-common/               # Result<T>, PageResponse, ErrorCode
ainovel-platform/             # access/cache/infrastructure/persistence/security
ainovel-admin/                # 管理操作日志
ainovel-user/                 # 注册/登录, 个人信息, 站内信
ainovel-audit-api/            # 审核提交端口
ainovel-novel-api/            # 审核结果回写端口
ainovel-audit/                # 内容审核引擎
ainovel-novel/                # 小说 CRUD, 章节管理, 爬虫导入
ainovel-reading/              # 阅读进度, 书签, 历史
ainovel-community/            # 评论, 点赞, 关注, 分区
ainovel-recommend/            # 推荐引擎
ainovel-app/                  # Spring Boot 启动入口、配置、集成测试资源、可执行 JAR

如何定制自己的项目

1. 移除不需要的示例模块

# 删除示例业务模块
rm -rf ainovel-novel
rm -rf ainovel-reading
rm -rf ainovel-community
rm -rf ainovel-audit
rm -rf ainovel-recommend

然后从根 pom.xml 的 <modules>、ainovel-app/pom.xml 的依赖和 AInovelApplication.java 的 @MapperScan 中移除对应条目。

2. 添加自己的业务模块

新增业务能力建议放入独立 Maven module，例如 ainovel-your-module：

ainovel-your-module/
├── pom.xml
└── src/main/java/com/ainovel/yourmodule/
    ├── controller/     # REST 接口 (使用 Result<T> 统一响应)
    ├── domain/         # 领域模型 (Java record)
    ├── dto/            # 请求/响应 DTO
    ├── entity/         # 数据库实体
    ├── mapper/         # MyBatis Mapper
    ├── service/        # 业务逻辑
    └── vo/             # 视图对象

创建后将模块加入根 pom.xml 的 <modules>，并在 ainovel-app/pom.xml 中添加依赖；如有 Mapper，再把 com.ainovel.yourmodule.mapper 加入 AInovelApplication 的 @MapperScan。

在 ainovel-app/src/main/resources/application-framework.yml 中配置权限路径：

ainovel:
  security:
    # 该模块的公开 GET 路径
    public-get-paths:
      - /api/v1/your-resource/**
    # 需要认证的路径
    authenticated-paths:
      - /api/v1/your-resource/write

3. 自定义安全配置

修改 application-framework.yml 或通过环境变量覆盖：

• ainovel.security.whitelist-paths — 完全公开路径
• ainovel.security.public-get-paths — 公开只读路径
• ainovel.security.authenticated-paths — 需要认证路径
• ainovel.security.jwt-secret — JWT 密钥（生产环境必须修改）

详细定制说明见 docs/CUSTOMIZE.md。

配置说明

配置文件	用途
application.yml	主配置：数据库、Redis 连接
application-framework.yml	框架配置：缓存、安全、限流、风控

技术栈

• Spring Boot 3.5.7 + Java 17
• MyBatis 3.0.4 + MySQL 8.4
• Redis 7 + Redisson 3.40.2
• Caffeine (本地缓存)
• JWT + Spring Security
• Docker Compose 部署

License

MIT