Java API 開發中使用 Bean Validation 進行參數校驗

在 Java API 的開發中，參數校驗是一個非常重要的環節。使用 Bean Validation 框架可以方便地實現對參數的校驗，從而保證 API 的參數傳遞的合法性。本文將介紹 Bean Validation 的使用方法。

一、什麼是 Bean Validation？

Bean Validation 是 Java EE 6 規格中的一部分。它是一個基於註解的參數校驗框架，可以用於在方法、建構子、欄位和屬性等註解中加入校驗規則。這些註解可以幫助開發人員在程式碼編寫階段更好地預防輸入錯誤，並在執行時偵測和提示使用者輸入錯誤。

Bean Validation 框架主要解決以下問題：

1. 驗證業務邏輯和限制（例如：是否為空、是否為郵件信箱、是否為數字等）。
2. 驗證格式和文法（例如：日期、電話號碼、郵遞區號等）。
3. 驗證兩個或多個欄位的互相依賴性（例如：開始日期必須早於結束日期）。

二、Bean Validation 如何運作？

Bean Validation 框架使用註解來標註需要校驗的參數，這些註解包括 @NotNull、@Min、@Max、@Size、@Pattern 等。當參數被傳遞到​​方法中時，Bean Validation 框架會自動執行對應的校驗規則，當校驗失敗時，Bean Validation 框架會傳送錯誤訊息。開發人員可以編寫自訂的校驗規則，以滿足業務需求。

Bean Validation 框架提供了一組預先定義的校驗規則，這些規則可以應用於 Java Bean 中的屬性和方法參數。預先定義的規則包括：

@NotNull：檢查是否為空值

@Size：檢查String、Collection、Map和陣列的長度

##@Min、@Max ：檢查數值的大小

@Email：檢查是否為電子郵件地址

@Pattern：根據正規表示式檢查字串

使用Bean Validation 框架時，需要在類別路徑下包含javax.validation-api 和對應的Bean Validation 實現，例如Hibernate Validator，透過Maven，可以加入以下依賴：

<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>2.0.1.Final</version>
</dependency>
<dependency>
    <groupId>org.hibernate.validator</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>6.0.10.Final</version>
</dependency>

三、Bean Validation 範例

假設我們有一個User 類，其中包含了使用者的基本訊息，現在需要對User 類別中的屬性進行校驗：

public class User {
    private String name;
    private Integer age;
    private String email;
    private String address;
  
    // getters and setters
}

專案所需的校驗規則如下：

name 不為空且長度大於5 且小於10；
1. age 不為空且大於0 且小於200；
2. email 不為空且為有效的郵箱位址；
3. # address 可以為空。

我們可以使用Bean Validation 來定義這些校驗規則，具體實作如下：

public class UserValidator {

    private Validator validator;

    public UserValidator() {
        ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
        validator = factory.getValidator();
    }

    /**
     * 对 User 对象进行校验
     * 
     * @param user
     * @return
     */
    public String validate(User user) {

        Set<ConstraintViolation<User>> violations = validator.validate(user);

        StringBuilder result = new StringBuilder();
        if (!violations.isEmpty()) {
            for (ConstraintViolation<User> violation : violations) {
                result.append(violation.getMessage()).append(";");
            }
        }

        return result.toString();
    }
}

在UserValidator 類別中，我們使用了Validator 工具類，透過buildDefaultValidatorFactory() 方法建立一個ValidatorFactory 對象，從而建立一個實例化的Validator 物件。透過呼叫 validator.validate(user) 方法，可以對 User 物件進行校驗。對於校驗結果，我們將所有錯誤訊息記錄在 StringBuilder 物件中，並傳回給呼叫端。

最後，我們可以在測試類別中使用UserValidator 物件並進行測試：

public class UserValidatorTest {
  
    @Test
    void testValidateUser() {
        User user = new User();
        user.setName("abcd");
        user.setAge(300);
        user.setEmail("abc");
        user.setAddress(null);

        UserValidator validator = new UserValidator();
        String result = validator.validate(user);

        assertThat(result, containsString("Name length must be between 5 and 10."));
        assertThat(result, containsString("Size must be between 1 and 200."));
        assertThat(result, containsString("must be a well-formed email address"));
    }
}

在上面的測試方法中，我們建立了一個User 對象，其中的屬性不符合校驗規則，因此呼叫UserValidator 的validate() 方法會傳回對應的錯誤訊息。

四、總結

本文介紹了 Bean Validation 框架的概念和使用方法。此框架透過註解對參數進行校驗，可以幫助開發人員在編寫程式碼時預防輸入錯誤，在執行時偵測並提示使用者輸入錯誤。同時，開發人員可以根據業務需求編寫自訂的校驗規則，滿足更複雜的校驗場景。

以上是Java API 開發中使用 Bean Validation 進行參數校驗的詳細內容。更多資訊請關注PHP中文網其他相關文章！