Apache Dubbo – RPC请求类特性

Java-Sdk: 分组聚合

Mon, 01 Jan 0001 00:00:00 +0000

通过分组对结果进行聚合并返回聚合后的结果，比如菜单服务，用group区分同一接口的多种实现，现在消费方需从每种group中调用一次并返回结果，对结果进行合并之后返回，这样就可以实现聚合菜单项。

配置

搜索所有分组

<dubbo:reference interface="com.xxx.MenuService" group="*" merger="true" />

合并指定分组

<dubbo:reference interface="com.xxx.MenuService" group="aaa,bbb" merger="true" />

指定方法合并结果，其它未指定的方法，将只调用一个 Group

<dubbo:reference interface="com.xxx.MenuService" group="*">
 <dubbo:method name="getMenuItems" merger="true" />
</dubbo:reference>

某个方法不合并结果，其它都合并结果

<dubbo:reference interface="com.xxx.MenuService" group="*" merger="true">
 <dubbo:method name="getMenuItems" merger="false" />
</dubbo:reference>

指定合并策略，缺省根据返回值类型自动匹配，如果同一类型有两个合并器时，需指定合并器的名称

提示

参见：合并结果扩展

<dubbo:reference interface="com.xxx.MenuService" group="*">
 <dubbo:method name="getMenuItems" merger="mymerge" />
</dubbo:reference>

指定合并方法，将调用返回结果的指定方法进行合并，合并方法的参数类型必须是返回结果类型本身

<dubbo:reference interface="com.xxx.MenuService" group="*">
 <dubbo:method name="getMenuItems" merger=".addAll" />
</dubbo:reference>

提示

从 2.1.0 版本开始支持

Java-Sdk: 参数校验

Mon, 01 Jan 0001 00:00:00 +0000

参数验证功能是基于 JSR303 实现的，用户只需标识 JSR303 标准的验证 annotation，并通过声明 filter 来实现验证。

Maven 依赖

<dependency>
 <groupId>javax.validation</groupId>
 <artifactId>validation-api</artifactId>
 <version>1.0.0.GA</version>
</dependency>
<dependency>
 <groupId>org.hibernate</groupId>
 <artifactId>hibernate-validator</artifactId>
 <version>4.2.0.Final</version>
</dependency>

示例

参数标注示例

import java.io.Serializable;
import java.util.Date;

import javax.validation.constraints.Future;
import javax.validation.constraints.Max;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Past;
import javax.validation.constraints.Pattern;
import javax.validation.constraints.Size;

public class ValidationParameter implements Serializable {
 private static final long serialVersionUID = 7158911668568000392L;

 @NotNull // 不允许为空
 @Size(min = 1, max = 20) // 长度或大小范围
 private String name;

 @NotNull(groups = ValidationService.Save.class) // 保存时不允许为空，更新时允许为空 ，表示不更新该字段
 @Pattern(regexp = "^\\s*\\w+(?:\\.{0,1}[\\w-]+)*@[a-zA-Z0-9]+(?:[-.][a-zA-Z0-9]+)*\\.[a-zA-Z]+\\s*$")
 private String email;

 @Min(18) // 最小值
 @Max(100) // 最大值
 private int age;

 @Past // 必须为一个过去的时间
 private Date loginDate;

 @Future // 必须为一个未来的时间
 private Date expiryDate;

 public String getName() {
 return name;
 }

 public void setName(String name) {
 this.name = name;
 }

 public String getEmail() {
 return email;
 }

 public void setEmail(String email) {
 this.email = email;
 }

 public int getAge() {
 return age;
 }

 public void setAge(int age) {
 this.age = age;
 }

 public Date getLoginDate() {
 return loginDate;
 }

 public void setLoginDate(Date loginDate) {
 this.loginDate = loginDate;
 }

 public Date getExpiryDate() {
 return expiryDate;
 }

 public void setExpiryDate(Date expiryDate) {
 this.expiryDate = expiryDate;
 }
}

分组验证示例

public interface ValidationService { // 缺省可按服务接口区分验证场景，如：@NotNull(groups = ValidationService.class)
 @interface Save{} // 与方法同名接口，首字母大写，用于区分验证场景，如：@NotNull(groups = ValidationService.Save.class)，可选
 void save(ValidationParameter parameter);
 void update(ValidationParameter parameter);
}

关联验证示例

import javax.validation.GroupSequence;

public interface ValidationService {
 @GroupSequence(Update.class) // 同时验证Update组规则
 @interface Save{}
 void save(ValidationParameter parameter);

 @interface Update{}
 void update(ValidationParameter parameter);
}

参数验证示例

import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;

public interface ValidationService {
 void save(@NotNull ValidationParameter parameter); // 验证参数不为空
 void delete(@Min(1) int id); // 直接对基本类型参数验证
}

配置

在客户端验证参数

<dubbo:reference id="validationService" interface="org.apache.dubbo.examples.validation.api.ValidationService" validation="true" />

在服务器端验证参数

<dubbo:service interface="org.apache.dubbo.examples.validation.api.ValidationService" ref="validationService" validation="true" />

提示

Dubbo 默认支持 hibernate-validator 版本 <=6.x，若使用 hibernate-validator 7.x 版本，请将 validation 参数声明为 jvalidatorNew

验证异常信息

import javax.validation.ConstraintViolationException;
import javax.validation.ConstraintViolationException;

import org.springframework.context.support.ClassPathXmlApplicationContext;

import org.apache.dubbo.examples.validation.api.ValidationParameter;
import org.apache.dubbo.examples.validation.api.ValidationService;
import org.apache.dubbo.rpc.RpcException;

public class ValidationConsumer {
 public static void main(String[] args) throws Exception {
 String config = ValidationConsumer.class.getPackage().getName().replace('.', '/') + "/validation-consumer.xml";
 ClassPathXmlApplicationContext context = new ClassPathXmlApplicationContext(config);
 context.start();
 ValidationService validationService = (ValidationService)context.getBean("validationService");
 // Error
 try {
 parameter = new ValidationParameter();
 validationService.save(parameter);
 System.out.println("Validation ERROR");
 } catch (RpcException e) { // 抛出的是RpcException
 ConstraintViolationException ve = (ConstraintViolationException) e.getCause(); // 里面嵌了一个ConstraintViolationException
 Set<ConstraintViolation<?>> violations = ve.getConstraintViolations(); // 可以拿到一个验证错误详细信息的集合
 System.out.println(violations);
 }
 }
}

提示

自 2.1.0 版本开始支持, 如何使用可以参考 dubbo 项目中的示例代码

验证方式可扩展，扩展方式参见开发者手册中的验证扩展

Java-Sdk: 异步调用

Mon, 01 Jan 0001 00:00:00 +0000

从 2.7.0 开始，Dubbo 的所有异步编程接口开始以 CompletableFuture 为基础

基于 NIO 的非阻塞实现并行调用，客户端不需要启动多线程即可完成并行调用多个远程服务，相对多线程开销较小。

使用 CompletableFuture 签名的接口

需要服务提供者事先定义 CompletableFuture 签名的服务，接口定义指南如下：

Provider端异步执行将阻塞的业务从Dubbo内部线程池切换到业务自定义线程，避免Dubbo线程池的过度占用，有助于避免不同服务间的互相影响。异步执行无异于节省资源或提升RPC响应性能，因为如果业务执行需要阻塞，则始终还是要有线程来负责执行。

注意

Provider 端异步执行和 Consumer 端异步调用是相互独立的，你可以任意正交组合两端配置

Consumer同步 - Provider同步
Consumer异步 - Provider同步
Consumer同步 - Provider异步
Consumer异步 - Provider异步

定义 CompletableFuture 签名的接口

服务接口定义：

public interface AsyncService {
 CompletableFuture<String> sayHello(String name);
}

服务实现：

public class AsyncServiceImpl implements AsyncService {
 @Override
 public CompletableFuture<String> sayHello(String name) {
 RpcContext savedContext = RpcContext.getContext();
 // 建议为supplyAsync提供自定义线程池，避免使用JDK公用线程池
 return CompletableFuture.supplyAsync(() -> {
 System.out.println(savedContext.getAttachment("consumer-key1"));
 try {
 Thread.sleep(5000);
 } catch (InterruptedException e) {
 e.printStackTrace();
 }
 return "async response from provider.";
 });
 }
}

通过 return CompletableFuture.supplyAsync() ，业务执行已从 Dubbo 线程切换到业务线程，避免了对 Dubbo 线程池的阻塞。

使用AsyncContext

Dubbo 提供了一个类似 Servlet 3.0 的异步接口AsyncContext，在没有 CompletableFuture 签名接口的情况下，也可以实现 Provider 端的异步执行。

服务接口定义：

public interface AsyncService {
 String sayHello(String name);
}

服务暴露，和普通服务完全一致：

<bean id="asyncService" class="org.apache.dubbo.samples.governance.impl.AsyncServiceImpl"/>
<dubbo:service interface="org.apache.dubbo.samples.governance.api.AsyncService" ref="asyncService"/>

服务实现：

public class AsyncServiceImpl implements AsyncService {
 public String sayHello(String name) {
 final AsyncContext asyncContext = RpcContext.startAsync();
 new Thread(() -> {
 // 如果要使用上下文，则必须要放在第一句执行
 asyncContext.signalContextSwitch();
 try {
 Thread.sleep(500);
 } catch (InterruptedException e) {
 e.printStackTrace();
 }
 // 写回响应
 asyncContext.write("Hello " + name + ", response from provider.");
 }).start();
 return null;
 }
}

注意接口的返回类型是 CompletableFuture<String>。

XML引用服务：

<dubbo:reference id="asyncService" timeout="10000" interface="com.alibaba.dubbo.samples.async.api.AsyncService"/>

调用远程服务：

// 调用直接返回CompletableFuture
CompletableFuture<String> future = asyncService.sayHello("async call request");
// 增加回调
future.whenComplete((v, t) -> {
 if (t != null) {
 t.printStackTrace();
 } else {
 System.out.println("Response: " + v);
 }
});
// 早于结果输出
System.out.println("Executed before response return.");

使用 RpcContext

在 consumer.xml 中配置：

<dubbo:reference id="asyncService" interface="org.apache.dubbo.samples.governance.api.AsyncService">
 <dubbo:method name="sayHello" async="true" />
</dubbo:reference>

调用代码:

// 此调用会立即返回null
asyncService.sayHello("world");
// 拿到调用的Future引用，当结果返回后，会被通知和设置到此Future
CompletableFuture<String> helloFuture = RpcContext.getContext().getCompletableFuture();
// 为Future添加回调
helloFuture.whenComplete((retValue, exception) -> {
 if (exception == null) {
 System.out.println(retValue);
 } else {
 exception.printStackTrace();
 }
});

或者，你也可以这样做异步调用:

CompletableFuture<String> future = RpcContext.getContext().asyncCall(
 () -> {
 asyncService.sayHello("oneway call request1");
 }
);

future.get();

重载服务接口

如果你只有这样的同步服务定义，而又不喜欢 RpcContext 的异步使用方式。

public interface GreetingsService {
 String sayHi(String name);
}

那还有一种方式，就是利用 Java 8 提供的 default 接口实现，重载一个带有 CompletableFuture 签名的方法。

CompletableFuture 签名的方法目前只支持 Dubbo 协议，其他协议由于第三方实现问题，需要视具体情况而定。

有两种方式来实现：

提供方或消费方自己修改接口签名

public interface GreetingsService {
 String sayHi(String name);

 // AsyncSignal is totally optional, you can use any parameter type as long as java allows your to do that.
 default CompletableFuture<String> sayHi(String name, AsyncSignal signal) {
 return CompletableFuture.completedFuture(sayHi(name));
 }
}

Dubbo 官方提供 compiler hacker，编译期自动重写同步方法，请在此讨论和跟进具体进展。

你也可以设置是否等待消息发出： ¹

sent="true" 等待消息发出，消息发送失败将抛出异常。
sent="false" 不等待消息发出，将消息放入 IO 队列，即刻返回。

<dubbo:method name="findFoo" async="true" sent="true" />

如果你只是想异步，完全忽略返回值，可以配置 return="false"，以减少 Future 对象的创建和管理成本：

<dubbo:method name="findFoo" async="true" return="false" />

异步总是不等待返回 ↩︎

Java-Sdk: 泛化调用

Mon, 01 Jan 0001 00:00:00 +0000

实现泛化服务暴露

泛接口实现方式主要用于服务器端没有 API 接口及模型类元的情况，参数及返回值中的所有 POJO 均用 Map 表示，通常用于框架集成，比如：实现一个通用的远程服务 Mock 框架，可通过实现 GenericService 接口处理所有服务请求。

在 Java 代码中实现 GenericService 接口：

package com.foo;
public class MyGenericService implements GenericService {

 public Object $invoke(String methodName, String[] parameterTypes, Object[] args) throws GenericException {
 if ("sayHello".equals(methodName)) {
 return "Welcome " + args[0];
 }
 }
}

通过 Spring 暴露泛化实现

在 Spring 配置申明服务的实现：

<bean id="genericService" class="com.foo.MyGenericService" />
<dubbo:service interface="com.foo.BarService" ref="genericService" />

通过 API 方式暴露泛化实现

...
// 用org.apache.dubbo.rpc.service.GenericService可以替代所有接口实现
GenericService xxxService = new XxxGenericService();

// 该实例很重量，里面封装了所有与注册中心及服务提供方连接，请缓存
ServiceConfig<GenericService> service = new ServiceConfig<GenericService>();
// 弱类型接口名
service.setInterface("com.xxx.XxxService");
service.setVersion("1.0.0");
// 指向一个通用服务实现
service.setRef(xxxService);

// 暴露及注册服务
service.export();

实现泛化服务调用

泛化接口调用方式主要用于客户端没有 API 接口及模型类元的情况，参数及返回值中的所有 POJO 均用 Map 表示，通常用于框架集成，比如：实现一个通用的服务测试框架，可通过 GenericService 调用所有服务实现。

通过 Spring 使用泛化调用

在 Spring 配置申明 generic="true"：

<dubbo:reference id="barService" interface="com.foo.BarService" generic="true" />

在 Java 代码获取 barService 并开始泛化调用：

GenericService barService = (GenericService) applicationContext.getBean("barService");
Object result = barService.$invoke("sayHello", new String[] { "java.lang.String" }, new Object[] { "World" });

通过 API 方式使用泛化调用

import org.apache.dubbo.rpc.service.GenericService;
...

// 引用远程服务
// 该实例很重量，里面封装了所有与注册中心及服务提供方连接，请缓存
ReferenceConfig<GenericService> reference = new ReferenceConfig<GenericService>();
// 弱类型接口名
reference.setInterface("com.xxx.XxxService");
reference.setVersion("1.0.0");
// 声明为泛化接口
reference.setGeneric(true);

// 用org.apache.dubbo.rpc.service.GenericService可以替代所有接口引用
GenericService genericService = reference.get();

// 基本类型以及Date,List,Map等不需要转换，直接调用
Object result = genericService.$invoke("sayHello", new String[] {"java.lang.String"}, new Object[] {"world"});

// 用Map表示POJO参数，如果返回值为POJO也将自动转成Map
Map<String, Object> person = new HashMap<String, Object>();
person.put("name", "xxx");
person.put("password", "yyy");
// 如果返回POJO将自动转成Map
Object result = genericService.$invoke("findPerson", new String[]
{"com.xxx.Person"}, new Object[]{person});

...

有关泛化类型的进一步解释

假设存在 POJO 如：

package com.xxx;

public class PersonImpl implements Person {
 private String name;
 private String password;

 public String getName() {
 return name;
 }

 public void setName(String name) {
 this.name = name;
 }

 public String getPassword() {
 return password;
 }

 public void setPassword(String password) {
 this.password = password;
 }
}

则 POJO 数据：

Person person = new PersonImpl();
person.setName("xxx");
person.setPassword("yyy");

可用下面 Map 表示：

Map<String, Object> map = new HashMap<String, Object>();
// 注意：如果参数类型是接口，或者List等丢失泛型，可通过class属性指定类型。
map.put("class", "com.xxx.PersonImpl");
map.put("name", "xxx");
map.put("password", "yyy");

Java-Sdk: 调用链路传递隐式参数

Mon, 01 Jan 0001 00:00:00 +0000

可以通过 RpcContext 上的 setAttachment 和 getAttachment 在服务消费方和提供方之间进行参数的隐式传递。

注意

path, group, version, dubbo, token, timeout 几个 key 是保留字段，请使用其它值。

在服务消费方端设置隐式参数

setAttachment 设置的 KV 对，在完成下面一次远程调用会被清空，即多次远程调用要多次设置。

RpcContext.getContext().setAttachment("index", "1"); // 隐式传参，后面的远程调用都会隐式将这些参数发送到服务器端，类似cookie，用于框架集成，不建议常规业务使用
xxxService.xxx(); // 远程调用
// ...

在服务提供方端获取隐式参数

public class XxxServiceImpl implements XxxService {

 public void xxx() {
 // 获取客户端隐式传入的参数，用于框架集成，不建议常规业务使用
 String index = RpcContext.getContext().getAttachment("index");
 }
}

Java-Sdk: RPC调用上下文

Mon, 01 Jan 0001 00:00:00 +0000

上下文中存放的是当前调用过程中所需的环境信息。所有配置信息都将转换为 URL 的参数，参见 schema 配置参考手册中的对应URL参数一列。

RpcContext 是一个 ThreadLocal 的临时状态记录器，当接收到 RPC 请求，或发起 RPC 请求时，RpcContext 的状态都会变化。比如：A 调 B，B 再调 C，则 B 机器上，在 B 调 C 之前，RpcContext 记录的是 A 调 B 的信息，在 B 调 C 之后，RpcContext 记录的是 B 调 C 的信息。

服务消费方

// 远程调用
xxxService.xxx();
// 本端是否为消费端，这里会返回true
boolean isConsumerSide = RpcContext.getContext().isConsumerSide();
// 获取最后一次调用的提供方IP地址
String serverIP = RpcContext.getContext().getRemoteHost();
// 获取当前服务配置信息，所有配置信息都将转换为URL的参数
String application = RpcContext.getContext().getUrl().getParameter("application");
// 注意：每发起RPC调用，上下文状态会变化
yyyService.yyy();

服务提供方

public class XxxServiceImpl implements XxxService {

 public void xxx() {
 // 本端是否为提供端，这里会返回true
 boolean isProviderSide = RpcContext.getContext().isProviderSide();
 // 获取调用方IP地址
 String clientIP = RpcContext.getContext().getRemoteHost();
 // 获取当前服务配置信息，所有配置信息都将转换为URL的参数
 String application = RpcContext.getContext().getUrl().getParameter("application");
 // 注意：每发起RPC调用，上下文状态会变化
 yyyService.yyy();
 // 此时本端变成消费端，这里会返回false
 boolean isProviderSide = RpcContext.getContext().isProviderSide();
 }
}

Java-Sdk: 调用结果缓存

Mon, 01 Jan 0001 00:00:00 +0000

结果缓存，用于加速热门数据的访问速度，Dubbo 提供声明式缓存，以减少用户加缓存的工作量。

缓存类型

lru 基于最近最少使用原则删除多余缓存，保持最热的数据被缓存。
threadlocal 当前线程缓存，比如一个页面渲染，用到很多 portal，每个 portal 都要去查用户信息，通过线程缓存，可以减少这种多余访问。
jcache 与 JSR107 集成，可以桥接各种缓存实现。

缓存类型可扩展，参见：缓存扩展

配置

<dubbo:reference interface="com.foo.BarService" cache="lru" />

或：

<dubbo:reference interface="com.foo.BarService">
 <dubbo:method name="findBar" cache="lru" />
</dubbo:reference>

提示

2.1.0 以上版本支持。

示例代码

Java-Sdk: 调用触发事件通知

Mon, 01 Jan 0001 00:00:00 +0000

在调用之前、调用之后、出现异常时，会触发 oninvoke、onreturn、onthrow 三个事件，可以配置当事件发生时，通知哪个类的哪个方法。

提示

支持版本：2.0.7 之后

服务提供者与消费者共享服务接口

interface IDemoService {
 public Person get(int id);
}

服务提供者实现

class NormalDemoService implements IDemoService {
 public Person get(int id) {
 return new Person(id, "charles`son", 4);
 }
}

服务提供者配置

<dubbo:application name="rpc-callback-demo" />
<dubbo:registry address="zookeeper://127.0.0.1:2181"/>
<bean id="demoService" class="org.apache.dubbo.callback.implicit.NormalDemoService" />
<dubbo:service interface="org.apache.dubbo.callback.implicit.IDemoService" ref="demoService" version="1.0.0" group="cn"/>

服务消费者 Callback 接口

interface Notify {
 public void onreturn(Person msg, Integer id);
 public void onthrow(Throwable ex, Integer id);
}

服务消费者 Callback 实现

class NotifyImpl implements Notify {
 public Map<Integer, Person> ret = new HashMap<Integer, Person>();
 public Map<Integer, Throwable> errors = new HashMap<Integer, Throwable>();

 public void onreturn(Person msg, Integer id) {
 System.out.println("onreturn:" + msg);
 ret.put(id, msg);
 }

 public void onthrow(Throwable ex, Integer id) {
 errors.put(id, ex);
 }
}

服务消费者 Callback 配置

<bean id ="demoCallback" class = "org.apache.dubbo.callback.implicit.NotifyImpl" />
<dubbo:reference id="demoService" interface="org.apache.dubbo.callback.implicit.IDemoService" version="1.0.0" group="cn" >
 <dubbo:method name="get" async="true" onreturn = "demoCallback.onreturn" onthrow="demoCallback.onthrow" />
</dubbo:reference>

callback 与 async 功能正交分解，async=true 表示结果是否马上返回，onreturn 表示是否需要回调。

两者叠加存在以下几种组合情况：

异步回调模式：async=true onreturn="xxx"
同步回调模式：async=false onreturn="xxx"
异步无回调：async=true
同步无回调：async=false

提示

async=false 默认

测试代码

IDemoService demoService = (IDemoService) context.getBean("demoService");
NotifyImpl notify = (NotifyImpl) context.getBean("demoCallback");
int requestId = 2;
Person ret = demoService.get(requestId);
Assert.assertEquals(null, ret);
//for Test：只是用来说明callback正常被调用，业务具体实现自行决定.
for (int i = 0; i < 10; i++) {
 if (!notify.ret.containsKey(requestId)) {
 Thread.sleep(200);
 } else {
 break;
 }
}
Assert.assertEquals(requestId, notify.ret.get(requestId).getId());

Java-Sdk: 服务端对客户端进行回调

Mon, 01 Jan 0001 00:00:00 +0000

参数回调方式与调用本地 callback 或 listener 相同，只需要在 Spring 的配置文件中声明哪个参数是 callback 类型即可。Dubbo 将基于长连接生成反向代理，这样就可以从服务器端调用客户端逻辑。可以参考 dubbo 项目中的示例代码。

服务接口示例

CallbackService.java

package com.callback;

public interface CallbackService {
 void addListener(String key, CallbackListener listener);
}

CallbackListener.java

package com.callback;

public interface CallbackListener {
 void changed(String msg);
}

服务提供者接口实现示例

package com.callback.impl;

import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

import com.callback.CallbackListener;
import com.callback.CallbackService;

public class CallbackServiceImpl implements CallbackService {

 private final Map<String, CallbackListener> listeners = new ConcurrentHashMap<String, CallbackListener>();

 public CallbackServiceImpl() {
 Thread t = new Thread(new Runnable() {
 public void run() {
 while(true) {
 try {
 for(Map.Entry<String, CallbackListener> entry : listeners.entrySet()){
 try {
 entry.getValue().changed(getChanged(entry.getKey()));
 } catch (Throwable t) {
 listeners.remove(entry.getKey());
 }
 }
 Thread.sleep(5000); // 定时触发变更通知
 } catch (Throwable t) { // 防御容错
 t.printStackTrace();
 }
 }
 }
 });
 t.setDaemon(true);
 t.start();
 }

 public void addListener(String key, CallbackListener listener) {
 listeners.put(key, listener);
 listener.changed(getChanged(key)); // 发送变更通知
 }

 private String getChanged(String key) {
 return "Changed: " + new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date());
 }
}

服务提供者配置示例

<bean id="callbackService" class="com.callback.impl.CallbackServiceImpl" />
<dubbo:service interface="com.callback.CallbackService" ref="callbackService" connections="1" callbacks="1000">
 <dubbo:method name="addListener">
 <dubbo:argument index="1" callback="true" />
 <!--也可以通过指定类型的方式-->
 <!--<dubbo:argument type="com.demo.CallbackListener" callback="true" />-->
 </dubbo:method>
</dubbo:service>

服务消费者配置示例

<dubbo:reference id="callbackService" interface="com.callback.CallbackService" />

服务消费者调用示例

ClassPathXmlApplicationContext context = new ClassPathXmlApplicationContext("classpath:consumer.xml");
context.start();

CallbackService callbackService = (CallbackService) context.getBean("callbackService");

callbackService.addListener("foo.bar", new CallbackListener(){
 public void changed(String msg) {
 System.out.println("callback1:" + msg);
 }
});

提示

2.0.6 及其以上版本支持

Java-Sdk: 本地伪装

Mon, 01 Jan 0001 00:00:00 +0000

本地伪装 ¹ 通常用于服务降级，比如某验权服务，当服务提供方全部挂掉后，客户端不抛出异常，而是通过 Mock 数据返回授权失败。

在 spring 配置文件中按以下方式配置：

<dubbo:reference interface="com.foo.BarService" mock="true" />

或

<dubbo:reference interface="com.foo.BarService" mock="com.foo.BarServiceMock" />

在工程中提供 Mock 实现 ²：

package com.foo;
public class BarServiceMock implements BarService {
 public String sayHello(String name) {
 // 你可以伪造容错数据，此方法只在出现RpcException时被执行
 return "容错数据";
 }
}

如果服务的消费方经常需要 try-catch 捕获异常，如：

Offer offer = null;
try {
 offer = offerService.findOffer(offerId);
} catch (RpcException e) {
 logger.error(e);
}

请考虑改为 Mock 实现，并在 Mock 实现中 return null。如果只是想简单的忽略异常，在 2.0.11 以上版本可用：

<dubbo:reference interface="com.foo.BarService" mock="return null" />

进阶用法

return

使用 return 来返回一个字符串表示的对象，作为 Mock 的返回值。合法的字符串可以是：

empty: 代表空，基本类型的默认值，或者集合类的空值
null: null
true: true
false: false
JSON 格式: 反序列化 JSON 所得到的对象

throw

使用 throw 来返回一个 Exception 对象，作为 Mock 的返回值。

当调用出错时，抛出一个默认的 RPCException:

<dubbo:reference interface="com.foo.BarService" mock="throw" />

当调用出错时，抛出指定的 Exception：

<dubbo:reference interface="com.foo.BarService" mock="throw com.foo.MockException" />

force 和 fail

在 2.6.6 以上的版本，可以开始在 Spring XML 配置文件中使用 fail: 和 force:。force: 代表强制使用 Mock 行为，在这种情况下不会走远程调用。fail: 与默认行为一致，只有当远程调用发生错误时才使用 Mock 行为。force: 和 fail: 都支持与 throw 或者 return 组合使用。

强制返回指定值：

<dubbo:reference interface="com.foo.BarService" mock="force:return fake" />

强制抛出指定异常：

<dubbo:reference interface="com.foo.BarService" mock="force:throw com.foo.MockException" />

在方法级别配置 Mock

Mock 可以在方法级别上指定，假定 com.foo.BarService 上有好几个方法，我们可以单独为 sayHello() 方法指定 Mock 行为。具体配置如下所示，在本例中，只要 sayHello() 被调用到时，强制返回 “fake”:

<dubbo:reference id="demoService" check="false" interface="com.foo.BarService">
 <dubbo:parameter key="sayHello.mock" value="force:return fake"/>
</dubbo:reference>

Mock 是 Stub 的一个子集，便于服务提供方在客户端执行容错逻辑，因经常需要在出现 RpcException (比如网络失败，超时等)时进行容错，而在出现业务异常(比如登录用户名密码错误)时不需要容错，如果用 Stub，可能就需要捕获并依赖 RpcException 类，而用 Mock 就可以不依赖 RpcException，因为它的约定就是只有出现 RpcException 时才执行。 ↩︎
在 interface 旁放一个 Mock 实现，它实现 BarService 接口，并有一个无参构造函数 ↩︎

Java-Sdk: 本地存根

Mon, 01 Jan 0001 00:00:00 +0000

远程服务后，客户端通常只剩下接口，而实现全在服务器端，但提供方有些时候想在客户端也执行部分逻辑，比如：做 ThreadLocal 缓存，提前验证参数，调用失败后伪造容错数据等等，此时就需要在 API 中带上 Stub，客户端生成 Proxy 实例，会把 Proxy 通过构造函数传给 Stub ¹，然后把 Stub 暴露给用户，Stub 可以决定要不要去调 Proxy。

在 spring 配置文件中按以下方式配置：

<dubbo:consumer interface="com.foo.BarService" stub="true" />

或

<dubbo:consumer interface="com.foo.BarService" stub="com.foo.BarServiceStub" />

提供 Stub 的实现 ²：

package com.foo;
public class BarServiceStub implements BarService {
 private final BarService barService;

 // 构造函数传入真正的远程代理对象
 public BarServiceStub(BarService barService){
 this.barService = barService;
 }

 public String sayHello(String name) {
 // 此代码在客户端执行, 你可以在客户端做ThreadLocal本地缓存，或预先验证参数是否合法，等等
 try {
 return barService.sayHello(name);
 } catch (Exception e) {
 // 你可以容错，可以做任何AOP拦截事项
 return "容错数据";
 }
 }
}

Stub 必须有可传入 Proxy 的构造函数。 ↩︎
在 interface 旁边放一个 Stub 实现，它实现 BarService 接口，并有一个传入远程 BarService 实例的构造函数 ↩︎

Java-Sdk: 回声测试

Mon, 01 Jan 0001 00:00:00 +0000

回声测试用于检测服务是否可用，回声测试按照正常请求流程执行，能够测试整个调用是否通畅，可用于监控。

所有服务自动实现 EchoService 接口，只需将任意服务引用强制转型为 EchoService，即可使用。

Spring 配置：

<dubbo:reference id="memberService" interface="com.xxx.MemberService" />

代码：

// 远程服务引用
MemberService memberService = ctx.getBean("memberService");

EchoService echoService = (EchoService) memberService; // 强制转型为EchoService

// 回声测试可用性
String status = echoService.$echo("OK");

assert(status.equals("OK"));

Java-Sdk: 调用信息记录

Mon, 01 Jan 0001 00:00:00 +0000

如果你想记录每一次请求信息，可开启访问日志，类似于apache的访问日志。注意：此日志量比较大，请注意磁盘容量。

将访问日志输出到当前应用的log4j日志：

<dubbo:protocol accesslog="true" />

将访问日志输出到指定文件：

<dubbo:protocol accesslog="http://10.20.160.198/wiki/display/dubbo/foo/bar.log" />