现代 Java 后端开发规范

技能文档

---
name: diegosouzapw-modern-java-backend-playbook
title: 现代 Java 后端开发规范
category: 开发工具
description: 强制执行后端 Java/Quarkus 项目标准，覆盖架构分层、设计模式、代码复用、Lombok、TDD、异常处理与现代 Java 特性。当用户使用 Quarkus、Panache、Hibernate、Jakarta EE 或微服务架构编写、修改、审查 Java 后端代码时使用。触发词：Java 后端、Quarkus、代码规范、代码审查、分层架构。
---

# Java 后端 —— 项目规范与模式

你是资深 Java 后端开发者，工作在基于 **Quarkus** 和 **Java** 的微服务生态中。在编写或修改代码前，先分析项目的 `pom.xml` 或 `build.gradle`，确认实际使用的 Java 与 Quarkus 版本，再应用该版本可用的最佳实践与新特性。以下规范为强制性项目标准，写代码、改代码、审代码时都必须遵守。

## 技能工作流

### 步骤1：识别项目版本与技术栈

读取 `pom.xml` / `build.gradle`，确认 Java 版本、Quarkus 版本与已引入的库，后续所有代码按该版本可用的特性编写。

### 步骤2：按分层结构组织代码

每个微服务遵循统一包结构，文件必须放进正确的包/模块，禁止混淆职责（Service 不进 `resources/`，查询不进 `service/`）；一个文件一个类，文件名与类名完全一致：

```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/            # 异步操作的拦截器与监听器
```

### 步骤3：按核心原则实现业务代码

各分层的完整参考实现见 [分层代码示例](references/layer-examples.md)，核心原则如下：

**代码复用**——绝不重复造轮子。写新逻辑前先确认以下位置是否已有现成方案：项目工具类（`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` 方法）。

**设计模式**——一致性应用：SOLID；Service 层承载全部业务逻辑（禁止放进 Resources 或 Repository）；Repository 只做数据访问与 SQL/HQL；DTO 对接 API、Entity 只做持久化，禁止直接暴露 Entity；构造注入用 Lombok `@AllArgsConstructor`（禁止 `@Inject`）；多服务编排用 Facade；复杂对象用 `@Builder`；算法可互换时用 Strategy；共享算法骨架用 Template Method；Resources 管 HTTP、Services 管逻辑、Repositories 管数据。

**现代 Java 特性**——按项目版本优先使用：Record（不可变 DTO/值对象）、Stream API（`stream().map().toList()` 替代手工循环）、`List.of()`/`Map.of()`/`Set.of()`、`var`（右侧类型明显时）、文本块 `"""`（SQL/JSON 模板）、switch 表达式、`instanceof` 模式匹配、switch 模式匹配、sealed 类、新字符串方法（`.strip()`、`.isBlank()`、`.formatted()`）、虚拟线程（I/O 密集并发场景受益时）。

### 步骤4：统一异常处理与校验

完整模式见 [异常处理模式](references/exception-handling.md)。要点：业务规则违反抛 `BusinessException`（422）；响应用统一的 `Problem` 模型 + `ProblemBuilder` 集中构建；按异常类型创建 `ExceptionMapper` Provider，并必须有 `Throwable` 全局兜底 Provider；校验注解放在 DTO 字段上，Resource 用 `@Valid` 触发，Service 不重复校验。

### 步骤5：按 TDD 编写测试

完整模式见 [测试模式](references/testing-patterns.md)。要点：先写测试或与实现同步编写；命名 `givenContext_WhenAction_ThenExpectedResult`；用 GIVEN/WHEN/THEN 注释组织；单元测试免数据库（`NoDatabaseTestProfile`），集成测试用 REST Assured + TestContainers；成功与失败路径都要覆盖。

### 步骤6：提交前自查

对照下方「提交前自查清单」逐项核验后交付。

## 其他工程规范

依赖注入、校验、常量、Lombok、REST 客户端、外部化配置、`this.` 显式调用的详细规则见 [工程模式](references/engineering-patterns.md)。其中文件格式要求：每个文件末尾恰好一个空行；4 空格缩进（不用 Tab）；import 按 java.* → jakarta.* → 第三方 → 项目内部排序。

## 技术栈参考

以 `pom.xml` / `build.gradle` 实际版本为准应用最佳实践：

| 技术 | 用途 |
|------|------|
| Java | 语言（以构建文件为准） |
| Quarkus | 框架（以构建文件为准） |
| Hibernate ORM + Panache | ORM / 数据访问 |
| Flyway | 数据库迁移 |
| SQL Server (MSSQL) | 数据库 |
| Keycloak / OIDC | 认证 |
| Lombok | 代码生成 |
| MapStruct | 对象映射（使用时） |
| Jackson | JSON 序列化 |
| Hibernate Validator | Bean 校验 |
| SmallRye OpenAPI | API 文档 |
| OpenTelemetry | 分布式追踪 |
| SmallRye Health | 健康检查 |
| SmallRye Fault Tolerance | 容错 |
| AWS S3 | 对象存储 |
| JUnit 5 + Mockito | 测试 |
| TestContainers | 集成测试 |
| REST Assured | API 测试 |
| JaCoCo | 覆盖率 |

## 提交前自查清单

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

使用说明

# 现代 Java 后端开发规范

面向 Java/Quarkus 微服务项目的强制性工程规范：架构分层、设计模式、代码复用、Lombok、TDD、异常处理与现代 Java 特性，写代码、改代码、审代码时统一遵循。

## 使用

告诉 Agent 你的开发任务，例如：

```text
用 Quarkus 写一个产品管理的 CRUD 接口（含单元测试）
帮我审查这个 Service 类是否符合项目规范
给现有的 REST 接口补充统一异常处理
```

Agent 会先读取 `pom.xml`/`build.gradle` 确认版本，再按规范实现或评审代码。

## 工作原理

SKILL.md 定义六步工作流（识别版本 → 分层组织 → 实现代码 → 异常与校验 → TDD 测试 → 提交自查）；`references/` 提供各层完整代码示例、异常处理模式、测试模式与工程模式细则，按需加载。

## 依赖

支持 SKILL.md 的任意 Agent 环境；目标项目需为 Java/Quarkus 工程。

如何安装此技能？

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