Quarkus Java 后端开发规范

技能文档

---
name: flaviodotcom-quarkus-java-backend-playbook
title: Quarkus Java 后端开发规范
category: 开发工具
description: 约束 Java/Quarkus 后端微服务项目的工程规范：分层架构（Resource/Service/Repository）、DTO 与实体转换、异常处理与统一 Problem 响应、Lombok 构造器注入、Hibernate Validator 校验、TDD 测试与现代 Java 特性，用于写代码、改代码和评审代码时保持全项目标准一致。当用户提到 Quarkus 开发、Java 后端规范、微服务代码评审、Panache、Hibernate 项目时触发。触发词：Quarkus、Java 后端、代码规范、微服务、Panache。
---

# Quarkus Java 后端开发规范

面向基于 **Quarkus** 与 **Java** 构建的微服务生态，沉淀一套不可妥协的项目级工程标准。在编写、修改或评审代码前，先分析项目的 `pom.xml` 或 `build.gradle`，确认实际使用的 Java 与 Quarkus 版本，再套用该版本可用的最佳实践与语言特性。

## 1. 核心原则

### 1.1 代码复用

**绝不重复造轮子。** 写新逻辑之前，先确认以下位置是否已有现成方案：

- 当前项目的工具类（如 `QueryUtils`、`DateUtils`、`FileUtils`、`JwtUtil`）
- Panache 内置方法（`findByIdOptional`、`find`、`list`、`persist`、`delete`、`count`、`pageCount`）
- 项目已引入的库（Apache Commons、MapStruct、Lombok、Jackson 等）
- Java 标准库（Stream API、`List.of()`、`Map.of()`、`Optional`、`String` 方法）

工具或辅助方法已存在时直接使用，不写重复逻辑。

### 1.2 设计模式

始终如一地应用以下模式：

- **SOLID** —— 单一职责、开闭、里氏替换、接口隔离、依赖倒置
- **Service 层模式** —— 全部业务逻辑放在 Service 中，绝不放进 Resource 或 Repository
- **Repository 模式** —— 只做数据访问，SQL/HQL 查询只出现在这里，不含业务逻辑
- **DTO 模式** —— DTO 用于 API 输入输出，Entity 用于持久化，绝不直接暴露 Entity
- **依赖注入** —— 通过 Lombok `@AllArgsConstructor` 做构造器注入，**禁用 `@Inject`**
- **Facade** —— 需要编排多个 Service 时使用
- **工厂方法 / Builder** —— 复杂对象创建用 Lombok `@Builder`
- **Strategy** —— 多种算法或行为需要可互换时使用
- **模板方法** —— 算法骨架固定、步骤可变时使用
- **MVC** —— Resource（控制器）处理 HTTP，Service 处理逻辑，Repository 处理数据

### 1.3 现代 Java 特性：必须使用

先查 `pom.xml` / `build.gradle` 确认版本，优先使用该版本可用的现代特性：

- **Record** —— 不可变 DTO、值对象与简单数据载体
- **Stream API** —— 集合转换优先 `stream().map().toList()`，少写手写循环
- **`List.of()` / `Map.of()` / `Set.of()`** —— 构建不可变集合
- **类型推断 `var`** —— 右侧类型显而易见的局部变量
- **文本块 `"""`** —— 多行字符串、SQL、JSON 模板
- **switch 表达式** —— 适时使用 `->` 与 `yield`
- **`instanceof` 模式匹配** —— 用 `if (obj instanceof String s)` 代替强转
- **switch 模式匹配、密封类（sealed）** —— 适用场景下使用
- **字符串新方法** —— `.strip()`、`.isBlank()`、`.formatted()` 等
- **虚拟线程** —— I/O 密集并发场景收益明显时使用

## 2. 架构与包结构

每个微服务遵循统一包结构：

```text
├── resources/              # REST 端点（JAX-RS Resources）
├── service/                # Service 接口
│   └── impl/               # Service 实现
├── repository/             # Panache 仓库（数据访问 + 查询）
├── dto/                    # 数据传输对象（请求/响应）
├── entities/               # JPA 实体
│   ├── enums/              # 实体使用的枚举
│   └── converters/         # JPA 属性转换器
├── exceptions/             # 自定义异常（BusinessException 等）
│   └── providers/          # ExceptionMapper 实现
├── config/                 # 配置类
│   ├── interceptors/       # 过滤器、拦截器
│   └── validators/         # 自定义约束校验器
├── annotations/            # 自定义注解
├── clients/                # REST 客户端接口（@RegisterRestClient）
├── mapper/                 # MapStruct 映射器（如使用）
├── util/                   # 工具类（QueryUtils、DateUtils、JwtUtil 等）
├── health/                 # 健康检查实现
├── startup/                # 应用启动钩子
└── concurrency/            # 异步操作的拦截器与监听器
```

**规则：**

- 文件必须放进正确的包/模块
- 不允许职责混杂：Service 不能出现在 `resources/`，查询不能出现在 `service/`
- 一个文件一个类，文件名与类名完全一致

## 3. 技能工作流

### 步骤1：确认技术栈版本

读取项目的 `pom.xml` 或 `build.gradle`，确认 Java 与 Quarkus 版本以及依赖清单，后续所有实现遵循该版本可用的特性与 API。

### 步骤2：按分层结构实现

新建或修改代码时，先定位所属分层（Resource / Service / Repository / DTO / Entity），按第 4 节的分层规则与 [references/layer-standards.md](references/layer-standards.md) 中的代码模板实现；业务逻辑只进 Service，SQL/HQL 只进 Repository。

### 步骤3：接入异常与校验

业务规则违规抛 `BusinessException`；为每类异常提供 `ExceptionMapper` Provider，统一返回 `Problem` 模型；校验注解写在 DTO 字段上，Resource 入参用 `@Valid` 触发。细节见 [references/layer-standards.md](references/layer-standards.md) 的异常处理一节。

### 步骤4：编写测试（TDD）

先写或同步写测试保证可测性：单元测试用 `@QuarkusTest` + `@InjectMock`，命名遵循 `given场景_When动作_Then期望结果`，用 GIVEN/WHEN/THEN 注释分段；集成测试用 REST Assured 与 TestContainers。模板见 [references/testing-and-patterns.md](references/testing-and-patterns.md)。

### 步骤5：提交前自检

对照第 6 节「提交自检清单」逐项核对，全部通过后才交付代码。

## 4. 分层规则速查

| 分层 | 核心规则 |
|------|----------|
| Resource | 只做 HTTP 编排：`@AllArgsConstructor` 注入、`@Authenticated` 鉴权、`@Valid` 校验入参、`@BeanParam` 接收过滤分页、返回 `Response`，不含业务逻辑 |
| Service | 承载全部业务逻辑：接口 + 实现分离，默认 `@ApplicationScoped`，写操作加 `@Transactional(rollbackOn = Exception.class)`，业务违规抛 `BusinessException` |
| Repository | 继承 `PanacheRepository<Entity>`，只放 SQL/HQL；优先复用 Panache 内置方法；单结果查询返回 `Optional<T>`，分页查询返回 `PanacheQuery<T>` |
| DTO | Lombok `@Data` + `@Builder` 系列 + `@RegisterForReflection`；校验注解写在字段上；提供静态 `fromEntity()`、实例 `toEntity()`、`toDtoList()`、`toEntityList()` 转换方法 |
| Entity | `@Entity` + `@Table(name)`，`@Id` + `@GeneratedValue(IDENTITY)`，字段全部标注 `@Column(name)`；枚举字段用 `@Enumerated(EnumType.STRING)`，枚举放 `entities.enums`；类名以 `Entity` 结尾 |
| 异常 | `BusinessException`（422）+ `Problem`/`ProblemObject` 响应模型 + `ProblemBuilder` 统一构建 + 各类 `ExceptionMapper` Provider，必须包含 `Throwable` 全局兜底 |
| 依赖注入 | 全部 CDI Bean 用 `@AllArgsConstructor` 构造器注入，字段尽量 `private final`，**禁用 `@Inject` 字段注入** |
| 常量 | 定义在类顶部，`private static final`，全大写下划线命名；常量过多或跨类共享时迁移到 `util` 下的专用常量类 |
| 文件格式 | 文件末尾恰好一个空行；4 空格缩进；import 按 java.*、jakarta.*、第三方、项目内部的顺序组织 |

完整代码模板与逐条规则见：

- [references/layer-standards.md](references/layer-standards.md) —— 各分层实现模板、DTO 转换、异常处理全流程
- [references/testing-and-patterns.md](references/testing-and-patterns.md) —— TDD 测试模板、REST 客户端、配置模式、`this` 关键字约定、技术栈对照表

## 5. Lombok 使用约定

| 注解 | 用途 |
|------|------|
| `@Data` | DTO、实体（生成 getter/setter/equals/hashCode/toString） |
| `@Getter` / `@Setter` | 有关联关系的实体（避免 hashCode 问题） |
| `@Builder` | DTO、实体与复杂对象构建 |
| `@Builder(toBuilder = true)` | 需要复制并修改对象时 |
| `@AllArgsConstructor` | 所有 CDI Bean 的构造器注入 |
| `@NoArgsConstructor` | JPA 实体与 Jackson 反序列化必需 |
| `@RequiredArgsConstructor` | 只需注入 `final` 字段时 |

**规则：** 能用 Lombok 消除的样板代码绝不手写；DTO 与实体的对象构建统一走 `@Builder`。

## 6. 提交自检清单

提交任何代码前逐项核对：

- [ ] 业务逻辑只在 Service 层
- [ ] SQL/HQL 查询只在 Repository 层
- [ ] 通过 `@AllArgsConstructor` 做构造器注入（没有 `@Inject`）
- [ ] 校验注解写在 DTO 字段上，Resource 入参带 `@Valid`
- [ ] 异常均有 ExceptionMapper Provider 映射，且与所在分层的架构语义相符
- [ ] 使用 Lombok 消除了样板代码
- [ ] DTO 具备 `fromEntity()`、`toEntity()`、`toDtoList()` 方法
- [ ] 使用了项目版本支持的现代 Java 特性（var、Stream、Record、switch 表达式、模式匹配等）
- [ ] 测试遵循 GIVEN/WHEN/THEN 结构
- [ ] 常量位于类顶部
- [ ] 文件位于正确的包中
- [ ] 文件末尾恰好一个空行
- [ ] 复用了已有代码与工具方法
- [ ] `this.` 按 [references/testing-and-patterns.md](references/testing-and-patterns.md) 的约定用于 void 方法、构造器、`toEntity()` 与更新方法

使用说明

# Quarkus Java 后端开发规范

统一 Java/Quarkus 微服务项目的工程标准：分层架构、异常处理、校验、TDD 测试与现代 Java 特性，写代码和评审代码时都遵循同一套规则。

## 使用

让 Agent 在开发或评审 Java 后端代码时应用本技能，例如：

```text
按照规范审查这个 Service 层的实现
帮我新建一个产品管理的 CRUD，遵循项目分层标准
这段代码的异常处理和校验符合规范吗？
```

## 工作原理

技能先确认项目技术栈版本，再按「Resource 编排 → Service 业务逻辑 → Repository 数据访问 → DTO 转换 → Entity 持久化」的分层标准实现，统一异常映射与 DTO 校验，最后按提交自检清单核对。完整代码模板见 references/ 目录。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。