# 一、背景

服務端在向外提供介面服務時，不管是對前端提供HTTP介面，還是面向內部其他服務端提供的RPC介面，常常會面對這樣一個問題，就是如何優雅的解決各種介面引數校驗問題？

早期大家在做面向前端提供的HTTP介面時，對引數的校驗可能都會經歷這幾個階段：每個介面每個引數都寫定製校驗程式碼、提煉公共校驗邏輯、自定義切面進行校驗、通用標準的校驗邏輯。

這邊提到的通用標準的校驗邏輯指的就是基於JSR303的[Java Bean Validation](https://beanvalidation.org/)，其中官方指定的具體實現就是 [Hibernate Validator](http://hibernate.org/validator/)，在Web專案中結合Spring可以做到很優雅的去進行引數校驗。

本文主要也是想給大家介紹下如何在使用Dubbo時做好優雅的引數校驗。

# 二、解決方案

Dubbo框架本身是支援引數校驗的，同時也是基於JSR303去實現的，我們來看下具體是怎麼實現的。

## 2.1 maven依賴

```java

<dependency>
    <groupid>javax.validation</groupid>
    <artifactid>validation-api</artifactid>
    <version>2.0.1.Final</version>

    <scope>provided</scope>
</dependency>
 

<dependency>
    <groupid>org.hibernate.validator</groupid>
    <artifactid>hibernate-validator</artifactid>
    <version>6.2.0.Final</version>
</dependency>

```

## 2.2 介面定義

facade介面定義：

```java
public interface UserFacade {
    FacadeResult<boolean> updateUser(UpdateUserParam param);
}

```

引數定義

```java
public class UpdateUserParam implements Serializable {
    private static final long serialVersionUID = 2476922055212727973L;
 
    @NotNull(message = "使用者標識不能為空")
    private Long id;
    @NotBlank(message = "使用者名稱不能為空")
    private String name;
    @NotBlank(message = "使用者手機號不能為空")
    @Size(min = 8, max = 16, message="電話號碼長度介於8~16位")
    private String phone;
 
    // getter and setter ignored
}

```

公共返回定義

```java
/**
 * Facade介面統一返回結果
 */
public class FacadeResult<t> implements Serializable {
    private static final long serialVersionUID = 8570359747128577687L;
 
    private int code;
    private T data;
    private String msg;
    // getter and setter ignored
}

```

## 2.3 Dubbo服務提供者端配置

Dubbo服務提供者端必須作這個validation="true"的配置，具體示例配置如下：

Dubbo介面服務端配置

```java
<bean class="com.xxx.demo.UserFacadeImpl" id="userFacade"></bean>
<service interface="com.xxx.demo.UserFacade" ref="userFacade" validation="true"></service>

```

## 2.4 Dubbo服務消費者端配置

這個根據業務方使用習慣不作強制要求，但建議配置上都加上validation="true"，示例配置如下：

```java
<reference id="userFacade" interface="com.xxx.demo.UserFacade" validation="true"></reference>

```

## 2.5 驗證引數校驗

前面幾步完成以後，驗證這一步就比較簡單了，消費者呼叫該約定介面，介面入參傳入UpdateUserParam物件，其中欄位不用賦值，然後呼叫服務端介面就會得到如下的引數異常提示：

Dubbo介面服務端配置

```java
javax.validation.ValidationException: Failed to validate service: com.xxx.demo.UserFacade, method: updateUser, cause: [ConstraintViolationImpl{interpolatedMessage='使用者名稱不能為空', propertyPath=name, rootBeanClass=class com.xxx.demo.UpdateUserParam, messageTemplate='使用者名稱不能為空'}, ConstraintViolationImpl{interpolatedMessage='使用者手機號不能為空', propertyPath=phone, rootBeanClass=class com.xxx.demo.UpdateUserParam, messageTemplate='使用者手機號不能為空'}, ConstraintViolationImpl{interpolatedMessage='使用者標識不能為空', propertyPath=id, rootBeanClass=class com.xxx.demo.UpdateUserParam, messageTemplate='使用者標識不能為空'}]
javax.validation.ValidationException: Failed to validate service: com.xxx.demo.UserFacade, method: updateUser, cause: [ConstraintViolationImpl{interpolatedMessage='使用者名稱不能為空', propertyPath=name, rootBeanClass=class com.xxx.demo.UpdateUserParam, messageTemplate='使用者名稱不能為空'}, ConstraintViolationImpl{interpolatedMessage='使用者手機號不能為空', propertyPath=phone, rootBeanClass=class com.xxx.demo.UpdateUserParam, messageTemplate='使用者手機號不能為空'}, ConstraintViolationImpl{interpolatedMessage='使用者標識不能為空', propertyPath=id, rootBeanClass=class com.xxx.demo.UpdateUserParam, messageTemplate='使用者標識不能為空'}]
    at org.apache.dubbo.validation.filter.ValidationFilter.invoke(ValidationFilter.java:96)
    at org.apache.dubbo.rpc.protocol.ProtocolFilterWrapper$1.invoke(ProtocolFilterWrapper.java:83)
    ....
    at org.apache.dubbo.remoting.exchange.support.header.HeaderExchangeHandler.received(HeaderExchangeHandler.java:175)
    at org.apache.dubbo.remoting.transport.DecodeHandler.received(DecodeHandler.java:51)
    at org.apache.dubbo.remoting.transport.dispatcher.ChannelEventRunnable.run(ChannelEventRunnable.java:57)
    at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149)
    at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624)
    at java.lang.Thread.run(Thread.java:748)

```

# 三、定製Dubbo引數校驗異常返回

從前面內容我們可以很輕鬆的驗證，當消費端呼叫Dubbo服務時，引數如果不合法就會丟擲相關異常資訊，消費端呼叫時也能識別出異常資訊，似乎這樣就沒有問題了。

但從前面所定義的服務介面來看，一般業務開發會定義統一的返回物件格式（如前文示例中的FacadeResult），對於業務異常情況，會約定相關異常碼並結合相關性資訊提示。因此對於引數校驗不合法的情況，服務呼叫方自然不希望服務端丟擲一大段包含堆疊資訊的異常資訊，而是希望還保持這種統一的返回形式，就如下面這種返回所示：

Dubbo介面服務端配置：

```java
{ 
  "code": 1001,
  "msg": "使用者名稱不能為空",
  "data": null
}

```

## 3.1 ValidationFilter & JValidator

想要做到返回格式的統一，我們先來看下前面所丟擲的異常是如何來的？

從異常堆疊內容我們可以看出這個異常資訊返回是由ValidationFilter丟擲的，從名字我們可以猜到這個是採用Dubbo的Filter擴充套件機制的一個內建實現，當我們對Dubbo服務介面啟用引數校驗時（即前文Dubbo服務配置中的validation="true")，該Filter就會真正起作用，我們來看下其中的關鍵實現邏輯：

```java
@Override
public Result invoke(Invoker> invoker, Invocation invocation) throws RpcException {
    if (validation != null && !invocation.getMethodName().startsWith("$")
            && ConfigUtils.isNotEmpty(invoker.getUrl().getMethodParameter(invocation.getMethodName(), VALIDATION_KEY))) {
        try {
            Validator validator = validation.getValidator(invoker.getUrl());
            if (validator != null) {
                // 注1
                validator.validate(invocation.getMethodName(), invocation.getParameterTypes(), invocation.getArguments());
            }
        } catch (RpcException e) {
            throw e;
        } catch (ValidationException e) {
            // 注2
            return AsyncRpcResult.newDefaultAsyncResult(new ValidationException(e.getMessage()), invocation);
        } catch (Throwable t) {
            return AsyncRpcResult.newDefaultAsyncResult(t, invocation);
        }
    }
    return invoker.invoke(invocation);
}

```

從前文的異常堆疊資訊我們可以知道異常資訊是由上述程式碼「注2」處所產生，這邊是因為捕獲了ValidationException，透過走讀程式碼或者除錯可以得知，該異常是由「注1」處valiator.validate方法所產生。

而Validator介面在Dubbo框架中實現只有JValidator，這個透過idea工具顯示Validator所有實現的UML類圖可以看出（如下圖所示），當然除錯程式碼也可以很輕鬆定位到。

![](https://static001.geekbang.org/infoq/d1/d164f51cd03c84e9236a5805d05676ab.png)

既然定位到JValidator了，我們就繼續看下它裡面validate方法的具體實現，關鍵程式碼如下所示：

```java
@Override
public void validate(String methodName, Class>[] parameterTypes, Object[] arguments) throws Exception {
    List<class>> groups = new ArrayList<>();
    Class> methodClass = methodClass(methodName);
    if (methodClass != null) {
        groups.add(methodClass);
    }
    Set<constraintviolation>> violations = new HashSet<>();
    Method method = clazz.getMethod(methodName, parameterTypes);
    Class>[] methodClasses;
    if (method.isAnnotationPresent(MethodValidated.class)){
        methodClasses = method.getAnnotation(MethodValidated.class).value();
        groups.addAll(Arrays.asList(methodClasses));
    }
    groups.add(0, Default.class);
    groups.add(1, clazz);
 
    Class>[] classgroups = groups.toArray(new Class[groups.size()]);
 
    Object parameterBean = getMethodParameterBean(clazz, method, arguments);
    if (parameterBean != null) {
        // 注1
        violations.addAll(validator.validate(parameterBean, classgroups ));
    }
 
    for (Object arg : arguments) {
        // 注2
        validate(violations, arg, classgroups);
    }
 
    if (!violations.isEmpty()) {
        // 注3
        logger.error("Failed to validate service: " + clazz.getName() + ", method: " + methodName + ", cause: " + violations);
        throw new ConstraintViolationException("Failed to validate service: " + clazz.getName() + ", method: " + methodName + ", cause: " + violations, violations);
    }
}

```

從上述程式碼中可以看出當「注1」和注「2」兩處程式碼進行引數校驗時所得到的「違反約束」的資訊都被加入到violations集合中，而在「注3」處檢查到「違反約束」不為空時，就會丟擲包含「違反約束」資訊的ConstraintViolationException，該異常繼承自ValidationException，這樣也就會被ValidationFilter中方法所捕獲，進而向呼叫方返回相關異常資訊。

## 3.2 自定義引數校驗異常返回

從前一小節我們可以很清晰的瞭解到了為什麼會丟擲那樣的異常資訊給呼叫方，如果想做到我們前面想要的訴求：統一返回格式，我們需要按照下面的步驟去實現。

### 3.2.1 自定義Filter

```java
@Activate(group = {CONSUMER, PROVIDER}, value = "customValidationFilter", order = 10000)
public class CustomValidationFilter implements Filter {
 
    private Validation validation;
 
    public void setValidation(Validation validation) { this.validation = validation; }
 
    public Result invoke(Invoker> invoker, Invocation invocation) throws RpcException {
        if (validation != null && !invocation.getMethodName().startsWith("$")
                && ConfigUtils.isNotEmpty(invoker.getUrl().getMethodParameter(invocation.getMethodName(), VALIDATION_KEY))) {
            try {
                Validator validator = validation.getValidator(invoker.getUrl());
                if (validator != null) {
                    validator.validate(invocation.getMethodName(), invocation.getParameterTypes(), invocation.getArguments());
                }
            } catch (RpcException e) {
                throw e;
            } catch (ConstraintViolationException e) {// 這邊細化了異常型別
                // 注1
                Set<constraintviolation>> violations = e.getConstraintViolations();
                if (CollectionUtils.isNotEmpty(violations)) {
                    ConstraintViolation> violation = violations.iterator().next();// 取第一個進行提示就行了
                    FacadeResult facadeResult = FacadeResult.fail(ErrorCode.INVALID_PARAM.getCode(), violation.getMessage());
                    return AsyncRpcResult.newDefaultAsyncResult(facadeResult, invocation);
                }
                return AsyncRpcResult.newDefaultAsyncResult(new ValidationException(e.getMessage()), invocation);
            } catch (Throwable t) {
                return AsyncRpcResult.newDefaultAsyncResult(t, invocation);
            }
        }
        return invoker.invoke(invocation);
    }
}

```

該自定義filter與內建的ValidationFilter唯一不同的地方就在於「注1」處所新增的針對特定異常ConstraintViolationException的處理，從異常物件中獲取包含的「違反約束」資訊，並取其中第一個來構造業務上所定義的通用資料格式FacadeResult物件，作為Dubbo服務介面呼叫返回的資訊。

## 3.2.2 自定義Filter的配置

開發過Dubbo自定義filter的同學都知道，要讓它生效需要作一個符合SPI規範的配置，如下所示：

![](https://static001.geekbang.org/infoq/9f/9f57c555067d0138a562249858aa914b.png)

a. 新建兩級目錄分別是META-INF和dubbo，這個需要特別注意，不能直接新建一個目錄名為「META-INFO.dubbo」，否則在初始化啟動的時候會失敗。

b. 新建一個檔名為com.alibaba.dubbo.rpc.Filter，當然也可以是org.apache.dubbo.rpc.Filter，Dubbo開源到Apache社群後，預設支援這兩個名字。

c. 檔案中配置內容為：customValidationFilter=com.xxx.demo.dubbo.filter.CustomValidationFilter。

### 3.3.3 Dubbo服務配置

有了自定義引數校驗的Filter配置後，如果只做到這的話，其實還有一個問題，應用啟動後會有兩個引數校驗Filter生效。當然可以透過指定Filter的order來實現自定義Filter先執行，但很顯然這種方式不穩妥，而且兩個Filter的功能是重複的，因此只需要一個生效就可以了，Dubbo提供了一種機制可以禁用指定的Filter，只需在Dubbo配置檔案中作如下配置即可：

```java


<provider filter="-validation"></provider>

```

但經過上述配置後，發現customValidationFilter並沒有生效，經過除錯以及對dubbo相關文件的學習，對Filter生效機制有了一定的瞭解。

a. dubbo啟動後，預設會生效框架自帶的一系列Filter；

> 可以在dubbo框架的資原始檔org.apache.dubbo.rpc.Filter中看到具體有哪些，不同版本的內容可能會有些許差別。

```java
cache=org.apache.dubbo.cache.filter.CacheFilter
validation=org.apache.dubbo.validation.filter.ValidationFilter  // 注1
echo=org.apache.dubbo.rpc.filter.EchoFilter
generic=org.apache.dubbo.rpc.filter.GenericFilter
genericimpl=org.apache.dubbo.rpc.filter.GenericImplFilter
token=org.apache.dubbo.rpc.filter.TokenFilter
accesslog=org.apache.dubbo.rpc.filter.AccessLogFilter
activelimit=org.apache.dubbo.rpc.filter.ActiveLimitFilter
classloader=org.apache.dubbo.rpc.filter.ClassLoaderFilter
context=org.apache.dubbo.rpc.filter.ContextFilter
consumercontext=org.apache.dubbo.rpc.filter.ConsumerContextFilter
exception=org.apache.dubbo.rpc.filter.ExceptionFilter
executelimit=org.apache.dubbo.rpc.filter.ExecuteLimitFilter
deprecated=org.apache.dubbo.rpc.filter.DeprecatedFilter
compatible=org.apache.dubbo.rpc.filter.CompatibleFilter
timeout=org.apache.dubbo.rpc.filter.TimeoutFilter
tps=org.apache.dubbo.rpc.filter.TpsLimitFilter
trace=org.apache.dubbo.rpc.protocol.dubbo.filter.TraceFilter
future=org.apache.dubbo.rpc.protocol.dubbo.filter.FutureFilter
monitor=org.apache.dubbo.monitor.support.MonitorFilter
metrics=org.apache.dubbo.monitor.dubbo.MetricsFilter

```

如上「注1」中的Filter就是我們上一步配置中想要禁用的Filter，因為這些filter都是Dubbo內建的，所以這些filter集合有一個統一的名字，default，因此如果想全部禁用，除了一個一個禁用外，也可以直接用'-default'達到目的，這些預設內建的filter只要沒有全部或單獨禁用，那就會生效。

b. 想要開發的自定義Filter能生效，不併一定要在<provider filter="xxxFitler">中體現；如果我們沒有在Dubbo相關的配置檔案中去配置Filter相關資訊，只要寫好自定義filter程式碼，並在資原始檔/META-INF/dubbo/com.alibaba.dubbo.rpc.Filter中按照spi規範定義好即可，這樣所有被載入的Filter都會生效。

c. 如果在Dubbo配置檔案中配置了Filter資訊，那自定義Filter只有顯式配置才會生效。

d. Filter配置也可以加在dubbo service配置中（<service interface="..." ref="..." validation="true" filter="xFilter,yFilter"></service>）。

當dubbo配置檔案中provider 和service部分都配置了Filter資訊，針對service具體生效的Filter取兩者配置的並集。

因此想要自定義的校驗Filter在所有服務中都生效，需要作如下配置：

```java
<provider filter="-validation, customValidationFilter"></provider>

```

# 四、如何擴充套件校驗註解

前面示例中都是利用引數校驗的內建註解去完成，在實際開發中有時候會遇到預設內建的註解無法滿足校驗需求，這時就需要自定義一些校驗註解去滿足需求，方便開發。

假設有這樣一個場景，某引數值需要校驗只能在指定的幾個數值範圍內，類似於白名單一樣，下面就以這個場景來演示下如何擴充套件校驗註解。

## 4.1 定義校驗註解

```java
@Target({ METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER })
@Retention(RUNTIME)
@Documented
@Constraint(validatedBy = { })// 注1
// @Constraint(validatedBy = {AllowedValueValidator.class}) 注2
public @interface AllowedValue {
 
    String message() default "引數值不在合法範圍內";
 
    Class>[] groups() default { };
 
    Class extends Payload>[] payload() default { };
 
    long[] value() default {};
 
}

```

```java
public class AllowedValueValidator implements ConstraintValidator<allowedvalue long=""> {
 
    private long[] allowedValues;
 
    @Override
    public void initialize(AllowedValue constraintAnnotation) {
        this.allowedValues = constraintAnnotation.value();
    }
 
    @Override
    public boolean isValid(Long value, ConstraintValidatorContext context) {
        if (allowedValues.length == 0) {
            return true;
        }
        return Arrays.stream(allowedValues).anyMatch(o -> Objects.equals(o, value));
    }
}

```

「注1」中的校驗器(Validator)並沒有指定，當然是可以像「注2」中那樣直接指定校驗器，但考慮到自定義註解有可能是直接暴露在facade包中，而具體的校驗器的實現有時候會包含一些業務依賴，所以不建議直接在此處指定，而是透過Hibernate Validator提供的Validator發現機制去完成關聯。

## 4.2 配置定製Validator發現

![](https://static001.geekbang.org/infoq/05/0550472fd9a3e463856d69da2148c35e.png)

a. 在resources目錄下新建META-INF/services/javax.validation.ConstraintValidator檔案。

b. 檔案中只需填入相應Validator的全路徑：com.xxx.demo.validator.AllowedValueValidator，如果有多個的話，每行一個。

# 五、總結

本文主要介紹了使用Dubbo框架時如何使用優雅點方式完成引數的校驗，首先演示瞭如何利用Dubbo框架預設支援的校驗實現，然後接著演示瞭如何配合實際業務開發返回統一的資料格式，最後介紹了下如何進行自定義校驗註解的實現，方便進行後續自行擴充套件實現，希望能在實際工作中有一定的幫助。

> 作者：vivo官網商城開發團隊-Wei Fuping</allowedvalue></provider></constraintviolation></constraintviolation></class></t></boolean>

Dubbo服務如何優雅的校驗引數

相關文章