1. 从单体到分布式为什么要在 Spring 里引入 Dubbo很多做 Java 后端的同学第一次接触分布式服务调用都是从“本地方法调用”直接跳到“远程调用”这个概念的。在单体应用里Service A 调 Service B就是一次普通的 Java 方法调用编译器帮你把参数压栈、把返回值带回来整个过程在同一个 JVM 里完成快得你根本感觉不到它的存在。可一旦业务膨胀订单、库存、用户、支付这些模块各自独立部署本地调用就彻底失效了——你没法在一个进程里 new 出另一个进程的对象。这时候就需要一个“远程调用框架”来补位。Dubbo 就是干这个的它把“调用远程服务”这件事伪装得跟“调用本地方法”几乎一样。你写orderService.createOrder(...)底层其实经历了网络传输、序列化、负载均衡、服务发现这一整套流程但对你来说代码写起来跟本地调用没区别。这就是 RPC远程过程调用框架的核心价值让分布式调用对开发者透明。那为什么是 Spring 整合 Dubbo而不是单独用 Dubbo因为 Spring 的 IOC 容器和 AOP 能力能把 Dubbo 的服务暴露和引用过程变成几个注解或者几行 XML 配置的事。你不用手动去写ServiceConfig、ReferenceConfig这些底层 APISpring 帮你管理 Bean 的生命周期Dubbo 帮你管理服务的注册与发现。两者结合才是生产环境里最常见的落地方式。这篇文章适合谁看如果你已经会写 Spring Boot 或者 Spring MVC 的常规业务代码但对“服务怎么拆出去”“消费者怎么找到提供者”这些问题还比较模糊那这篇内容就是给你准备的。我会从零开始把 Spring 整合 Dubbo 的完整链路拆开包括依赖选型、配置细节、启动顺序、常见报错以及我实际踩过的几个坑。不堆概念只讲能跑起来的代码和能复现的排查思路。提示本文基于 Dubbo 2.7.x 与 Spring Boot 2.x 的整合场景展开这是目前存量项目里最主流的组合。如果你用的是 Dubbo 3.x核心思路一致但部分配置项和注册中心行为有差异我会在对应位置标注。2. 动手之前的选型账注册中心、协议与依赖版本2.1 注册中心为什么首选 ZooKeeper 或 NacosDubbo 要工作必须有一个“服务注册中心”。提供者启动时把自己的地址写进去消费者启动时从里面读出来这样双方才能建立连接。没有注册中心你就得手动配置提供者的 IP 和端口一旦提供者扩容或者迁移消费者就得跟着改配置这在生产环境里是不可接受的。常见的注册中心有两个主流选择ZooKeeper 和 Nacos。ZooKeeper 是 Dubbo 早期默认的注册中心基于 ZAB 协议保证一致性成熟稳定很多老项目都在用。Nacos 是后来者除了服务注册发现还集成了配置管理控制台更友好支持临时实例和持久实例的灵活切换。我个人的建议是新项目直接用 Nacos老项目如果已经在用 ZooKeeper没必要为了换而换。两者的整合代码差异很小主要就是依赖和配置地址不同。下面这张表可以帮你快速决策对比维度ZooKeeperNacos一致性协议ZABRaftCP DistroAP控制台无原生UI需第三方自带Web控制台配置管理不支持原生支持健康检查会话心跳心跳主动探测适用场景存量老项目新项目、云原生环境2.2 依赖引入别小看这几个 artifactSpring 整合 Dubbo依赖引入是最容易出问题的地方。很多人直接抄网上的 pom结果启动就报NoSuchMethodError或者ClassNotFoundException根源就是版本没对齐。核心依赖其实就三个dubbo-spring-boot-starterDubbo 官方提供的 Spring Boot 整合包封装了自动配置。dubboDubbo 核心包starter 会传递依赖进来但有时需要显式指定版本。注册中心客户端用 ZooKeeper 就引curator-framework和curator-recipes用 Nacos 就引nacos-client。这里有个细节Dubbo 2.7.x 的 starter 版本号要和 Dubbo 核心版本保持一致。比如你用dubbo-spring-boot-starter:2.7.8那dubbo也应该是2.7.8。如果项目里还有其他依赖间接引入了不同版本的 Dubbo就会产生冲突。我习惯在 pom 里用dependencyManagement锁定版本避免这种隐性冲突。dependencyManagement dependencies dependency groupIdorg.apache.dubbo/groupId artifactIddubbo-dependencies-bom/artifactId version2.7.8/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement注意Dubbo 2.7 之后groupId 从com.alibaba变成了org.apache如果你还在用老版本的com.alibaba.dubbo配置项前缀也是dubbo.而不是spring.dubbo.这个迁移坑很多人踩过。2.3 通信协议的选择逻辑Dubbo 支持多种通信协议默认是dubbo协议基于 Netty 的单一长连接和 NIO 异步通信适合小数据量、高并发的服务调用。除此之外还有rmi、hessian、http等。为什么默认用 dubbo 协议因为它针对服务调用场景做了优化单一长连接减少了连接建立的开销二进制序列化比文本协议更紧凑异步通信提升了吞吐量。但如果你要调用的服务参数或返回值特别大比如传输大文件dubbo 协议的单一长连接反而会成为瓶颈这时候可以考虑hessian协议它支持多连接和短连接。对于入门场景直接用默认的 dubbo 协议就行不需要额外配置。等你遇到性能瓶颈或者跨语言调用需求时再考虑换协议。3. 提供者端把本地服务暴露成远程服务3.1 接口抽离为什么必须单独建一个 API 模块这是新手最容易忽略的一步。提供者和消费者要能互相调用双方必须共享同一份接口定义。如果你把接口写在提供者模块里消费者就得依赖提供者的整个 jar 包这显然不合理——消费者可能只需要一个接口却被迫引入了提供者的所有实现和依赖。正确的做法是单独建一个 API 模块里面只放接口和传输对象DTO提供者和消费者都依赖这个模块。这样消费者编译时只需要 API 模块的 jar运行时通过 Dubbo 动态代理调用远程实现。// api 模块中的接口定义 public interface UserService { UserDTO getUserById(Long id); boolean register(UserDTO user); }这个接口里不要出现任何提供者特有的类比如数据库实体、内部工具类。DTO 也要尽量简单只包含需要传输的字段并且实现Serializable接口——因为跨进程传输需要序列化。3.2 服务实现与 DubboService 注解提供者端的服务实现类就是普通的 Spring Bean只不过要加上DubboService注解Dubbo 2.7.7 之后推荐用这个之前是Service但会和 Spring 的Service冲突。DubboService(version 1.0.0, timeout 3000) public class UserServiceImpl implements UserService { Autowired private UserMapper userMapper; Override public UserDTO getUserById(Long id) { User user userMapper.selectById(id); if (user null) { return null; } UserDTO dto new UserDTO(); dto.setId(user.getId()); dto.setName(user.getName()); return dto; } Override public boolean register(UserDTO user) { // 注册逻辑 return true; } }这里有几个关键参数需要解释version服务版本号。当同一个接口有多个实现时用版本号区分。消费者引用时必须指定相同的版本号否则找不到服务。timeout调用超时时间单位毫秒。默认是 1000ms但实际业务中数据库查询可能超过这个时间建议根据业务设置合理值。group服务分组用于隔离不同环境或不同业务线的服务。提示DubboService注解默认会把服务注册到所有配置的注册中心。如果你有多个注册中心可以用registry属性指定。3.3 配置文件里的那些必填项提供者的application.yml里至少需要配置应用名、注册中心地址和协议端口dubbo: application: name: user-service-provider registry: address: nacos://127.0.0.1:8848 protocol: name: dubbo port: 20880 scan: base-packages: com.example.provider.service逐项说明dubbo.application.name应用名必须唯一。注册中心里就是靠这个区分不同应用的。dubbo.registry.address注册中心地址。用 Nacos 就写nacos://ip:port用 ZooKeeper 就写zookeeper://ip:port。dubbo.protocol.portDubbo 服务暴露的端口。默认是 20880如果一台机器部署多个提供者端口会自增20880、20881...。生产环境建议显式指定避免端口冲突。dubbo.scan.base-packages扫描DubboService注解的包路径。不配这个注解不会被处理服务也不会暴露。我见过有人只配了注册中心忘了配scan结果启动没报错但消费者就是调不到服务。排查了半天才发现是注解没被扫描到。这个坑很隐蔽因为 Dubbo 不会主动提示你“有注解没扫描”。3.4 启动顺序与注册中心连接验证提供者启动时Dubbo 会做几件事连接注册中心、创建服务代理、把服务地址写入注册中心、启动 Netty 监听端口。如果注册中心连不上启动会失败并抛出RpcException。启动成功后你可以去 Nacos 控制台或者 ZooKeeper 客户端里验证服务是否注册成功。Nacos 的话在“服务管理-服务列表”里应该能看到你的应用名和对应的实例地址。ZooKeeper 的话用ls /dubbo/com.example.api.UserService/providers命令查看。如果注册中心里没有你的服务按这个顺序排查DubboService注解是否加在实现类上而不是接口上。dubbo.scan.base-packages是否覆盖了实现类所在的包。注册中心地址是否正确网络是否连通。是否有多个注册中心配置冲突。4. 消费者端像调用本地 Bean 一样调用远程服务4.1 DubboReference 的注入逻辑消费者端要引用远程服务只需要在字段上加DubboReference注解RestController public class UserController { DubboReference(version 1.0.0, timeout 3000) private UserService userService; GetMapping(/user/{id}) public UserDTO getUser(PathVariable Long id) { return userService.getUserById(id); } }Spring 启动时Dubbo 会为这个字段生成一个动态代理对象。当你调用userService.getUserById(id)时代理对象会拦截调用从注册中心获取提供者地址列表经过负载均衡选出一个提供者把方法名、参数类型、参数值序列化后通过网络发送过去等待响应后再反序列化返回结果。整个过程对开发者完全透明。你不需要写任何网络代码也不需要手动处理连接池。4.2 消费者配置少即是多消费者的配置比提供者更简单通常只需要应用名和注册中心地址dubbo: application: name: order-service-consumer registry: address: nacos://127.0.0.1:8848不需要配protocol因为消费者不暴露服务只发起调用。也不需要配scan因为DubboReference是在字段上Spring 处理 Bean 注入时就会处理。但有一个配置建议加上dubbo.consumer.checkfalse。默认情况下消费者启动时会检查依赖的服务是否可用如果提供者还没启动消费者会启动失败。在开发环境或者提供者启动较慢的场景下这个检查很烦人。设为false后消费者启动时不会检查调用时如果服务不可用才会报错。dubbo: consumer: check: false timeout: 5000 retries: 2check启动时是否检查服务可用性。timeout默认调用超时时间可以被DubboReference上的配置覆盖。retries失败重试次数默认是 2。注意重试只对幂等操作安全非幂等操作比如插入数据要设为 0否则可能重复插入。4.3 直连模式开发调试时的救命稻草有时候你只想本地调试不想启动注册中心或者提供者还没注册到注册中心。这时候可以用直连模式绕过注册中心直接调用指定地址DubboReference(url dubbo://127.0.0.1:20880, version 1.0.0) private UserService userService;或者在配置里全局指定dubbo: reference: url: dubbo://127.0.0.1:20880直连模式在排查“是注册中心问题还是服务本身问题”时特别有用。如果直连能调通说明服务实现没问题问题出在注册中心如果直连也调不通那就是服务本身或者网络的问题。注意直连模式只适合开发调试生产环境绝对不要用。因为直连绕过了服务发现提供者扩容或迁移后消费者无法感知。4.4 异步调用与泛化调用简介Dubbo 还支持异步调用消费者发起调用后不阻塞等待结果而是通过 Future 或者回调获取。这在批量调用或者对响应时间敏感的场景下很有用。配置方式是在DubboReference上加async true然后通过RpcContext.getContext().getFuture()获取 Future 对象。泛化调用则是消费者没有 API 接口的情况下的兜底方案。比如你做一个网关需要调用各种未知的服务不可能为每个服务都引入 API 包。这时候可以用GenericService接口传入方法名、参数类型和参数值Dubbo 会帮你完成调用。泛化调用的性能比正常调用略低因为少了编译期的类型检查但灵活性极高。这两个特性入门阶段可以先了解等有具体需求时再深入。5. 联调时最容易卡住的几个环节5.1 服务找不到从注册中心到网络的全链路排查“No provider available for the service”是 Dubbo 最常见的报错。这个报错的意思是消费者在注册中心里找不到可用的提供者。排查要按链路走不要跳步。第一步确认提供者是否真的注册成功了。去注册中心控制台看服务列表里有没有提供者的应用名实例列表里有没有具体的 IP 和端口。如果没有回到提供者端排查DubboService和scan配置。第二步确认消费者和提供者连的是同一个注册中心。这个听起来很蠢但我确实见过有人提供者连的是测试环境的 Nacos消费者连的是本地的 ZooKeeper两边完全不在一个频道上。第三步确认服务接口的全限定名、版本号、分组是否完全一致。消费者写version 1.0.0提供者写version 1.0.1或者消费者没写版本号而提供者写了都会导致找不到服务。Dubbo 的匹配是精确匹配差一个字符都不行。第四步检查网络连通性。消费者能不能 ping 通提供者的 IP提供者的端口是不是被防火墙拦了。Dubbo 默认用 20880 端口有些公司的安全策略会封禁非标准端口。5.2 序列化异常实体类没实现 Serializable 的后果这个报错信息通常是org.apache.dubbo.remoting.RemotingException: Failed to invoke the method ... cause: java.io.NotSerializableException。原因很简单传输的对象没有实现Serializable接口。Dubbo 默认用 Hessian2 序列化它要求传输的对象必须可序列化。不仅是 DTO 本身DTO 里嵌套的所有对象也都要可序列化。我遇到过有人在 DTO 里放了一个java.util.DateDate 本身是可序列化的但它的子类java.sql.Timestamp在某些序列化器下会有问题。所以 DTO 里的字段类型尽量用基本类型和 String复杂类型要确认序列化兼容性。另外如果 DTO 里有无参构造函数之外的构造函数但没有保留无参构造函数Hessian2 反序列化时也会失败。因为反序列化需要先创建实例再填充字段没有无参构造函数就没法创建。5.3 超时与重试默认参数在真实业务里的陷阱Dubbo 默认超时是 1000ms默认重试 2 次。这两个默认值在真实业务里经常出问题。先说超时。1000ms 对于简单的内存操作够用但一旦涉及数据库查询、远程缓存、第三方接口调用很容易超过。超时后消费者会抛出TimeoutException然后触发重试。如果提供者的业务逻辑已经执行了比如已经扣了库存但响应因为网络慢没及时返回重试就会导致重复扣减。再说重试。默认重试 2 次加上首次调用一共 3 次。对于查询操作重试是安全的还能提高成功率。但对于插入、更新、删除操作重试就是灾难。所以我的习惯是所有非幂等的服务在DubboService或DubboReference上显式设置retries 0。DubboService(version 1.0.0, timeout 5000, retries 0) public class OrderServiceImpl implements OrderService { // 下单逻辑绝对不能重试 }超时时间也要根据业务设置。我的经验值是数据库单表查询设 3000ms复杂查询设 5000ms调用第三方接口设 10000ms。不要全局设一个很大的值那样一旦提供者真的挂了消费者会长时间阻塞拖垮整个调用链。5.4 启动顺序导致的假死现象在微服务架构里服务之间有依赖关系。如果消费者启动时提供者还没启动消费者会报“No provider available”然后启动失败如果checktrue。但如果checkfalse消费者能启动成功但第一次调用时会失败。更隐蔽的情况是提供者启动了但还没完成服务注册消费者就开始调用了。Dubbo 的服务注册是异步的提供者启动完成后注册中心的通知可能还有延迟。如果消费者在这个窗口期发起调用就会失败。解决办法有两个一是消费者配置checkfalse并配合重试机制二是用 Dubbo 的lazy属性延迟初始化。但最根本的还是要保证启动顺序或者在网关层做健康检查等所有依赖服务都就绪后再放流量进来。6. 从能跑到好用几个值得提前知道的优化点6.1 服务分组与多版本并行当同一个接口需要同时存在多个实现时比如灰度发布场景老版本和新版本要并行运行这时候就需要用group和version来区分。// 提供者老版本 DubboService(version 1.0.0, group stable) public class UserServiceStableImpl implements UserService { } // 提供者新版本 DubboService(version 2.0.0, group gray) public class UserServiceGrayImpl implements UserService { } // 消费者指定调用灰度版本 DubboReference(version 2.0.0, group gray) private UserService userService;这样可以在不影响老用户的情况下让部分流量走新版本。等新版本验证稳定后再把所有消费者的配置切到新版本。6.2 本地伪装与容错降级Dubbo 提供了mock机制当远程调用失败时可以返回一个本地伪装的结果而不是直接抛异常。这在依赖服务不可用时能保证主流程不被阻塞。DubboReference(version 1.0.0, mock com.example.mock.UserServiceMock) private UserService userService;UserServiceMock需要实现UserService接口并提供一个无参构造函数。当远程调用失败时Dubbo 会调用 Mock 类的对应方法返回兜底数据。这个机制在秒杀、大促场景下特别有用。比如推荐服务挂了返回一个默认的热门列表总比整个页面报错要好。6.3 监控与治理的入口Dubbo 自带了一个简单的监控中心dubbo-monitor可以统计调用次数、成功率、响应时间等指标。虽然功能不如专业的 APM 系统但对于入门和中小项目来说够用了。配置方式是在提供者和消费者都加上dubbo: monitor: protocol: registry这样监控数据会通过注册中心上报。启动 dubbo-monitor 后可以在控制台看到服务的调用统计。如果公司有 Prometheus Grafana 的监控体系Dubbo 也支持通过dubbo-metrics-prometheus模块暴露指标接入现有的监控大盘。6.4 线程模型与连接数控制Dubbo 默认的线程模型是all即所有消息都派发到业务线程池。线程池默认大小是 200队列长度是 0即不排队直接拒绝。在高并发场景下这个配置可能导致请求被拒绝。如果服务大多是 CPU 密集型线程数可以设小一点比如 CPU 核数 1。如果是 IO 密集型线程数可以设大一点比如 500。队列长度建议设一个合理的值比如 1000避免瞬间流量直接打满线程池。dubbo: protocol: threads: 500 queues: 1000连接数方面Dubbo 默认是共享单一长连接。如果提供者的服务处理时间较长单一连接可能成为瓶颈。可以通过connections参数增加连接数DubboReference(connections 10) private UserService userService;但连接数不是越多越好每个连接都会占用系统资源。一般建议根据压测结果来调整不要盲目设大。7. 我踩过的三个真实坑与对应解法第一个坑是注解冲突。早期 Dubbo 用Service注解暴露服务但 Spring 也有Service。我在同一个类上同时写了两个Service结果 Spring 把它当成了普通 BeanDubbo 没识别到服务一直注册不上去。后来换成DubboService才解决。如果你用的是 Dubbo 2.7.7 之前的版本要么用 XML 配置要么确保Service的包路径是org.apache.dubbo.config.annotation.Service。第二个坑是泛型擦除导致的序列化问题。我在 DTO 里用了一个ListT字段运行时 T 被擦除成 ObjectHessian2 序列化时无法确定具体类型反序列化后变成了ListMap。消费者拿到数据后强转报ClassCastException。解决办法是 DTO 里的集合字段尽量用具体类型比如ListUserDTO而不是ListT或者用JSONField之类的注解指定类型信息。第三个坑是注册中心地址配了多个但只生效一个。我在dubbo.registry.address里写了两个地址用逗号分隔以为会同时注册到两个注册中心。实际上 Dubbo 默认只使用第一个可用的地址后面的作为备份。如果要同时注册到多个注册中心需要配置多个dubbo.registries节点并在DubboService上指定registry属性。这个细节官方文档里写得很隐蔽我是看了源码才搞明白。最后分享一个排查小技巧Dubbo 启动时会打印服务暴露和引用的日志把日志级别调到DEBUG可以看到服务注册的详细过程包括注册中心地址、服务接口、版本号、分组等信息。如果服务找不到先看这些日志比盲目猜要快得多。logging: level: org.apache.dubbo: DEBUG这个配置在开发环境建议一直开着生产环境再调回INFO。
1. 从单体到分布式为什么要在 Spring 里引入 Dubbo很多做 Java 后端的同学第一次接触分布式服务调用都是从“本地方法调用”直接跳到“远程调用”这个概念的。在单体应用里Service A 调 Service B就是一次普通的 Java 方法调用编译器帮你把参数压栈、把返回值带回来整个过程在同一个 JVM 里完成快得你根本感觉不到它的存在。可一旦业务膨胀订单、库存、用户、支付这些模块各自独立部署本地调用就彻底失效了——你没法在一个进程里 new 出另一个进程的对象。这时候就需要一个“远程调用框架”来补位。Dubbo 就是干这个的它把“调用远程服务”这件事伪装得跟“调用本地方法”几乎一样。你写orderService.createOrder(...)底层其实经历了网络传输、序列化、负载均衡、服务发现这一整套流程但对你来说代码写起来跟本地调用没区别。这就是 RPC远程过程调用框架的核心价值让分布式调用对开发者透明。那为什么是 Spring 整合 Dubbo而不是单独用 Dubbo因为 Spring 的 IOC 容器和 AOP 能力能把 Dubbo 的服务暴露和引用过程变成几个注解或者几行 XML 配置的事。你不用手动去写ServiceConfig、ReferenceConfig这些底层 APISpring 帮你管理 Bean 的生命周期Dubbo 帮你管理服务的注册与发现。两者结合才是生产环境里最常见的落地方式。这篇文章适合谁看如果你已经会写 Spring Boot 或者 Spring MVC 的常规业务代码但对“服务怎么拆出去”“消费者怎么找到提供者”这些问题还比较模糊那这篇内容就是给你准备的。我会从零开始把 Spring 整合 Dubbo 的完整链路拆开包括依赖选型、配置细节、启动顺序、常见报错以及我实际踩过的几个坑。不堆概念只讲能跑起来的代码和能复现的排查思路。提示本文基于 Dubbo 2.7.x 与 Spring Boot 2.x 的整合场景展开这是目前存量项目里最主流的组合。如果你用的是 Dubbo 3.x核心思路一致但部分配置项和注册中心行为有差异我会在对应位置标注。2. 动手之前的选型账注册中心、协议与依赖版本2.1 注册中心为什么首选 ZooKeeper 或 NacosDubbo 要工作必须有一个“服务注册中心”。提供者启动时把自己的地址写进去消费者启动时从里面读出来这样双方才能建立连接。没有注册中心你就得手动配置提供者的 IP 和端口一旦提供者扩容或者迁移消费者就得跟着改配置这在生产环境里是不可接受的。常见的注册中心有两个主流选择ZooKeeper 和 Nacos。ZooKeeper 是 Dubbo 早期默认的注册中心基于 ZAB 协议保证一致性成熟稳定很多老项目都在用。Nacos 是后来者除了服务注册发现还集成了配置管理控制台更友好支持临时实例和持久实例的灵活切换。我个人的建议是新项目直接用 Nacos老项目如果已经在用 ZooKeeper没必要为了换而换。两者的整合代码差异很小主要就是依赖和配置地址不同。下面这张表可以帮你快速决策对比维度ZooKeeperNacos一致性协议ZABRaftCP DistroAP控制台无原生UI需第三方自带Web控制台配置管理不支持原生支持健康检查会话心跳心跳主动探测适用场景存量老项目新项目、云原生环境2.2 依赖引入别小看这几个 artifactSpring 整合 Dubbo依赖引入是最容易出问题的地方。很多人直接抄网上的 pom结果启动就报NoSuchMethodError或者ClassNotFoundException根源就是版本没对齐。核心依赖其实就三个dubbo-spring-boot-starterDubbo 官方提供的 Spring Boot 整合包封装了自动配置。dubboDubbo 核心包starter 会传递依赖进来但有时需要显式指定版本。注册中心客户端用 ZooKeeper 就引curator-framework和curator-recipes用 Nacos 就引nacos-client。这里有个细节Dubbo 2.7.x 的 starter 版本号要和 Dubbo 核心版本保持一致。比如你用dubbo-spring-boot-starter:2.7.8那dubbo也应该是2.7.8。如果项目里还有其他依赖间接引入了不同版本的 Dubbo就会产生冲突。我习惯在 pom 里用dependencyManagement锁定版本避免这种隐性冲突。dependencyManagement dependencies dependency groupIdorg.apache.dubbo/groupId artifactIddubbo-dependencies-bom/artifactId version2.7.8/version typepom/type scopeimport/scope /dependency /dependencies /dependencyManagement注意Dubbo 2.7 之后groupId 从com.alibaba变成了org.apache如果你还在用老版本的com.alibaba.dubbo配置项前缀也是dubbo.而不是spring.dubbo.这个迁移坑很多人踩过。2.3 通信协议的选择逻辑Dubbo 支持多种通信协议默认是dubbo协议基于 Netty 的单一长连接和 NIO 异步通信适合小数据量、高并发的服务调用。除此之外还有rmi、hessian、http等。为什么默认用 dubbo 协议因为它针对服务调用场景做了优化单一长连接减少了连接建立的开销二进制序列化比文本协议更紧凑异步通信提升了吞吐量。但如果你要调用的服务参数或返回值特别大比如传输大文件dubbo 协议的单一长连接反而会成为瓶颈这时候可以考虑hessian协议它支持多连接和短连接。对于入门场景直接用默认的 dubbo 协议就行不需要额外配置。等你遇到性能瓶颈或者跨语言调用需求时再考虑换协议。3. 提供者端把本地服务暴露成远程服务3.1 接口抽离为什么必须单独建一个 API 模块这是新手最容易忽略的一步。提供者和消费者要能互相调用双方必须共享同一份接口定义。如果你把接口写在提供者模块里消费者就得依赖提供者的整个 jar 包这显然不合理——消费者可能只需要一个接口却被迫引入了提供者的所有实现和依赖。正确的做法是单独建一个 API 模块里面只放接口和传输对象DTO提供者和消费者都依赖这个模块。这样消费者编译时只需要 API 模块的 jar运行时通过 Dubbo 动态代理调用远程实现。// api 模块中的接口定义 public interface UserService { UserDTO getUserById(Long id); boolean register(UserDTO user); }这个接口里不要出现任何提供者特有的类比如数据库实体、内部工具类。DTO 也要尽量简单只包含需要传输的字段并且实现Serializable接口——因为跨进程传输需要序列化。3.2 服务实现与 DubboService 注解提供者端的服务实现类就是普通的 Spring Bean只不过要加上DubboService注解Dubbo 2.7.7 之后推荐用这个之前是Service但会和 Spring 的Service冲突。DubboService(version 1.0.0, timeout 3000) public class UserServiceImpl implements UserService { Autowired private UserMapper userMapper; Override public UserDTO getUserById(Long id) { User user userMapper.selectById(id); if (user null) { return null; } UserDTO dto new UserDTO(); dto.setId(user.getId()); dto.setName(user.getName()); return dto; } Override public boolean register(UserDTO user) { // 注册逻辑 return true; } }这里有几个关键参数需要解释version服务版本号。当同一个接口有多个实现时用版本号区分。消费者引用时必须指定相同的版本号否则找不到服务。timeout调用超时时间单位毫秒。默认是 1000ms但实际业务中数据库查询可能超过这个时间建议根据业务设置合理值。group服务分组用于隔离不同环境或不同业务线的服务。提示DubboService注解默认会把服务注册到所有配置的注册中心。如果你有多个注册中心可以用registry属性指定。3.3 配置文件里的那些必填项提供者的application.yml里至少需要配置应用名、注册中心地址和协议端口dubbo: application: name: user-service-provider registry: address: nacos://127.0.0.1:8848 protocol: name: dubbo port: 20880 scan: base-packages: com.example.provider.service逐项说明dubbo.application.name应用名必须唯一。注册中心里就是靠这个区分不同应用的。dubbo.registry.address注册中心地址。用 Nacos 就写nacos://ip:port用 ZooKeeper 就写zookeeper://ip:port。dubbo.protocol.portDubbo 服务暴露的端口。默认是 20880如果一台机器部署多个提供者端口会自增20880、20881...。生产环境建议显式指定避免端口冲突。dubbo.scan.base-packages扫描DubboService注解的包路径。不配这个注解不会被处理服务也不会暴露。我见过有人只配了注册中心忘了配scan结果启动没报错但消费者就是调不到服务。排查了半天才发现是注解没被扫描到。这个坑很隐蔽因为 Dubbo 不会主动提示你“有注解没扫描”。3.4 启动顺序与注册中心连接验证提供者启动时Dubbo 会做几件事连接注册中心、创建服务代理、把服务地址写入注册中心、启动 Netty 监听端口。如果注册中心连不上启动会失败并抛出RpcException。启动成功后你可以去 Nacos 控制台或者 ZooKeeper 客户端里验证服务是否注册成功。Nacos 的话在“服务管理-服务列表”里应该能看到你的应用名和对应的实例地址。ZooKeeper 的话用ls /dubbo/com.example.api.UserService/providers命令查看。如果注册中心里没有你的服务按这个顺序排查DubboService注解是否加在实现类上而不是接口上。dubbo.scan.base-packages是否覆盖了实现类所在的包。注册中心地址是否正确网络是否连通。是否有多个注册中心配置冲突。4. 消费者端像调用本地 Bean 一样调用远程服务4.1 DubboReference 的注入逻辑消费者端要引用远程服务只需要在字段上加DubboReference注解RestController public class UserController { DubboReference(version 1.0.0, timeout 3000) private UserService userService; GetMapping(/user/{id}) public UserDTO getUser(PathVariable Long id) { return userService.getUserById(id); } }Spring 启动时Dubbo 会为这个字段生成一个动态代理对象。当你调用userService.getUserById(id)时代理对象会拦截调用从注册中心获取提供者地址列表经过负载均衡选出一个提供者把方法名、参数类型、参数值序列化后通过网络发送过去等待响应后再反序列化返回结果。整个过程对开发者完全透明。你不需要写任何网络代码也不需要手动处理连接池。4.2 消费者配置少即是多消费者的配置比提供者更简单通常只需要应用名和注册中心地址dubbo: application: name: order-service-consumer registry: address: nacos://127.0.0.1:8848不需要配protocol因为消费者不暴露服务只发起调用。也不需要配scan因为DubboReference是在字段上Spring 处理 Bean 注入时就会处理。但有一个配置建议加上dubbo.consumer.checkfalse。默认情况下消费者启动时会检查依赖的服务是否可用如果提供者还没启动消费者会启动失败。在开发环境或者提供者启动较慢的场景下这个检查很烦人。设为false后消费者启动时不会检查调用时如果服务不可用才会报错。dubbo: consumer: check: false timeout: 5000 retries: 2check启动时是否检查服务可用性。timeout默认调用超时时间可以被DubboReference上的配置覆盖。retries失败重试次数默认是 2。注意重试只对幂等操作安全非幂等操作比如插入数据要设为 0否则可能重复插入。4.3 直连模式开发调试时的救命稻草有时候你只想本地调试不想启动注册中心或者提供者还没注册到注册中心。这时候可以用直连模式绕过注册中心直接调用指定地址DubboReference(url dubbo://127.0.0.1:20880, version 1.0.0) private UserService userService;或者在配置里全局指定dubbo: reference: url: dubbo://127.0.0.1:20880直连模式在排查“是注册中心问题还是服务本身问题”时特别有用。如果直连能调通说明服务实现没问题问题出在注册中心如果直连也调不通那就是服务本身或者网络的问题。注意直连模式只适合开发调试生产环境绝对不要用。因为直连绕过了服务发现提供者扩容或迁移后消费者无法感知。4.4 异步调用与泛化调用简介Dubbo 还支持异步调用消费者发起调用后不阻塞等待结果而是通过 Future 或者回调获取。这在批量调用或者对响应时间敏感的场景下很有用。配置方式是在DubboReference上加async true然后通过RpcContext.getContext().getFuture()获取 Future 对象。泛化调用则是消费者没有 API 接口的情况下的兜底方案。比如你做一个网关需要调用各种未知的服务不可能为每个服务都引入 API 包。这时候可以用GenericService接口传入方法名、参数类型和参数值Dubbo 会帮你完成调用。泛化调用的性能比正常调用略低因为少了编译期的类型检查但灵活性极高。这两个特性入门阶段可以先了解等有具体需求时再深入。5. 联调时最容易卡住的几个环节5.1 服务找不到从注册中心到网络的全链路排查“No provider available for the service”是 Dubbo 最常见的报错。这个报错的意思是消费者在注册中心里找不到可用的提供者。排查要按链路走不要跳步。第一步确认提供者是否真的注册成功了。去注册中心控制台看服务列表里有没有提供者的应用名实例列表里有没有具体的 IP 和端口。如果没有回到提供者端排查DubboService和scan配置。第二步确认消费者和提供者连的是同一个注册中心。这个听起来很蠢但我确实见过有人提供者连的是测试环境的 Nacos消费者连的是本地的 ZooKeeper两边完全不在一个频道上。第三步确认服务接口的全限定名、版本号、分组是否完全一致。消费者写version 1.0.0提供者写version 1.0.1或者消费者没写版本号而提供者写了都会导致找不到服务。Dubbo 的匹配是精确匹配差一个字符都不行。第四步检查网络连通性。消费者能不能 ping 通提供者的 IP提供者的端口是不是被防火墙拦了。Dubbo 默认用 20880 端口有些公司的安全策略会封禁非标准端口。5.2 序列化异常实体类没实现 Serializable 的后果这个报错信息通常是org.apache.dubbo.remoting.RemotingException: Failed to invoke the method ... cause: java.io.NotSerializableException。原因很简单传输的对象没有实现Serializable接口。Dubbo 默认用 Hessian2 序列化它要求传输的对象必须可序列化。不仅是 DTO 本身DTO 里嵌套的所有对象也都要可序列化。我遇到过有人在 DTO 里放了一个java.util.DateDate 本身是可序列化的但它的子类java.sql.Timestamp在某些序列化器下会有问题。所以 DTO 里的字段类型尽量用基本类型和 String复杂类型要确认序列化兼容性。另外如果 DTO 里有无参构造函数之外的构造函数但没有保留无参构造函数Hessian2 反序列化时也会失败。因为反序列化需要先创建实例再填充字段没有无参构造函数就没法创建。5.3 超时与重试默认参数在真实业务里的陷阱Dubbo 默认超时是 1000ms默认重试 2 次。这两个默认值在真实业务里经常出问题。先说超时。1000ms 对于简单的内存操作够用但一旦涉及数据库查询、远程缓存、第三方接口调用很容易超过。超时后消费者会抛出TimeoutException然后触发重试。如果提供者的业务逻辑已经执行了比如已经扣了库存但响应因为网络慢没及时返回重试就会导致重复扣减。再说重试。默认重试 2 次加上首次调用一共 3 次。对于查询操作重试是安全的还能提高成功率。但对于插入、更新、删除操作重试就是灾难。所以我的习惯是所有非幂等的服务在DubboService或DubboReference上显式设置retries 0。DubboService(version 1.0.0, timeout 5000, retries 0) public class OrderServiceImpl implements OrderService { // 下单逻辑绝对不能重试 }超时时间也要根据业务设置。我的经验值是数据库单表查询设 3000ms复杂查询设 5000ms调用第三方接口设 10000ms。不要全局设一个很大的值那样一旦提供者真的挂了消费者会长时间阻塞拖垮整个调用链。5.4 启动顺序导致的假死现象在微服务架构里服务之间有依赖关系。如果消费者启动时提供者还没启动消费者会报“No provider available”然后启动失败如果checktrue。但如果checkfalse消费者能启动成功但第一次调用时会失败。更隐蔽的情况是提供者启动了但还没完成服务注册消费者就开始调用了。Dubbo 的服务注册是异步的提供者启动完成后注册中心的通知可能还有延迟。如果消费者在这个窗口期发起调用就会失败。解决办法有两个一是消费者配置checkfalse并配合重试机制二是用 Dubbo 的lazy属性延迟初始化。但最根本的还是要保证启动顺序或者在网关层做健康检查等所有依赖服务都就绪后再放流量进来。6. 从能跑到好用几个值得提前知道的优化点6.1 服务分组与多版本并行当同一个接口需要同时存在多个实现时比如灰度发布场景老版本和新版本要并行运行这时候就需要用group和version来区分。// 提供者老版本 DubboService(version 1.0.0, group stable) public class UserServiceStableImpl implements UserService { } // 提供者新版本 DubboService(version 2.0.0, group gray) public class UserServiceGrayImpl implements UserService { } // 消费者指定调用灰度版本 DubboReference(version 2.0.0, group gray) private UserService userService;这样可以在不影响老用户的情况下让部分流量走新版本。等新版本验证稳定后再把所有消费者的配置切到新版本。6.2 本地伪装与容错降级Dubbo 提供了mock机制当远程调用失败时可以返回一个本地伪装的结果而不是直接抛异常。这在依赖服务不可用时能保证主流程不被阻塞。DubboReference(version 1.0.0, mock com.example.mock.UserServiceMock) private UserService userService;UserServiceMock需要实现UserService接口并提供一个无参构造函数。当远程调用失败时Dubbo 会调用 Mock 类的对应方法返回兜底数据。这个机制在秒杀、大促场景下特别有用。比如推荐服务挂了返回一个默认的热门列表总比整个页面报错要好。6.3 监控与治理的入口Dubbo 自带了一个简单的监控中心dubbo-monitor可以统计调用次数、成功率、响应时间等指标。虽然功能不如专业的 APM 系统但对于入门和中小项目来说够用了。配置方式是在提供者和消费者都加上dubbo: monitor: protocol: registry这样监控数据会通过注册中心上报。启动 dubbo-monitor 后可以在控制台看到服务的调用统计。如果公司有 Prometheus Grafana 的监控体系Dubbo 也支持通过dubbo-metrics-prometheus模块暴露指标接入现有的监控大盘。6.4 线程模型与连接数控制Dubbo 默认的线程模型是all即所有消息都派发到业务线程池。线程池默认大小是 200队列长度是 0即不排队直接拒绝。在高并发场景下这个配置可能导致请求被拒绝。如果服务大多是 CPU 密集型线程数可以设小一点比如 CPU 核数 1。如果是 IO 密集型线程数可以设大一点比如 500。队列长度建议设一个合理的值比如 1000避免瞬间流量直接打满线程池。dubbo: protocol: threads: 500 queues: 1000连接数方面Dubbo 默认是共享单一长连接。如果提供者的服务处理时间较长单一连接可能成为瓶颈。可以通过connections参数增加连接数DubboReference(connections 10) private UserService userService;但连接数不是越多越好每个连接都会占用系统资源。一般建议根据压测结果来调整不要盲目设大。7. 我踩过的三个真实坑与对应解法第一个坑是注解冲突。早期 Dubbo 用Service注解暴露服务但 Spring 也有Service。我在同一个类上同时写了两个Service结果 Spring 把它当成了普通 BeanDubbo 没识别到服务一直注册不上去。后来换成DubboService才解决。如果你用的是 Dubbo 2.7.7 之前的版本要么用 XML 配置要么确保Service的包路径是org.apache.dubbo.config.annotation.Service。第二个坑是泛型擦除导致的序列化问题。我在 DTO 里用了一个ListT字段运行时 T 被擦除成 ObjectHessian2 序列化时无法确定具体类型反序列化后变成了ListMap。消费者拿到数据后强转报ClassCastException。解决办法是 DTO 里的集合字段尽量用具体类型比如ListUserDTO而不是ListT或者用JSONField之类的注解指定类型信息。第三个坑是注册中心地址配了多个但只生效一个。我在dubbo.registry.address里写了两个地址用逗号分隔以为会同时注册到两个注册中心。实际上 Dubbo 默认只使用第一个可用的地址后面的作为备份。如果要同时注册到多个注册中心需要配置多个dubbo.registries节点并在DubboService上指定registry属性。这个细节官方文档里写得很隐蔽我是看了源码才搞明白。最后分享一个排查小技巧Dubbo 启动时会打印服务暴露和引用的日志把日志级别调到DEBUG可以看到服务注册的详细过程包括注册中心地址、服务接口、版本号、分组等信息。如果服务找不到先看这些日志比盲目猜要快得多。logging: level: org.apache.dubbo: DEBUG这个配置在开发环境建议一直开着生产环境再调回INFO。
