Spring Boot Service Template

微服务快速开发能力模板，v1.1.0-SNAPSHOT。Java 17, Spring Boot 4.0.0, Spring Cloud 2025.1.0。

GroupId: com.lanyuanxiaoyao，根包: com.lanyuanxiaoyao.service.template。

模块

spring-boot-service-template/              (根 POM, packaging=pom)
├── spring-boot-service-template-common/    (jar — 通用工具)
└── spring-boot-service-template-database/  (jar — JPA 数据库能力)

模块命名规则: spring-boot-service-template-{capability}[-{impl}]

包结构

com.lanyuanxiaoyao.service.template.{module}/
  configuration/   # @Configuration（用 configuration 不用 config）
  controller/      # REST 控制器 + 接口
  entity/          # JPA 实体、Query、GlobalResponse 等数据对象
  exception/       # 自定义异常（用 exception 不用 exceptions）
  helper/          # 工具类（用 helper 不用 util/utils）
  repository/      # Spring Data 仓库
  service/         # 业务服务

无独立 DTO/VO 包，DTO 作为 Controller 内部 record。

database 模块

单表 CRUD → REST 接口快速实现框架。基于 JPA + Fenix + QueryDSL + MapStruct。

文档：

• 开发指南 - 模块架构、核心设计、技术实现、扩展指南
• 使用指南 - 快速开始、API 接口、查询条件、高级用法

开发规范

命名

类别	模式	示例
实体基类	*Entity	IdOnlyEntity, SimpleEntity
业务实体	纯名词	Employee
控制器接口	*Controller	SaveController
控制器抽象基类	*ControllerSupport	SimpleControllerSupport
服务接口	*Service	SaveService
服务抽象基类	*ServiceSupport	SimpleServiceSupport
仓库	*Repository	EmployeeRepository
工具类	*Helper	ObjectHelper
配置类	*Configuration	QueryDSLConfiguration
异常	*Exception	IdNotFoundException
内部 DTO record	SaveItem/ListItem/DetailItem	Controller 内部

• 接口不加 I 前缀
• 方法: 动词开头 save()/list()/detail()/remove()；布尔用 is/has 前缀
• 常量 UPPER_SNAKE_CASE；字段常量用 @FieldNameConstants 生成 {Class}.Fields.{field}
• 泛型: 简单用 T/E，领域用 ENTITY/SAVE_ITEM/LIST_ITEM/DETAIL_ITEM

代码风格

• 2 空格缩进，K&R 大括号，不用 Tab
• Import 排序: java.* → jakarta.* → 第三方 → com.lanyuanxiaoyao.*，不用通配符
• 积极使用 Java 17 特性: record(DTO) / var / instanceof 模式匹配 / Text Blocks / String.formatted()
• JavaDoc 用中文，含 @param/@return/@see，可用 <p>/<h3>/<ul>/<pre>
• 不写 // 行内注释，除非必要

注解

用:

• 实体: @Getter @Setter @ToString @FieldNameConstants，子类加 @ToString(callSuper = true)
• 日志: @Slf4j
• 注入: @RequiredArgsConstructor(access = AccessLevel.PROTECTED)（构造器注入）
• 事务: 写 @Transactional(rollbackFor = Throwable.class)，读 @Transactional(readOnly = true)
• 实体基类: @MappedSuperclass @EntityListeners(AuditingEntityListener.class)

不用:

• 不用 @Valid/@NotNull 等校验注解
• 不用 Swagger/OpenAPI 注解
• 不用 @Autowired 字段注入
• 不写代码注释（//），除非必要

异常

继承 RuntimeException，构造器用 String.formatted()。查无数据用 Optional.orElseThrow(() -> new IdNotFoundException(id))。无全局 @ControllerAdvice。

依赖管理

版本集中在根 POM <properties> + <dependencyManagement>，子模块不声明版本。 全局继承: lombok / jspecify:1.0.0 核心: spring-boot-starter-data-jpa / fenix-spring-boot-starter:4.0.0 / querydsl-jpa:7.1 / mapstruct:1.6.3 database 模块注解处理器: lombok → hibernate-jpamodelgen → querydsl-apt(jpa) → jakarta.persistence-api → mapstruct-processor

通用原则

• 文档/注释/commit 用中文，代码标识符用英文
• 不引入新依赖前先复用已有组件，优先 JDK 和 Spring 内置能力
• 构造器注入，不使用 @Autowired 字段注入

构建

mvn clean package