java-quarkus-development

Java Quarkus 开发最佳实践

核心原则

• 使用 Quarkus 最佳实践编写整洁、高效且文档完善的 Java 代码
• 通过 GraalVM 原生构建，专注于快速启动和最小化内存占用
• 利用 Quarkus 扩展实现常见功能
• 面向容器化和无服务器部署进行设计
• 遵循 SOLID 原则和微服务架构模式

开发工作流

Quarkus 开发模式

• 使用 quarkus dev 进行快速迭代，并启用实时重载
• 在开发过程中利用持续测试
• 使用 Dev UI 进行调试和配置检查
• 利用 Dev Services 进行本地开发

配置

类型安全配置

• 使用 @ConfigProperty 注入类型安全的配置
• 使用 @ConfigMapping 接口对相关配置进行分组
• 在启动时验证配置
• 为配置属性编写文档

基于配置文件的配置

• 使用 %dev、%test、%prod 前缀设置环境专属配置
• 在生产环境中通过环境变量覆盖配置
• 不要将敏感值纳入源代码管理
• 在本地开发时使用 .env 文件

依赖注入

CDI 注解

• 使用 @Inject 进行依赖注入
• 使用 @Named 指定实现
• 适当使用 @Singleton、@ApplicationScoped、@RequestScoped
• 对必需依赖优先使用构造函数注入

Bean 发现

• 了解 Quarkus 的构建时 Bean 发现机制
• 使用 @IfBuildProfile 创建有条件的 Bean
• 避免在原生构建中使用大量依赖反射的模式

REST API 开发

RESTEasy Reactive

• 使用 @Path、@GET、@POST 等注解定义端点
• 返回正确的 HTTP 状态码
• 使用 @Valid 验证输入
• 实现异常映射器，确保错误响应一致

响应式模式

• 使用 Mutiny 进行响应式编程
• 利用 Uni 和 Multi 执行异步操作
• 适当结合响应式代码和命令式代码

数据访问

使用 Panache 的 Hibernate ORM

• 使用 Panache 简化 JPA 模式
• 利用 Active Record 或 Repository 模式
• 对具有内置操作的实体使用 PanacheEntity
• 使用 find 和 list 方法实现自定义查询

数据库操作

• 使用 Flyway 或 Liquibase 进行迁移
• 使用 Agroal 配置连接池
• 使用响应式数据库客户端实现非阻塞 I/O

测试

JUnit 5 集成

• 使用 @QuarkusTest 编写集成测试
• 使用 @QuarkusIntegrationTest 测试原生映像
• 利用测试配置文件处理不同配置

REST 端点测试

• 使用 rest-assured 测试端点
• 测试成功和错误场景
• 验证响应正文和状态码
• 测试身份验证和授权

性能优化

原生映像优化

• 使用 GraalVM 构建生产环境所用的原生映像
• 在开发过程中定期测试原生构建
• 必要时使用 @RegisterForReflection
• 尽量减少反射的使用

内存和启动

• 监控容器中的内存使用情况
• 针对无服务器冷启动进行优化
• 适当使用延迟初始化

可观测性

健康检查

• 使用 MicroProfile Health 实现存活性和就绪性探针
• 为依赖项实现自定义健康检查
• 根据健康端点配置 Kubernetes 探针

指标

• 使用 MicroProfile Metrics 获取应用指标
• 以 Prometheus 格式导出指标
• 为业务操作添加自定义指标

分布式追踪

• 使用 OpenTracing/OpenTelemetry 集成
• 在服务之间传递追踪上下文
• 为生产环境合理配置采样

安全

• 使用 Quarkus 安全扩展
• 使用 OIDC 或 JWT 实现身份验证
• 为 Web 客户端配置 CORS
• 验证并清理所有输入
• 在生产环境中使用 HTTPS

容器化

• 使用 Quarkus 容器镜像扩展
• 为原生镜像构建多阶段 Dockerfile
• 适当配置资源限制
• 使用 distroless 或精简基础镜像