# 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。

**文档**：
- [开发指南](docs/database-development.md) - 模块架构、核心设计、技术实现、扩展指南
- [使用指南](docs/database-usage.md) - 快速开始、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` 字段注入

### 构建

```bash
mvn clean package
```