如何使用Quarkus编写RESTful API？求架构类教程指引

一、快速搭建基础REST API项目 #

用Quarkus官方的项目生成命令可以快速初始化适合REST开发的项目结构，推荐用Maven执行：

mvn io.quarkus.platform:quarkus-maven-plugin:3.2.0.Final:create \
    -DprojectGroupId=com.example \
    -DprojectArtifactId=quarkus-rest-api \
    -Dextensions="resteasy-reactive-jackson"

这个命令会生成集成了RESTEasy Reactive（Quarkus推荐的高性能REST实现）和Jackson序列化工具的项目，省去手动配置的麻烦。

二、编写基础REST端点 #

在生成项目的src/main/java/com/example目录下创建API类，示例如下：

package com.example;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

@Path("/hello")
public class HelloResource {

    @GET
    @Produces(MediaType.TEXT_PLAIN)
    public String hello() {
        return "Hello from Quarkus REST API!";
    }
}

• @Path：定义API的基础访问路径
• @GET：指定该方法处理HTTP GET请求
• @Produces：声明响应的媒体类型

执行./mvnw quarkus:dev启动开发服务器，访问http://localhost:8080/hello即可看到响应结果。

三、架构层面的规范指导 #

Quarkus推荐结合自身轻量特性，遵循分层架构设计，各层职责清晰：

1. API层（表现层）
   • 仅处理HTTP相关逻辑：请求路由、参数解析、响应封装、参数校验
   • 不包含业务逻辑，通过依赖注入调用服务层完成业务处理
   • 用JAX-RS注解（@Path/@GET/@POST等）定义端点，配合@Valid实现参数校验
2. 服务层（业务逻辑层）
   • 封装核心业务规则，是API层与数据层的中间桥梁
   • 用@ApplicationScoped注解声明服务类，确保被Quarkus容器管理并可注入
   • 示例：

     @ApplicationScoped
     public class UserService {
         public User getUserById(Long id) {
             // 业务逻辑处理，比如调用数据层查询用户
             return User.findById(id);
         }
     }
     

3. 数据访问层
   • 负责与数据库的交互，推荐使用Quarkus Panache简化JPA操作，或直接使用JDBC客户端
   • 避免在服务层硬编码SQL，将数据操作封装到该层
   • Panache实体示例：

     @Entity
     public class User extends PanacheEntity {
         public String name;
         public String email;
     }
     

4. 通用组件
   • 错误处理：实现ExceptionMapper（用@Provider注解）统一拦截异常，返回标准化错误响应
   • 配置管理：用@ConfigProperty读取配置文件参数，避免硬编码
   • 日志：使用Quarkus自带的Jboss Logging，配合@Slf4j注解快速输出日志

四、进阶开发教程步骤 #

1. 扩展端点支持复杂参数与响应
   添加支持路径参数、查询参数的端点，返回JSON格式响应：

   @Inject
   UserService userService;
   
   @GET
   @Path("/user/{id}")
   @Produces(MediaType.APPLICATION_JSON)
   public User getUser(@PathParam("id") Long id) {
       return userService.getUserById(id);
   }
   

2. 处理POST请求创建资源
   接收JSON格式的请求体，完成资源创建：

   @POST
   @Path("/user")
   @Consumes(MediaType.APPLICATION_JSON)
   public Response createUser(@Valid User user) {
       user.persist();
       return Response.status(Response.Status.CREATED).build();
   }
   

3. 添加参数校验
   给实体类添加校验注解，API层用@Valid触发校验：

   @Entity
   public class User extends PanacheEntity {
       @NotBlank(message = "用户名不能为空")
       public String name;
       @Email(message = "邮箱格式不正确")
       public String email;
   }
   

4. 编写集成测试
   使用Quarkus集成的RESTAssured编写测试用例，确保API功能正常：

   package com.example;
   
   import io.quarkus.test.junit.QuarkusTest;
   import org.junit.jupiter.api.Test;
   
   import static io.restassured.RestAssured.given;
   import static org.hamcrest.CoreMatchers.is;
   
   @QuarkusTest
   public class HelloResourceTest {
   
       @Test
       public void testHelloEndpoint() {
           given()
             .when().get("/hello")
             .then()
                .statusCode(200)
                .body(is("Hello from Quarkus REST API!"));
       }
   }
   

五、最佳实践 #

• 优先使用RESTEasy Reactive替代传统RESTEasy，获得更好的性能表现
• 开发阶段使用quarkus:dev模式，支持热重载，修改代码无需重启服务
• 遵循RESTful设计原则：用合适的HTTP方法（GET/POST/PUT/DELETE），以名词命名资源路径
• 统一响应格式，比如采用包含code、message、data的标准结构
• 按需添加Quarkus扩展，比如quarkus-smallrye-openapi自动生成API文档

内容的提问来源于stack exchange，提问作者Abdel