自定义扩展 on Apache Dubbo

自定义 SPI 扩展的基本步骤

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

下面以 RPC 协议插件 为例，说明如何利用 Dubbo 提供的 SPI 插件提供一个自定义的 RPC 协议实现。如果想了解 SPI 机制的工作原理以及框架内置的 SPI 扩展点列表，请查看参考手册 - SPI扩展。

1. 提供 SPI 插件实现类

提供一个 Java 类实现 org.apache.dubbo.rpc.Protocol 接口。

package com.spi.demo;
import org.apache.dubbo.rpc.Protocol;

@Activate
public class CustomizedProtocol implements Protocol {
	// ...
}

2. 在指定文件配置实现类

在应用 resources/META-INF/services/ 目录下添加 org.apache.dubbo.rpc.Protocol 文件，文件中增加如下配置：

customized=com.spi.demo.CustomizedProtocol

配置注意事项

文件名必须为 SPI 插件定义的 package 全路径名，具体取决于你要扩展的 SPI 定义，如示例中的 resources/META-INF/services/org.apache.dubbo.rpc.Protocol。
文件中的内容必须是 key=value 形式，其中 key 可随便定义，但建议增加特定前缀以避免与 Dubbo 内置实现重名，value 必须设置为扩展类实现的全路径名。

3. 通过配置启用自定义协议实现

在应用中修改协议配置，告诉 Dubbo 框架使用自定义协议：

# 使用 Spring Boot，可修改 application.yml 或 application.properties
dubbo
 protocol
 name: customized

或者

Filter

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

在 RPC框架 - Filter请求拦截一节中，我们了解了 Filter 的工作机制，以及 Dubbo 框架提供的一些内置 Filter 实现。在本文中，我们来了解如何扩展自定义的过滤器实现：一个可以对返回的结果进行统一的处理、验证等统一 Filter 处理器，减少对开发人员的打扰。

本示例的完整源码请参见 dubbo-samples-extensibility。除了本示例之外，Dubbo 核心仓库 apache/dubbo 以及扩展库 apache/dubbo-spi-extensions 中的众多 Filter 实现，都可以作为扩展参考实现。

任务详情

对所有调用Provider服务的请求在返回的结果的后面统一添加's customized AppendedFilter。

实现方式

在Provider中自定义一个Filter，在Filter中修改返回结果。

代码结构

src
 |-main
 |-java
 |-org
 |-apache
 |-dubbo
 |-samples
 |-extensibility
 |-filter
 |-provider
 |-AppendedFilter.java (实现Filter接口)
 |-resources
 |-META-INF
 |-application.properties (Dubbo Provider配置文件)
 |-dubbo
 |-org.apache.dubbo.rpc.Filter (纯文本文件)

代码详情

package org.apache.dubbo.samples.extensibility.filter.provider;

import org.apache.dubbo.rpc.Filter;
import org.apache.dubbo.rpc.Result;
import org.apache.dubbo.rpc.Invoker;
import org.apache.dubbo.rpc.Invocation;
import org.apache.dubbo.rpc.RpcException;
import org.apache.dubbo.rpc.AsyncRpcResult;

public class AppendedFilter implements Filter {

 @Override
 public Result invoke(Invoker<?> invoker, Invocation invocation) throws RpcException {
 Result result= invoker.invoke(invocation);
 // Obtain the returned value
 Result appResponse = ((AsyncRpcResult) result).getAppResponse();
 // Appended value
 appResponse.setValue(appResponse.getValue()+"'s customized AppendedFilter");
 return result;
 }
}

SPI配置

在resources/META-INF/dubbo/org.apache.dubbo.rpc.Filter文件中添加如下配置：

Protocol

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

在通信协议一章中，我们了解了 Dubbo 内置的几个核心 RPC 协议 dubbo、rest、和tri 以及它们的使用方式。本文讲解如何通过扩展 org.apache.dubbo.rpc.Protocol SPI，提供自定义的 RPC 协议实现。

自定义一套私有协议有两种方式，第一种是对原有的协议进行包装，添加一些特定的业务逻辑。另外一种是完全自定义一套协议。前者实现简单，在dubbo中也是有广泛的使用，比如：ProtocolFilterWrapper, QosProtocolWrapper, ProtocolListenerWrapper等。后者实现相对复杂，但却具有最大的灵活性，比如 Dubbo 框架内置的协议 dubbo、triple 协议都可以算作这种实现方式。

本示例的完整源码请参见 dubbo-samples-extensibility。除了本示例之外，Dubbo 核心仓库 apache/dubbo 以及扩展库 apache/dubbo-spi-extensions 中的众多 Protocol 实现，都可以作为扩展参考实现：

# Dubbo对外支持的常用协议
dubbo=org.apache.dubbo.rpc.protocol.dubbo.DubboProtocol
tri=org.apache.dubbo.rpc.protocol.tri.TripleProtocol

任务详情

基于现有的dubbo协议来实现自定义协议edubbo。

实现方式

通过对dubbo协议进行包装来实现edubbo协议。

代码结构

Common

src
 |-main
 |-java
 |-org
 |-apache
 |-dubbo
 |-samples
 |-extensibility
 |-protocol
 |-common
 |-EnhancedProtocol.java (实现Protocol接口)

Provider

src
 |-main
 |-java
 |-org
 |-apache
 |-dubbo
 |-samples
 |-extensibility
 |-protocol
 |-provider
 |-ExtensibilityProtocolProviderApplication.java
 |-ExtensibilityProtocolServiceImpl.java
 |-resources
 |-META-INF
 |-application.properties (Dubbo Provider配置文件)
 |-dubbo
 |-org.apache.dubbo.rpc.Protocol (纯文本文件)

Consumer

src
 |-main
 |-java
 |-org
 |-apache
 |-dubbo
 |-samples
 |-extensibility
 |-protocol
 |-consumer
 |-ExtensibilityProtocolConsumerApplication.java
 |-ExtensibilityProtocolConsumerTask.java
 |-resources
 |-META-INF
 |-application.properties (Dubbo Consumer配置文件)
 |-dubbo
 |-org.apache.dubbo.rpc.Protocol (纯文本文件)

代码详情

package org.apache.dubbo.samples.extensibility.protocol.common;

import org.apache.dubbo.common.URL;
import org.apache.dubbo.rpc.Protocol;
import org.apache.dubbo.rpc.Invoker;
import org.apache.dubbo.rpc.Exporter;
import org.apache.dubbo.rpc.ProtocolServer;
import org.apache.dubbo.rpc.RpcException;
import org.apache.dubbo.rpc.model.FrameworkModel;
import org.apache.dubbo.rpc.protocol.dubbo.DubboProtocol;

import java.util.List;

public class EnhancedProtocol implements Protocol {

 public EnhancedProtocol(FrameworkModel frameworkModel) {
 this.protocol = new DubboProtocol(frameworkModel);
 }

 private final Protocol protocol;

 @Override
 public int getDefaultPort() {
 return this.protocol.getDefaultPort();
 }

 @Override
 public <T> Exporter<T> export(Invoker<T> invoker) throws RpcException {
 // do something
 return this.protocol.export(invoker);
 }

 @Override
 public <T> Invoker<T> refer(Class<T> type, URL url) throws RpcException {
 // do something
 return this.protocol.refer(type, url);
 }

 @Override
 public void destroy() {
 this.protocol.destroy();
 }

 @Override
 public List<ProtocolServer> getServers() {
 return protocol.getServers();
 }
}

SPI配置

Provider

在resources/META-INF/dubbo/org.apache.dubbo.rpc.Protocol文件中添加如下配置：

Registry

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

在服务发现一章中，我们了解了 Dubbo 内置的几个核心注册中心实现 Nacos、Zookeeper 的使用方式与工作原理。本文讲解如何通过扩展 org.apache.dubbo.registry.client.ServiceDiscovery 和 org.apache.dubbo.registry.nacos.NacosServiceDiscoveryFactory SPI，提供自定义的注册中心实现。

本示例的完整源码请参见 dubbo-registry-etcd。除了本示例之外，Dubbo 核心仓库 apache/dubbo 以及扩展库 apache/dubbo-spi-extensions 中的众多注册中心扩展实现，都可以作为扩展参考实现：

# Dubbo对外支持的常用注册中心实现
nacos=org.apache.dubbo.registry.nacos.NacosServiceDiscoveryFactory
zookeeper=org.apache.dubbo.registry.zookeeper.ZookeeperServiceDiscoveryFactory

任务详情

通过扩展 SPI 实现基于的 etcd 注册中心。

实现方式

代码详情

首先，通过继承 AbstractServiceDiscoveryFactory 实现 ServiceDiscoveryFactory 接口

public class EtcdServiceDiscoveryFactory extends AbstractServiceDiscoveryFactory {

 @Override
 protected ServiceDiscovery createDiscovery(URL registryURL) {
 return new EtcdServiceDiscovery(applicationModel, registryURL);
 }

}

EtcdServiceDiscovery 的一些关键方法与实现如下：

public class EtcdServiceDiscovery extends AbstractServiceDiscovery {

 private final Set<String> services = new ConcurrentHashSet<>();
 private final Map<String, InstanceChildListener> childListenerMap = new ConcurrentHashMap<>();

 EtcdClient etcdClient;

 public EtcdServiceDiscovery(ApplicationModel applicationModel, URL registryURL) {
 super(applicationModel, registryURL);
 EtcdTransporter etcdTransporter = applicationModel.getExtensionLoader(EtcdTransporter.class).getAdaptiveExtension();

 etcdClient = etcdTransporter.connect(registryURL);

 etcdClient.addStateListener(state -> {
 if (state == StateListener.CONNECTED) {
 try {
 recover();
 } catch (Exception e) {
 logger.error(e.getMessage(), e);
 }
 }
 });

 this.registryURL = registryURL;
 }

 @Override
 public void doRegister(ServiceInstance serviceInstance) {
 try {
 String path = toPath(serviceInstance);
 etcdClient.putEphemeral(path, new Gson().toJson(serviceInstance));
 services.add(serviceInstance.getServiceName());
 } catch (Throwable e) {
 throw new RpcException("Failed to register " + serviceInstance + " to etcd " + etcdClient.getUrl()
 + ", cause: " + (OptionUtil.isProtocolError(e)
 ? "etcd3 registry may not be supported yet or etcd3 registry is not available."
 : e.getMessage()), e);
 }
 }

 @Override
 protected void doUnregister(ServiceInstance serviceInstance) {
 try {
 String path = toPath(serviceInstance);
 etcdClient.delete(path);
 services.remove(serviceInstance.getServiceName());
 } catch (Throwable e) {
 throw new RpcException("Failed to unregister " + serviceInstance + " to etcd " + etcdClient.getUrl() + ", cause: " + e.getMessage(), e);
 }
 }

 @Override
 public void addServiceInstancesChangedListener(ServiceInstancesChangedListener listener) throws NullPointerException, IllegalArgumentException {
 for (String serviceName : listener.getServiceNames()) {
 registerServiceWatcher(serviceName, listener);
 }
 }

 @Override
 public List<ServiceInstance> getInstances(String serviceName) {
 List<String> children = etcdClient.getChildren(toParentPath(serviceName));
 if (CollectionUtils.isEmpty(children)) {
 return Collections.emptyList();
 }
 List<ServiceInstance> list = new ArrayList<>(children.size());
 for (String child : children) {
 ServiceInstance serviceInstance = new Gson().fromJson(etcdClient.getKVValue(child), DefaultServiceInstance.class);
 list.add(serviceInstance);
 }
 return list;
 }
}

SPI配置

在 resources/META-INF/dubbo/org.apache.dubbo.registry.client.ServiceDiscoveryFactory 文件中添加如下配置：

Router

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

通过自定义路由，可以根据业务场景的特点来实现特定的路由方式。本示例 router 扩展实现源码请参见 dubbo-samples-extensibility。

开始之前

任务详情

对所有的请求都使用第一提供服务的Provider，如果该Provider下线，则从新选择一个新的Provider。

实现方式

在Consumer中自定义一个Router，在Router中将第一次调用的Provider保存下来，如果后续有请求调用且Provider列表中包含第一次调用时使用的Provider，则继续使用第一次调用时使用的Provider，否则重新选去一个Provider。

代码结构

src
 |-main
 |-java
 |-org
 |-apache
 |-dubbo
 |-samples
 |-extensibility
 |-router
 |-consumer
 |-router
 |-StickFirstStateRouter.java (实现StateRouter接口)
 |-StickFirstStateRouterFactory.java (实现StateRouterFactory接口)
 |-resources
 |-META-INF
 |-application.properties (Dubbo Consumer配置文件)
 |-dubbo
 |-org.apache.dubbo.rpc.cluster.router.state.StateRouterFactory (纯文本文件)

代码详情

StickFirstStateRouter

package org.apache.dubbo.samples.extensibility.router.consumer.router;

import org.apache.dubbo.common.URL;
import org.apache.dubbo.common.config.configcenter.ConfigChangeType;
import org.apache.dubbo.common.config.configcenter.ConfigChangedEvent;
import org.apache.dubbo.common.config.configcenter.ConfigurationListener;
import org.apache.dubbo.common.logger.ErrorTypeAwareLogger;
import org.apache.dubbo.common.logger.LoggerFactory;
import org.apache.dubbo.common.utils.CollectionUtils;
import org.apache.dubbo.common.utils.Holder;
import org.apache.dubbo.rpc.Invocation;
import org.apache.dubbo.rpc.Invoker;
import org.apache.dubbo.rpc.RpcException;
import org.apache.dubbo.rpc.cluster.router.RouterSnapshotNode;
import org.apache.dubbo.rpc.cluster.router.state.AbstractStateRouter;
import org.apache.dubbo.rpc.cluster.router.state.BitList;

public class StickFirstStateRouter<T> extends AbstractStateRouter<T> implements ConfigurationListener {
 public StickFirstStateRouter(URL url) {
 super(url);
 }

 public static final String NAME = "STICK_FIRST_ROUTER";
 private static final ErrorTypeAwareLogger logger = LoggerFactory.getErrorTypeAwareLogger(StickFirstStateRouter.class);
 private volatile BitList<Invoker<T>> firstInvokers;

 @Override
 protected BitList<Invoker<T>> doRoute(BitList<Invoker<T>> invokers, URL url, Invocation invocation, boolean needToPrintMessage, Holder<RouterSnapshotNode<T>> routerSnapshotNodeHolder, Holder<String> messageHolder) throws RpcException {
 if (CollectionUtils.isEmpty(invokers)) {
 if (needToPrintMessage) {
 messageHolder.set("Directly Return. Reason: Invokers from previous router is empty.");
 }
 return invokers;
 }
 BitList<Invoker<T>> copy = invokers.clone();
 if (CollectionUtils.isEmpty(copy)) {
 this.firstInvokers = new BitList<>(BitList.emptyList());
 this.firstInvokers.add(copy.get(0));
 } else {
 this.firstInvokers = copy.and(invokers);
 if(CollectionUtils.isEmpty(this.firstInvokers)){
 this.firstInvokers.add(copy.get(0));
 }
 }
 return this.firstInvokers;
 }

 @Override
 public void process(ConfigChangedEvent event) {
 if (logger.isDebugEnabled()) {
 logger.debug("Notification of tag rule, change type is: " + event.getChangeType() + ", raw rule is:\n " +
 event.getContent());
 }
 // Reset
 if (event.getChangeType().equals(ConfigChangeType.DELETED)) {
 this.firstInvokers = null;
 }
 }

 @Override
 public void stop() {
 super.stop();
 this.firstInvokers = null;
 }
}

StickFirstStateRouterFactory

package org.apache.dubbo.samples.extensibility.router.consumer.router;

import org.apache.dubbo.common.URL;
import org.apache.dubbo.rpc.cluster.router.state.StateRouter;
import org.apache.dubbo.rpc.cluster.router.state.StateRouterFactory;

public class StickFirstStateRouterFactory implements StateRouterFactory {
 @Override
 public <T> StateRouter<T> getRouter(Class<T> interfaceClass, URL url) {
 return new StickFirstStateRouter<>(url);
 }
}

SPI配置

在resources/META-INF/dubbo/org.apache.dubbo.rpc.cluster.router.state.StateRouterFactory文件中添加如下配置：