java-quarkus-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Java Quarkus Development Best Practices

Java Quarkus开发最佳实践

Core Principles

核心原则

Write clean, efficient, and well-documented Java code using Quarkus best practices
Focus on fast startup and minimal memory footprint via GraalVM native builds
Leverage Quarkus extensions for common functionality
Design for containerized and serverless deployments
Follow SOLID principles and microservices architecture patterns

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

Development Workflow

开发工作流

Quarkus Dev Mode

Quarkus开发模式

Use
```
quarkus dev
```
for rapid iteration with live reload
Leverage continuous testing during development
Use Dev UI for debugging and configuration inspection
Take advantage of Dev Services for local development

使用
```
quarkus dev
```
实现带实时重载的快速迭代
开发过程中利用持续测试功能
使用Dev UI进行调试和配置检查
借助Dev Services进行本地开发

Configuration

配置

Type-Safe Configuration

类型安全配置

Use
```
@ConfigProperty
```
for type-safe configuration injection
Group related configs with
```
@ConfigMapping
```
interfaces
Validate configuration at startup
Document configuration properties

使用
```
@ConfigProperty
```
进行类型安全的配置注入
通过
```
@ConfigMapping
```
接口对相关配置进行分组
在启动时验证配置
记录配置属性

Profile-Based Configuration

基于环境的配置

Use
```
%dev
```
,
```
%test
```
,
```
%prod
```
prefixes for environment-specific configs
Override configs via environment variables in production
Keep sensitive values out of source control
Use
```
.env
```
files for local development

使用
```
%dev
```
,
```
%test
```
,
```
%prod
```
前缀实现环境特定配置
在生产环境中通过环境变量覆盖配置
敏感信息不要存入版本控制
本地开发使用
```
.env
```
文件

Dependency Injection

依赖注入

CDI Annotations

CDI注解

Use
```
@Inject
```
for dependency injection
Use
```
@Named
```
to qualify implementations

Use

@Singleton

@ApplicationScoped

@RequestScoped

appropriately

Prefer constructor injection for required dependencies

使用
```
@Inject
```
进行依赖注入
使用
```
@Named
```
限定实现类

合理使用

@Singleton

@ApplicationScoped

@RequestScoped

对于必需依赖，优先使用构造函数注入

Bean Discovery

Bean发现

Understand Quarkus build-time bean discovery
Use
```
@IfBuildProfile
```
for conditional beans
Avoid reflection-heavy patterns for native builds

了解Quarkus构建时Bean发现机制
使用
```
@IfBuildProfile
```
实现条件化Bean
原生构建中避免过度依赖反射的模式

REST API Development

REST API开发

RESTEasy Reactive

Use
```
@Path
```
,
```
@GET
```
,
```
@POST
```
, etc. for endpoint definitions
Return proper HTTP status codes
Use
```
@Valid
```
for input validation
Implement exception mappers for consistent error responses

使用
```
@Path
```
,
```
@GET
```
,
```
@POST
```
等定义端点
返回正确的HTTP状态码
使用
```
@Valid
```
进行输入验证
实现异常映射器以确保一致的错误响应

Reactive Patterns

响应式模式

Use Mutiny for reactive programming
Leverage
```
Uni
```
and
```
Multi
```
for async operations
Combine reactive with imperative code where appropriate

使用Mutiny进行响应式编程
利用
```
Uni
```
和
```
Multi
```
处理异步操作
在合适的场景结合响应式与命令式代码

Data Access

数据访问

Hibernate ORM with Panache

搭配Panache的Hibernate ORM

Use Panache for simplified JPA patterns
Leverage Active Record or Repository patterns
Use
```
PanacheEntity
```
for entities with built-in operations
Implement custom queries with
```
find
```
and
```
list
```
methods

使用Panache简化JPA模式
利用活动记录或仓库模式
使用
```
PanacheEntity
```
实现内置操作的实体类
通过
```
find
```
和
```
list
```
方法实现自定义查询

Database Operations

数据库操作

Use Flyway or Liquibase for migrations
Configure connection pooling with Agroal
Use reactive database clients for non-blocking I/O

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

Testing

测试

JUnit 5 Integration

JUnit 5集成

Use
```
@QuarkusTest
```
for integration tests
Use
```
@QuarkusIntegrationTest
```
for native image tests
Leverage test profiles for different configurations

使用
```
@QuarkusTest
```
进行集成测试
使用
```
@QuarkusIntegrationTest
```
进行原生镜像测试
利用测试环境实现不同配置

REST Endpoint Testing

REST端点测试

Use rest-assured for endpoint testing
Test both success and error scenarios
Verify response bodies and status codes
Test authentication and authorization

使用rest-assured进行端点测试
测试成功与错误场景
验证响应体与状态码
测试认证与授权

Performance Optimization

性能优化

Native Image Optimization

原生镜像优化

Build native images with GraalVM for production
Test native builds regularly during development
Use
```
@RegisterForReflection
```
when needed
Minimize reflection usage

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

Memory and Startup

内存与启动优化

Monitor memory usage in containers
Optimize for serverless cold starts
Use lazy initialization where appropriate

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

Observability

可观测性

Health Checks

健康检查

Use MicroProfile Health for liveness and readiness probes
Implement custom health checks for dependencies
Configure Kubernetes probes based on health endpoints

使用MicroProfile Health实现存活与就绪探针
为依赖项实现自定义健康检查
基于健康端点配置Kubernetes探针

Metrics

指标

Use MicroProfile Metrics for application metrics
Export metrics in Prometheus format
Add custom metrics for business operations

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

Distributed Tracing

分布式追踪

Use OpenTracing/OpenTelemetry integration
Propagate trace context across services
Configure sampling appropriately for production

集成OpenTracing/OpenTelemetry
在服务间传播追踪上下文
为生产环境合理配置采样策略

Security

安全

Use Quarkus Security extensions
Implement authentication with OIDC or JWT
Configure CORS for web clients
Validate and sanitize all inputs
Use HTTPS in production

使用Quarkus Security扩展
基于OIDC或JWT实现认证
为Web客户端配置CORS
验证并清理所有输入
生产环境使用HTTPS

Containerization

容器化

Use Quarkus container image extensions
Build multi-stage Dockerfiles for native images
Configure resource limits appropriately
Use distroless or minimal base images

使用Quarkus容器镜像扩展
为原生镜像构建多阶段Dockerfile
合理配置资源限制
使用无发行版或最小化基础镜像