moai-lang-java

快速参考（30 秒）

Java 21 LTS 专家——使用 Spring Boot 3.3、虚拟线程和现代 Java 特性进行企业级开发。

自动触发：扩展名为 .java 的 Java 文件，以及 pom.xml、build.gradle 或 build.gradle.kts 等构建文件

核心功能：

• Java 21 LTS：虚拟线程、模式匹配、record 模式、密封类
• Spring Boot 3.3：REST 控制器、服务、存储库、WebFlux 响应式编程
• Spring Security 6：JWT 身份验证、OAuth2、基于角色的访问控制
• JPA/Hibernate 7：实体映射、关系、查询、事务
• JUnit 5：单元测试、模拟、TestContainers 集成
• 构建工具：Maven 3.9、使用 Kotlin DSL 的 Gradle 8.5

---

实现指南（5 分钟）

Java 21 LTS 特性

使用 Project Loom 的虚拟线程：

对 Executors.newVirtualThreadPerTaskExecutor 使用 try-with-resources。调用 IntStream.range，范围为 0 到 10000，并使用 forEach 提交任务，让任务休眠一秒后返回迭代值。

结构化并发预览模式：

对 new StructuredTaskScope.ShutdownOnFailure 使用 try-with-resources。通过调用 scope.fork 并传入 lambda 表达式，派生用于获取用户和订单的任务。调用 scope.join，然后调用 throwIfFailed。返回一个新的组合对象，其中包含两个任务提供程序的结果。

Switch 的模式匹配：

创建一个接收 Object 参数的 describe 方法。使用 switch 表达式，包含以下分支：Integer i 且保护条件 i 大于 0 时，返回正整数消息；Integer i 时，返回非正数消息；String s 时，返回长度消息；带通配符的 List 时，返回大小消息；null 时，返回空值消息；default 时，返回未知类型消息。

Record 模式和密封类：

定义包含 int x 和 int y 的 Point record。定义包含 Point topLeft 和 Point bottomRight 的 Rectangle record。创建 area 方法，使用 switch 对 Rectangle 模式进行解构，将两个 Point 组件分别赋给变量，并返回宽度乘高度的绝对值。定义一个 sealed Shape 接口，允许 Circle 和 Rectangle。实现一个包含 area 方法的 Circle record，该方法使用 PI 乘以半径的平方。

Spring Boot 3.3

REST 控制器模式：

创建 UserController，添加 RestController 注解、针对 api/users 的 RequestMapping，以及 RequiredArgsConstructor。注入 UserService。创建带有 GetMapping 和针对 id 的 PathVariable 的 getUser 方法，该方法返回 ResponseEntity：将 findById 结果映射为 ok，或者返回 notFound。创建 createUser 方法，添加 PostMapping、Valid 注解以及针对 CreateUserRequest 的 RequestBody。创建用户，构建 URI 位置，并返回包含响应正文的 created 响应。创建 deleteUser 方法，添加 DeleteMapping；根据服务结果返回 noContent 或 notFound。

服务层模式：

创建 UserService，添加 Service、RequiredArgsConstructor 和 readOnly 为 true 的 Transactional 注解。注入 UserRepository 和 PasswordEncoder。创建返回 Optional 的 findById 方法。创建事务性 create 方法，检查电子邮件是否重复；如果重复，则抛出 DuplicateEmailException；然后使用构建器模式创建 User，并对密码进行编码，最后保存到存储库。

Spring Security 6

安全配置模式：

创建 SecurityConfig，添加 Configuration 和 EnableWebSecurity 注解。定义一个接收 HttpSecurity 的 filterChain Bean。配置 authorizeHttpRequests：对公共 API 路径使用 permitAll，对管理路径使用 hasRole ADMIN，对所有其他请求使用 authenticated。使用默认配置配置 oauth2ResourceServer 的 jwt。将 sessionManagement 设为 STATELESS，并禁用 csrf。定义一个返回 BCryptPasswordEncoder 的 passwordEncoder Bean。

JPA/Hibernate 模式

实体定义模式：

创建带有 Entity 和 Table 注解的 User 实体。添加 Lombok 的 Getter、Setter、NoArgsConstructor 和 Builder 注解。为 id 定义 Id 和 GeneratedValue IDENTITY。为 name 和 email 定义 Column nullable false，email 还需设置 unique。为 status 定义 Enumerated STRING。为 orders 定义 OneToMany mappedBy user、cascade ALL 和 orphanRemoval true。

带自定义查询的仓库模式：

创建继承 JpaRepository 的 UserRepository。添加返回 Optional 的 findByEmail。添加返回 boolean 的 existsByEmail。为 findByIdWithOrders 添加带 LEFT JOIN FETCH 的 JPQL Query 注解，并使用 Param 注解。添加带 Pageable 的 findByNameContainingIgnoreCase，以支持分页。

使用 Record 定义 DTO 的模式：

创建包含 id、name、email 和 status 的 UserDto record。添加静态 from 工厂方法，用于从 User 实体构造 record。创建 CreateUserRequest record：name 添加 NotBlank 和 Size 注解，email 添加 NotBlank 和 Email 注解，password 添加 NotBlank 和 Size min 8 注解。

---

高级模式

集成虚拟线程

创建带有 Service 和 RequiredArgsConstructor 注解的 AsyncUserService。创建 fetchUserDetails 方法，在 try-with-resources 中使用 StructuredTaskScope.ShutdownOnFailure。为用户和订单查询派生任务，调用 join，并在失败时抛出异常，然后返回组合结果。创建 processUsersInParallel 方法，使用 newVirtualThreadPerTaskExecutor，并通过流式处理用户 ID 来提交处理任务。

构建配置

Maven 3.9 模式：

定义项目，并将 spring-boot-starter-parent 3.3.0 版本设为 parent。将 java.version 属性设为 21。添加 spring-boot-starter-web 和 spring-boot-starter-data-jpa 依赖。

Gradle 8.5 Kotlin DSL 模式：

应用 org.springframework.boot、io.spring.dependency-management 和 java 插件。将 toolchain 的 languageVersion 设为 21。为 web 和 data-jpa starter 添加 implementation 依赖，为 test starter 添加 testImplementation 依赖。

使用 JUnit 5 测试

单元测试模式：

创建带有 ExtendWith MockitoExtension 的测试类。为 UserRepository 添加 Mock 注解。为 UserService 添加 InjectMocks。创建 shouldCreateUser 测试，将 existsByEmail 存根设为返回 false，并将 save 存根设为返回带有 id 的用户。调用服务的 create 方法，并使用 assertThat 断言结果 id 等于 1。

使用 TestContainers 进行集成测试的模式：

创建带有 Testcontainers 和 SpringBootTest 注解的测试类。定义 PostgreSQL 的静态 Container，并使用 postgres:16-alpine 镜像。添加 DynamicPropertySource，以从容器设置 datasource.url。自动装配仓库。创建测试，保存用户并使用 assertThat 断言 id isNotNull。

---

Context7 集成

最新文档的库映射：

• spring-projects/spring-boot，用于 Spring Boot 3.3 文档
• spring-projects/spring-framework，用于 Spring Framework 核心
• spring-projects/spring-security，用于 Spring Security 6
• hibernate/hibernate-orm，用于 Hibernate 7 ORM 模式
• junit-team/junit5，用于 JUnit 5 测试框架

---

搭配使用效果良好

• moai-lang-kotlin，用于 Kotlin 互操作和 Spring Kotlin 扩展
• moai-domain-backend，用于 REST API、GraphQL 和微服务架构
• moai-domain-database，用于 JPA、Hibernate 和 R2DBC 模式
• moai-foundation-quality，用于 JUnit 5、Mockito 和 TestContainers 集成
• moai-infra-docker，用于 JVM 容器优化

---

故障排除

常见问题：

• 版本不匹配：运行 java -version，并检查 JAVA_HOME 是否指向 Java 21
• 编译错误：运行 mvn clean compile -X 或 gradle build --info
• 虚拟线程问题：确保使用 Java 21+，并在需要时启用 --enable-preview
• JPA 延迟加载：使用 Transactional 注解或 JOIN FETCH 查询

性能提示：

• 将 spring.threads.virtual.enabled 设为 true，以启用虚拟线程
• 使用 GraalVM Native Image 加快启动速度
• 使用 HikariCP 配置连接池

---

高级文档

如需查阅全面的参考资料：

• reference.md：Java 21 功能、Context7 映射和性能
• examples.md：可用于生产环境的 Spring Boot 示例

---

最后更新：2026-01-11 状态：已可用于生产环境（v1.1.0）