API 配置

以API 配置的方式来配置你的 Dubbo 应用

通过API编码方式组装配置，启动Dubbo，发布及订阅服务。此方式可以支持动态创建ReferenceConfig/ServiceConfig，结合泛化调用可以满足API Gateway或测试平台的需要。

API 属性与XML配置项一一对应，各属性含义请参见：XML配置参考手册，比如：ApplicationConfig.setName("xxx") 对应 <dubbo:application name="xxx" />

API使用范围说明：API 仅用于 OpenAPI, ESB, Test, Mock, Gateway 等系统集成，普通服务提供方或消费方，请采用XML 配置 或 注解配置 或 属性配置 方式使用 Dubbo

参考API示例

服务提供者

通过ServiceConfig暴露服务接口，发布服务接口到注册中心。

注意：为了更好支持Dubbo3的应用级服务发现，推荐使用新的DubboBootstrap API。

  1. import org.apache.dubbo.rpc.config.ApplicationConfig;
  2. import org.apache.dubbo.rpc.config.RegistryConfig;
  3. import org.apache.dubbo.rpc.config.ProviderConfig;
  4. import org.apache.dubbo.rpc.config.ServiceConfig;
  5. import com.xxx.DemoService;
  6. import com.xxx.DemoServiceImpl;
  8. public class DemoProvider {
  9.     public static void main(String[] args) {
  10.         // 服务实现
  11.         DemoService demoService = new DemoServiceImpl();
  13.         // 当前应用配置
  14.         ApplicationConfig application = new ApplicationConfig();
  15.         application.setName("demo-provider");
  17.         // 连接注册中心配置
  18.         RegistryConfig registry = new RegistryConfig();
  19.         registry.setAddress("zookeeper://10.20.130.230:2181");
  21.         // 服务提供者协议配置
  22.         ProtocolConfig protocol = new ProtocolConfig();
  23.         protocol.setName("dubbo");
  24.         protocol.setPort(12345);
  25.         protocol.setThreads(200);
  27.         // 注意：ServiceConfig为重对象，内部封装了与注册中心的连接，以及开启服务端口
  28.         // 服务提供者暴露服务配置
  29.         ServiceConfig<DemoService> service = new ServiceConfig<DemoService>(); // 此实例很重，封装了与注册中心的连接，请自行缓存，否则可能造成内存和连接泄漏
  30.         service.setApplication(application);
  31.         service.setRegistry(registry); // 多个注册中心可以用setRegistries()
  32.         service.setProtocol(protocol); // 多个协议可以用setProtocols()
  33.         service.setInterface(DemoService.class);
  34.         service.setRef(demoService);
  35.         service.setVersion("1.0.0");
  37.         // 暴露及注册服务
  38.         service.export();
  40.         // 挂起等待(防止进程退出）
  41.         System.in.read();
  42.     }
  43. }

服务消费者

通过ReferenceConfig引用远程服务，从注册中心订阅服务接口。

注意：为了更好支持Dubbo3的应用级服务发现，推荐使用新的DubboBootstrap API。

  1. import org.apache.dubbo.rpc.config.ApplicationConfig;
  2. import org.apache.dubbo.rpc.config.RegistryConfig;
  3. import org.apache.dubbo.rpc.config.ConsumerConfig;
  4. import org.apache.dubbo.rpc.config.ReferenceConfig;
  5. import com.xxx.DemoService;
  7. public class DemoConsumer {
  8.     public static void main(String[] args) {
  9.         // 当前应用配置
  10.         ApplicationConfig application = new ApplicationConfig();
  11.         application.setName("demo-consumer");
  13.         // 连接注册中心配置
  14.         RegistryConfig registry = new RegistryConfig();
  15.         registry.setAddress("zookeeper://10.20.130.230:2181");
  17.         // 注意：ReferenceConfig为重对象，内部封装了与注册中心的连接，以及与服务提供方的连接
  18.         // 引用远程服务
  19.         ReferenceConfig<DemoService> reference = new ReferenceConfig<DemoService>(); // 此实例很重，封装了与注册中心的连接以及与提供者的连接，请自行缓存，否则可能造成内存和连接泄漏
  20.         reference.setApplication(application);
  21.         reference.setRegistry(registry); // 多个注册中心可以用setRegistries()
  22.         reference.setInterface(DemoService.class);
  23.         reference.setVersion("1.0.0");
  25.         // 和本地bean一样使用demoService
  26.         // 注意：此代理对象内部封装了所有通讯细节，对象较重，请缓存复用
  27.         DemoService demoService = reference.get();
  28.         demoService.sayHello("Dubbo");
  29.     }
  30. }

Bootstrap API

通过DubboBootstrap API可以减少重复配置，更好控制启动过程，支持批量发布/订阅服务接口，还可以更好支持Dubbo3的应用级服务发现。

  1. import org.apache.dubbo.config.bootstrap.DubboBootstrap;
  2. import org.apache.dubbo.rpc.config.ApplicationConfig;
  3. import org.apache.dubbo.rpc.config.RegistryConfig;
  4. import org.apache.dubbo.rpc.config.ProviderConfig;
  5. import org.apache.dubbo.rpc.config.ServiceConfig;
  6. import com.xxx.DemoService;
  7. import com.xxx.DemoServiceImpl;
  9. public class DemoProvider {
  10.     public static void main(String[] args) {
  12.         ConfigCenterConfig configCenter = new ConfigCenterConfig();
  13.         configCenter.setAddress("zookeeper://127.0.0.1:2181");
  15.         // 服务提供者协议配置
  16.         ProtocolConfig protocol = new ProtocolConfig();
  17.         protocol.setName("dubbo");
  18.         protocol.setPort(12345);
  19.         protocol.setThreads(200);
  21.         // 注意：ServiceConfig为重对象，内部封装了与注册中心的连接，以及开启服务端口
  22.         // 服务提供者暴露服务配置
  23.         ServiceConfig<DemoService> demoServiceConfig = new ServiceConfig<>();
  24.         demoServiceConfig.setInterface(DemoService.class);
  25.         demoServiceConfig.setRef(new DemoServiceImpl());
  26.         demoServiceConfig.setVersion("1.0.0");
  28.         // 第二个服务配置
  29.         ServiceConfig<FooService> fooServiceConfig = new ServiceConfig<>();
  30.         fooServiceConfig.setInterface(FooService.class);
  31.         fooServiceConfig.setRef(new FooServiceImpl());
  32.         fooServiceConfig.setVersion("1.0.0");
  34.         ...
  36.         // 通过DubboBootstrap简化配置组装，控制启动过程
  37.         DubboBootstrap.getInstance()
  38.                 .application("demo-provider") // 应用配置
  39.                 .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) // 注册中心配置
  40.                 .protocol(protocol) // 全局默认协议配置
  41.                 .service(demoServiceConfig) // 添加ServiceConfig
  42.                 .service(fooServiceConfig)
  43.                 .start()    // 启动Dubbo
  44.                 .await();   // 挂起等待(防止进程退出）
  45.     }
  46. }
  1. import org.apache.dubbo.config.bootstrap.DubboBootstrap;
  2. import org.apache.dubbo.rpc.config.ApplicationConfig;
  3. import org.apache.dubbo.rpc.config.RegistryConfig;
  4. import org.apache.dubbo.rpc.config.ProviderConfig;
  5. import org.apache.dubbo.rpc.config.ServiceConfig;
  6. import com.xxx.DemoService;
  7. import com.xxx.DemoServiceImpl;
  9. public class DemoConsumer {
  10.     public static void main(String[] args) {
  12.         // 引用远程服务
  13.         ReferenceConfig<DemoService> demoServiceReference = new ReferenceConfig<DemoService>(); 
  14.         demoServiceReference.setInterface(DemoService.class);
  15.         demoServiceReference.setVersion("1.0.0");
  17.         ReferenceConfig<FooService> fooServiceReference = new ReferenceConfig<FooService>(); 
  18.         fooServiceReference.setInterface(FooService.class);
  19.         fooServiceReference.setVersion("1.0.0");
  21.         // 通过DubboBootstrap简化配置组装，控制启动过程
  22.         DubboBootstrap bootstrap = DubboBootstrap.getInstance();
  23.         bootstrap.application("demo-consumer") // 应用配置
  24.                 .registry(new RegistryConfig("zookeeper://127.0.0.1:2181")) // 注册中心配置
  25.                 .reference(demoServiceReference) // 添加ReferenceConfig
  26.                 .service(fooServiceReference)
  27.                 .start();    // 启动Dubbo
  29.         ...
  31.         // 和本地bean一样使用demoService
  32.         // 通过Interface获取远程服务接口代理，不需要依赖ReferenceConfig对象
  33.         DemoService demoService = DubboBootstrap.getInstance().getCache().get(DemoService.class);
  34.         demoService.sayHello("Dubbo");
  36.         FooService fooService = DubboBootstrap.getInstance().getCache().get(FooService.class);
  37.         fooService.greeting("Dubbo");
  38.     }
  40. }

其它配置

API配置能力与XML配置是等价的，其它的各种配置都可以用API设置。

下面只列出不同的地方，其它参见上面的写法。

基本配置

可以在DubboBootstrap中设置全局基本配置，包括应用配置、协议配置、注册中心、配置中心、元数据中心、模块、监控、SSL、provider配置、consumer配置等。

  1. // 注册中心
  2. RegistryConfig registry = new RegistryConfig();
  3. registry.setAddress("zookeeper://192.168.10.1:2181");
  4. ...
  6. // 服务提供者协议配置
  7. ProtocolConfig protocol = new ProtocolConfig();
  8. protocol.setName("dubbo");
  9. protocol.setPort(12345);
  10. protocol.setThreads(200);
  11. ...
  13. // 配置中心
  14. ConfigCenterConfig configCenter = new ConfigCenterConfig();
  15. configCenter.setAddress("zookeeper://192.168.10.2:2181");
  16. ...
  18. // 元数据中心
  19. MetadataReportConfig metadataReport = new MetadataReportConfig();
  20. metadataReport.setAddress("zookeeper://192.168.10.3:2181");
  21. ...
  23. // Metrics
  24. MetricsConfig metrics = new MetricsConfig();
  25. metrics.setProtocol("dubbo");
  26. ...
  28. // SSL
  29. SslConfig ssl = new SslConfig();
  30. ssl.setServerKeyCertChainPath("/path/ssl/server-key-cert-chain");
  31. ssl.setServerPrivateKeyPath("/path/ssl/server-private-key");
  32. ...
  34. // Provider配置（ServiceConfig默认配置）
  35. ProviderConfig provider = new ProviderConfig();
  36. provider.setGroup("demo");
  37. provider.setVersion("1.0.0");
  38. ...
  40. // Consumer配置（ReferenceConfig默认配置）
  41. ConsumerConfig consumer = new ConsumerConfig();
  42. consumer.setGroup("demo");
  43. consumer.setVersion("1.0.0");
  44. consumer.setTimeout(2000);
  45. ...
  47. DubboBootstrap.getInstance()
  48.     .application("demo-app")
  49.     .registry(registry)
  50.     .protocol(protocol)
  51.     .configCenter(configCenter)
  52.     .metadataReport(metadataReport)
  53.     .module(new ModuleConfig("module"))
  54.     .metrics(metrics)
  55.       .ssl(ssl)
  56.       .provider(provider)
  57.       .consumer(consumer)
  58.       ...
  59.       .start();

方法级设置

  1. ...
  3. // 方法级配置
  4. List<MethodConfig> methods = new ArrayList<MethodConfig>();
  5. MethodConfig method = new MethodConfig();
  6. method.setName("sayHello");
  7. method.setTimeout(10000);
  8. method.setRetries(0);
  9. methods.add(method);
  11. // 引用远程服务
  12. ReferenceConfig<DemoService> reference = new ReferenceConfig<DemoService>(); // 此实例很重，封装了与注册中心的连接以及与提供者的连接，请自行缓存，否则可能造成内存和连接泄漏
  13. ...
  14. reference.setMethods(methods); // 设置方法级配置
  16. ...

点对点直连

  2. ...
  4. // 此实例很重，封装了与注册中心的连接以及与提供者的连接，请自行缓存，否则可能造成内存和连接泄漏
  5. ReferenceConfig<DemoService> reference = new ReferenceConfig<DemoService>(); 
  6. // 如果点对点直连，可以用reference.setUrl()指定目标地址，设置url后将绕过注册中心，
  7. // 其中，协议对应provider.setProtocol()的值，端口对应provider.setPort()的值，
  8. // 路径对应service.setPath()的值，如果未设置path，缺省path为接口名
  9. reference.setUrl("dubbo://10.20.130.230:20880/com.xxx.DemoService"); 
  11. ...

最后修改 September 21, 2021: Bug fix miss mialbox (#953) (57cf51b)