🔥 FREE PRO OFFER Linkage.page Pro Version is 100% Free of Cost till 31 December, 2026! Claim Free Pro

软件架构

使用 Java Quarkus 构建 REST API:高性能、响应式和云原生指南

使用 Java Quarkus 构建 REST API:高性能、响应式和云原生指南

在现代企业软件工程中,构建 RESTful API 是后端系统开发的核心石。几十年来,Java 开发者一直依赖 Spring Boot 或 Jakarta EE 等传统框架。 Quarkus 应运而生——这是专为 OpenJDK HotSpot 和 GraalVM 量身定制的 Supersonic Subatomic Java 框架。 1. 为什么选择 Quarkus 构建 Java REST API? A. RESTEasy 响应式范式 B. Dev Services 与零配置实时编码 2. Quarkus REST API 架构 3. 项目初始化与依赖项 mvn io.quarkus.platform:quarkus-maven-plugin:3.15.0:create \ -DprojectGroupId=com.ghaznix.api \ -DprojectArtifactId=quarkus-product-api \ -DclassName="com.ghaznix.api.ProductResource" \ -Dpath="/api/products" \ -Dextensions="resteasy-reactive-jackson,hibernate-orm-panache,jdbc-postgresql,hibernate-validator,smallrye-openapi" 4. 配置应用程序属性 # Application Configuration quarkus.application.name=quarkus-product-api quarkus.http.port=8080 # Database Configuration (Dev Services will override in dev mode automatically) quarkus.datasource.db-kind=postgresql quarkus.datasource.username=postgres quarkus.datasource.password=secret quarkus.datasource.jdbc.url=jdbc:postgresql://localhost:5432/product_db # Hibernate ORM Configuration quarkus.hibernate-orm.database.generation=drop-and-create quarkus.hibernate-orm.log.sql=true # Swagger UI & OpenAPI Path quarkus.swagger-ui.always-include=true quarkus.swagger-ui.path=/swagger-ui 5. 领域模型与 Panache Active Record package com.ghaznix.api; import io.quarkus.hibernate.orm.panache.PanacheEntity; import jakarta.persistence.Column; import jakarta.persistence.Entity; import jakarta.persistence.Table; import jakarta.validation.constraints.Min; import jakarta.validation.constraints.NotBlank; import jakarta.validation.constraints.NotNull; import java.math.BigDecimal; import java.util.List; @Entity @Table(name = "products") public class Product extends PanacheEntity { @NotBlank(message = "Product name cannot be blank") @Column(nullable = false) public String name; @Column(length = 1000) public String description; @NotNull(message = "Price is required") @Min(value = 0, message = "Price must be non-negative") @Column(nullable = false) public BigDecimal price; @Column(nullable = false) public Integer stockQuantity; public String category; // Static Finder Utility Methods powered by Panache public static List<Product> findByCategory(String category) { return list("category", category); } public static List<Product> findAvailableProducts() { return list("stockQuantity > 0"); } } 6. 构建生产级 REST 端点 package com.ghaznix.api; import io.quarkus.panache.common.Page; import io.quarkus.panache.common.Sort; import jakarta.transaction.Transactional; import jakarta.validation.Valid; import jakarta.ws.rs.*; import jakarta.ws.rs.core.MediaType; import jakarta.ws.rs.core.Response; import org.eclipse.microprofile.openapi.annotations.Operation; import org.eclipse.microprofile.openapi.annotations.responses.APIResponse; import org.eclipse.microprofile.openapi.annotations.tags.Tag; import java.net.URI; import java.util.List; @Path("/api/products") @Produces(MediaType.APPLICATION_JSON) @Consumes(MediaType.APPLICATION_JSON) @Tag(name = "Product REST API", description = "Operations for managing catalog products") public class ProductResource { @GET @Operation(summary = "Get all products with pagination") @APIResponse(responseCode = "200", description = "List of products retrieved successfully") public List<Product> getAllProducts( @QueryParam("page") @DefaultValue("0") int pageIndex, @QueryParam("size") @DefaultValue("10") int pageSize, @QueryParam("sort") @DefaultValue("name") String sortBy) { return Product.findAll(Sort.by(sortBy)) .page(Page.of(pageIndex, pageSize)) .list(); } @GET @Path("/{id}") @Operation(summary = "Get product by ID") @APIResponse(responseCode = "200", description = "Product details found") @APIResponse(responseCode = "404", description = "Product not found") public Product getProductById(@PathParam("id") Long id) { Product product = Product.findById(id); if (product == null) { throw new NotFoundException("Product with ID " + id + " does not exist."); } return product; } @POST @Transactional @Operation(summary = "Create a new product") @APIResponse(responseCode = "201", description = "Product created successfully") @APIResponse(responseCode = "400", description = "Invalid request payload") public Response createProduct(@Valid Product product) { product.persist(); return Response.created(URI.create("/api/products/" + product.id)) .entity(product) .build(); } @PUT @Path("/{id}") @Transactional @Operation(summary = "Update an existing product") @APIResponse(responseCode = "200", description = "Product updated") @APIResponse(responseCode = "404", description = "Product ID not found") public Product updateProduct(@PathParam("id") Long id, @Valid Product updatedProduct) { Product entity = Product.findById(id); if (entity == null) { throw new NotFoundException("Product with ID " + id + " not found."); } entity.name = updatedProduct.name; entity.description = updatedProduct.description; entity.price = updatedProduct.price; entity.stockQuantity = updatedProduct.stockQuantity; entity.category = updatedProduct.category; return entity; } @DELETE @Path("/{id}") @Transactional @Operation(summary = "Delete a product by ID") @APIResponse(responseCode = "204", description = "Product deleted successfully") @APIResponse(responseCode = "404", description = "Product ID not found") public Response deleteProduct(@PathParam("id") Long id) { boolean deleted = Product.deleteById(id); if (!deleted) { throw new NotFoundException("Product with ID " + id + " not found."); } return Response.noContent().build(); } } 7. 响应式 REST 端点与阻塞执行 import io.smallrye.mutiny.Uni; import io.smallrye.mutiny.Multi; @GET @Path("/reactive/{id}") public Uni<Product> getProductReactive(@PathParam("id") Long id) { return Product.<Product>findByIdAsync(id) .onItem().ifNull().failWith(new NotFoundException("Product not found")); } @GET @Path("/stream") @Produces(MediaType.SERVER_SENT_EVENTS) public Multi<Product> streamProducts() { return Product.streamAll(); } 8. 全局异常处理与错误标准 package com.ghaznix.api.exception; import jakarta.ws.rs.NotFoundException; import jakarta.ws.rs.core.MediaType; import jakarta.ws.rs.core.Response; import jakarta.ws.rs.ext.ExceptionMapper; import jakarta.ws.rs.ext.Provider; import java.time.Instant; import java.util.HashMap; import java.util.Map; @Provider public class GlobalExceptionMapper implements ExceptionMapper<Exception> { @Override public Response toResponse(Exception exception) { Map<String, Object> errorPayload = new HashMap<>(); errorPayload.put("timestamp", Instant.now().toString()); if (exception instanceof NotFoundException) { errorPayload.put("status", 404); errorPayload.put("error", "Not Found"); errorPayload.put("message", exception.getMessage()); return Response.status(Response.Status.NOT_FOUND) .entity(errorPayload) .type(MediaType.APPLICATION_JSON) .build(); } errorPayload.put("status", 500); errorPayload.put("error", "Internal Server Error"); errorPayload.put("message", exception.getMessage()); return Response.status(Response.Status.INTERNAL_SERVER_ERROR) .entity(errorPayload) .type(MediaType.APPLICATION_JSON) .build(); } } 9. 使用 @QuarkusTest 和 REST Assured 进行自动化测试 package com.ghaznix.api; import io.quarkus.test.junit.QuarkusTest; import io.restassured.http.ContentType; import org.junit.jupiter.api.Test; import static io.restassured.RestAssured.given; import static org.hamcrest.CoreMatchers.*; @QuarkusTest public class ProductResourceTest { @Test public void testGetAllProductsEndpoint() { given() .when().get("/api/products") .then() .statusCode(200) .contentType(ContentType.JSON); } @Test public void testCreateAndGetProduct() { Product product = new Product(); product.name = "Gaming Laptop"; product.description = "High-performance GPU laptop"; product.price = new java.math.BigDecimal("1499.99"); product.stockQuantity = 15; product.category = "Electronics"; // Test POST Endpoint Integer createdId = given() .contentType(ContentType.JSON) .body(product) .when().post("/api/products") .then() .statusCode(201) .body("name", equalTo("Gaming Laptop")) .extract().path("id"); // Test GET Endpoint by ID given() .pathParam("id", createdId) .when().get("/api/products/{id}") .then() .statusCode(200) .body("category", equalTo("Electronics")); } } ./mvnw test 10. 打包并编译为 GraalVM 原生可执行文件 ./mvnw quarkus:dev ./mvnw package java -jar target/quarkus-app/quarkus-run.jar ./mvnw package -Dnative -Dquarkus.native.container-build=true ./target/quarkus-product-api-1.0.0-runner 2026-09-21 22:30:00,014 INFO [io.quarkus] (main) quarkus-product-api 1.0.0-runner native (powered by Quarkus 3.15.0) started in 0.018s. Listening on: http://0.0.0.0:8080 11. 性能基准测试:Quarkus 与 Spring Boot 指标 Spring Boot (JVM) Quarkus (OpenJDK JVM) Quarkus (GraalVM Native) 提升 启动时间 (冷启动) 3.82 秒 1.18 秒 0.015 秒 快 254 倍 内存占用 (RSS) 184 MB 108 MB 28 MB 内存降低 84% 12. 总结与最佳实践 Ghaznix Blog.
Java Quarkus REST API 微服务 GraalVM 响应式编程 Hibernate Panache 云原生 软件架构
编排与编排:设计微服务中的分布式工作流程

编排与编排:设计微服务中的分布式工作流程

在整体架构中,执行复杂的业务交易(例如履行电子商务订单)非常简单。所有数据都驻留在单个关系数据库中,允许开发人员将跨库存、支付和运输的多个数据库写入包装在单个 ACID 事务中。如果任何时候发生错误,SQL ROLLBACK 会立即恢复系统一致性。 然而,现代云原生系统采用微服务架构,其中每个服务都拥有自己的数据并公开不同的 API 边界。在这种分布式范例中,单个端到端业务操作跨越多个独立的微服务和数据库引擎。 由于两阶段提交 (2PC) 协议在云网络中速度缓慢、阻塞且脆弱,因此分布式系统必须异步协调工作流程,同时保持最终一致性。 这使软件架构师做出了一个基本的设计决策:您应该使用编排还是编排来管理分布式微服务工作流程? 在这份综合指南中,我们将分解这两种架构模式,探索现实世界的类比,分析架构权衡,详细介绍 Go 和 Java 中的生产代码实现,并建立一个框架来为您的基础设施选择正确的模式。 现实世界的类比:快闪族与交响乐团 要为这两种模式建立直观的心理模型,请考虑人类表演者群体如何协调他们的行动: 编舞类比:快闪舞者网络 想象一下一群专业街舞者表演快闪表演。没有教练站在舞台上指着个别舞者指挥他们的下一步动作。相反,每个舞者都会聆听中心音乐,并对旁边舞者的动作做出动态反应。 当舞者 A 完成翻转时,舞者 B 识别出该视觉提示并开始旋转。 当舞者B完成旋转后,舞者C向前迈出一步。 关键特征:去中心化、反应性和自主性。每个参与者都明白自己的责任,无需中央指导。 编排类比:交响乐团 现在想象一下一个由 70 名乐手组成的古典交响乐团。小提琴手、打击乐手和大提琴手不会通过观察舞台上彼此的手来获得暗示。相反,所有人都直视指挥。 指挥向小提琴发出何时演奏软弦的信号。 指挥指向鼓以发出打击乐的信号。 如果音乐家错过节奏,指挥会协调节奏调整或发出暂停信号。 关键特征:集中、明确、命令驱动。一名领导者指导所有参与者。 1.编排架构:去中心化和事件驱动 在编排中,分布式微服务在没有中央主协调器的情况下进行反应式通信。每当服务的内部状态发生变化时,服务都会将域事件发布到异步消息代理(例如 Apache Kafka、RabbitMQ 或 AWS EventBridge)。下游微服务订阅相关事件主题并独立决定下一步采取什么行动。 编排下的电子商务流程 考虑使用编排的电子商务结账流程: 订单服务:接收 HTTP POST 结帐请求,将挂单写入其数据库,并向 Kafka 事件总线发出 OrderCreated 域事件。 支付服务:订阅OrderCreated主题。收到事件后,它会向客户的信用卡收费并发出 PaymentProcessed 事件。 库存服务:订阅 PaymentProcessed 主题。它保留仓库物品并发出 InventoryReserved 事件。 运送服务:订阅InventoryReserved主题。它生成运输标签并发出 OrderShipped 事件。 通知服务:订阅OrderShipped并向客户发送跟踪电子邮件。 编排的优点 高度自治和松耦合:服务不知道下游处理程序的存在。订单服务只知道订单已创建;它并不关心谁使用该信息。 独立的可扩展性和速度:团队可以独立构建、部署和扩展微服务。添加新功能(例如,跟踪销售的分析服务)需要订阅现有事件,而无需修改上游代码。 无单点故障(SPOF):因为没有中央工作流协调器,所以不相关服务的故障不会导致整个执行引擎瘫痪。 高性能和吞吐量:事件驱动的发布/订阅流异步处理大量事件,没有同步 HTTP/gRPC 阻塞延迟。 编排的缺点 隐式工作流逻辑:没有单个代码位置定义端到端业务流程。了解整个工作流程需要将多个代码库中的事件处理程序拼凑在一起。 循环依赖风险:如果微服务在没有仔细主题设计的情况下发布和订阅重叠主题,则无限事件循环可能会导致系统消息队列崩溃。 复杂的可观测性和分布式跟踪:跨 10 个事件主题跟踪单个订单交易需要强大的分布式跟踪基础设施(例如 OpenTelemetry、Jaeger、W3C Trace Context)。 困难的错误处理和补偿:如果付款成功后库存服务失败,则库存服务必须发出 InventoryFailed 事件。支付服务必须侦听此事件并手动触发退款补偿。 2.编排架构:集中式和命令驱动 在编排中,专用协调器服务(Saga Orchestrator)显式指导执行顺序。 Orchestrator 持有工作流状态机,向工作微服务发送命令请求(通过 gRPC、HTTP REST 或专用命令队列),等待响应并确定下一个执行步骤。
微服务 编舞 编排 系统设计 分布式系统 传奇模式 事件驱动架构 软件架构