1. 概述

在本教程中，我們將探討使用開源框架 Jersey 中的 Bean 驗證。

正如我們在之前的文章中所看到，Jersey 是一個用於開發 RESTful Web Services 的開源框架。

驗證是核實某些數據是否符合預定義的約束的過程。這在大多數應用程序中是一個非常常見的用例。

Java Bean Validation 框架 (JSR-380) 已成為 Java 中處理此類操作的默認標準。為了回顧 Java Bean Validation 的基本知識，請參考我們的上一篇教程。

Jersey 包含一個擴展模塊，用於支持 Bean Validation。要使用此功能，我們首先需要在我們的應用程序中進行配置。在下一部分，我們將看到如何配置我們的應用程序。

3. 應用程序設置

現在，讓我們基於來自《Jersey MVC 支持》出色文章的簡單水果 API 示例進行構建。

3.1. Maven 依賴項

首先，讓我們將 Bean 驗證依賴項添加到我們的 pom.xml 中：

<dependency>
    <groupId>org.glassfish.jersey.ext</groupId>
    <artifactId>jersey-bean-validation</artifactId>
    <version>3.1.1</version>
</dependency>

我們可以從 Maven Central 獲取最新版本。

3.2. 配置服務器

在 Jersey 中，我們通常在自定義資源配置類中註冊我們想要使用的擴展功能。

但是，對於 Bean 驗證擴展，不需要進行此註冊。 幸運的是，這是 Jersey 框架自動註冊的少數擴展之一。

最後，為了將驗證錯誤發送到客户端 我們將一個服務器屬性添加到我們的自定義資源配置：

public ViewApplicationConfig() {
    packages("com.baeldung.jersey.server");
    property(ServerProperties.BV_SEND_ERROR_IN_RESPONSE, true);
}

4. 有效的 JAX-RS 資源方法

在本節中，我們將解釋兩種使用約束註解進行輸入參數驗證的方法：

• 使用內置 Bean Validation API 約束
• 創建自定義約束和驗證器

4.1. 使用內置約束註解

我們首先看一下內置的約束註解：

@POST
@Path("/create")
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
public void createFruit(
    @NotNull(message = "Fruit name must not be null") @FormParam("name") String name, 
    @NotNull(message = "Fruit colour must not be null") @FormParam("colour") String colour) {

    Fruit fruit = new Fruit(name, colour);
    SimpleStorageService.storeFruit(fruit);
}

在這個例子中，我們使用兩個表單參數 name 和 colour 創建一個新的 Fruit。我們使用了 @NotNull 標註，它已包含在 Bean Validation API 中。

這會對我們的表單參數施加一個簡單的非空約束。 如果其中一個參數為 null，則在註解中聲明的消息將被返回。

當然，我們將用一個單元測試來演示這一點：

@Test
public void givenCreateFruit_whenFormContainsNullParam_thenResponseCodeIsBadRequest() {
    Form form = new Form();
    form.param("name", "apple");
    form.param("colour", null);
    Response response = target("fruit/create").request(MediaType.APPLICATION_FORM_URLENCODED)
        .post(Entity.form(form));

    assertEquals("Http Response should be 400 ", 400, response.getStatus());
    assertThat(response.readEntity(String.class), containsString("Fruit colour must not be null"));
}

在這個例子中，我們使用 JerseyTest 支持類來測試我們的水果資源。我們發送一個帶有 colour 為 null 的 POST 請求，並檢查響應是否包含預期的消息。

對於內置的驗證約束列表，請查看 文檔。

4.2. 定義自定義約束註解

有時我們需要施加更復雜的約束。 我們可以通過定義自己的自定義註解來實現這一點。

假設我們使用簡單的水果 API 示例，我們需要驗證所有水果具有有效的序列號：

@PUT
@Path("/update")
@Consumes("application/x-www-form-urlencoded")
public void updateFruit(@SerialNumber @FormParam("serial") String serial) {
    //...
}

在這個例子中，serial 參數必須滿足 @SerialNumber 註解定義的約束：

@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = { SerialNumber.Validator.class })
    public @interface SerialNumber {

    String message()

    default "Fruit serial number is not valid";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};
}

接下來，我們將定義驗證器類 SerialNumber.Validator：

public class Validator implements ConstraintValidator<SerialNumber, String> {
    @Override
    public void initialize(SerialNumber serial) {
    }

    @Override
    public boolean isValid(String serial, 
        ConstraintValidatorContext constraintValidatorContext) {
        
        String serialNumRegex = "^\\d{3}-\\d{3}-\\d{4}$";
        return Pattern.matches(serialNumRegex, serial);
    }
}

關鍵點在於 Validator 類必須 實現 ConstraintValidator，其中 T 是我們想要驗證的值的類型，在本例中是 String

最後，我們將 實現 我們的自定義驗證邏輯在 isValid 方法中。

5. 資源驗證

此外，Bean驗證API也允許我們使用註解來驗證對象。

@XmlRootElement
public class Fruit {

    @Min(value = 10, message = "Fruit weight must be 10 or greater")
    private Integer weight;
    //...
}

@POST
@Path("/create")
@Consumes("application/json")
public void createFruit(@Valid Fruit fruit) {
    SimpleStorageService.storeFruit(fruit);
}

@GET
@Valid
@Produces("application/json")
@Path("/search/{name}")
public Fruit findFruitByName(@PathParam("name") String name) {
    return SimpleStorageService.findByName(name);
}

public class FruitExceptionMapper implements ExceptionMapper<ConstraintViolationException> {

    @Override
    public Response toResponse(ConstraintViolationException exception) {
        return Response.status(Response.Status.BAD_REQUEST)
            .entity(prepareMessage(exception))
            .type("text/plain")
            .build();
    }

    private String prepareMessage(ConstraintViolationException exception) {
        StringBuilder message = new StringBuilder();
        for (ConstraintViolation<?> cv : exception.getConstraintViolations()) {
            message.append(cv.getPropertyPath() + " " + cv.getMessage() + "\n");
        }
        return message.toString();
    }
}

@Override
protected Application configure() {
    ViewApplicationConfig config = new ViewApplicationConfig();
    config.register(FruitExceptionMapper.class);
    return config;
}

@GET
@Produces(MediaType.TEXT_HTML)
@Path("/exception")
@Valid
public Fruit exception() {
    Fruit fruit = new Fruit();
    fruit.setName("a");
    fruit.setColour("b");
    return fruit;
}