一、工程结构为什么要拆三个模块整个项目拆成三个 Maven 子模块由一个父 POM 聚合管理dubbo-demo父工程packagingpom ├── dubbo-api → 接口契约层 ├── dubbo-provider → 服务提供者 └── dubbo-consumer → 服务消费者父工程的职责只有两件事统一管理子模块列表modules和统一锁定依赖版本dependencyManagement。它本身不产出任何 JARpackaging必须声明为pom。dubbo-api 独立成模块是 Dubbo 微服务的核心设计思想。接口定义和传输实体单独一个工程Provider 和 Consumer 都依赖它。这样做的好处是两端通过共享契约解耦Provider 的实现细节对 Consumer 完全不可见未来如果有新的消费方只要引入这个 API JAR 就能调用服务。二、三个核心注解整个 Dubbo 集成只需要记住三个注解EnableDubbo— 贴在启动类上。它是一切的开关作用是触发 Dubbo 的自动配置扫描当前包及子包下的 Dubbo 注解。Provider 和 Consumer 的启动类上都要加。没有它DubboService和DubboReference都不会生效。DubboService— 贴在Provider 端的接口实现类上。作用是告诉 Dubbo把这个类作为服务暴露出去注册到注册中心。它可以附带多个属性最常用的是version版本号和loadbalance负载均衡建议。一个接口可以有多个实现类通过不同的version区分。DubboReference— 贴在Consumer 端的字段上。作用是告诉 Dubbo帮我生成这个接口的远程代理从注册中心找到对应的 Provider 来调用。它是 RPC 调用的入口使用体验和注入一个本地 Bean 一样——字段声明后直接调方法底层的网络通信完全透明。容易混淆的点DubboService不是 Spring 的ServiceDubboReference也不是 Spring 的Autowired。它们是 Dubbo 自己的注解走的是 Dubbo 的注册发现机制不是 Spring 容器的 Bean 注入。三、版本路由同一接口多个实现共存Dubbo 允许同一个接口在 Provider 端注册多个版本。本项目中UserService同时有 v1.0 和 v2.0 两个实现Provider 端两个实现类分别用version 1.0和version 2.0标注Consumer 端通过DubboReference(version 1.0)精确指定调哪个版本如果 Consumer 端写version *则表示我不挑版本Dubbo 会在所有可用版本中做负载均衡。实际应用场景灰度发布。新版本上线时先部署一个 v2.0 的 Provider 实例让少量流量通过version *打过去观察效果确认无误后再全量切换。四、负载均衡策略当同一个服务有多个 Provider 实例时比如部署了 3 台机器Consumer 调用时需要决定请求发给谁。Dubbo 内置了五种策略random随机默认策略适合机器性能差不多的场景roundrobin轮询请求轮流分发保证绝对均匀leastactive最少活跃数哪台机器当前处理的请求最少就调哪台适合处理耗时差异大的场景consistenthash一致性哈希相同参数的请求始终落到同一台机器适合有缓存的场景shortestresponse最短响应时间优先调用响应最快的机器配置方式是在DubboService或DubboReference中设置loadbalance属性。五、配置优先级规则很重要Dubbo 中 Provider 和 Consumer 两端都可以配置timeout、retries、loadbalance等参数但它们的优先级是不同的Consumer 端配置 Provider 端配置 Dubbo 全局默认值也就是说Provider 端在DubboService上设的loadbalance random只是一个建议值。如果 Consumer 端在DubboReference上也设了loadbalance roundrobin最终以 Consumer 为准。设计意图是服务的提供方提供推荐配置但消费方可以根据自己的业务需求覆盖。比如某个消费方对延迟特别敏感它可以单独把timeout调短而不影响其他消费方。六、两个端口别搞混Provider 启动后实际监听了两个端口Spring Boot HTTP 端口如server.port: 8081处理 HTTP 请求比如 actuator 健康检查、REST 接口等Dubbo 协议端口如dubbo.protocol.port: 20880处理 RPC 调用Consumer 通过这个端口与 Provider 通信Consumer 端只需要 HTTP 端口对外暴露 REST 接口不需要 Dubbo 协议端口所以配置为port: -1。七、注册中心的角色ZooKeeper 在整个架构中充当的是服务电话簿Provider 启动时把自己的地址、接口名、版本号等信息写入 ZK 的节点上注册Consumer 启动时到 ZK 上查询自己需要的服务有哪些可用的 Provider 地址订阅运行时如果某个 Provider 下线ZK 会通知所有订阅者更新地址列表感知变化关键配置项dubbo.consumer.check: false的含义是Consumer 启动时不强制要求 Provider 已经就位。设为true默认值时如果找不到 ProviderConsumer 启动会直接报错。开发阶段建议设为false生产环境视情况而定。八、序列化的硬性要求Dubbo RPC 调用时参数和返回值需要经过序列化对象 → 字节流通过网络传输然后在对端反序列化字节流 → 对象。因此所有在接口中出现的实体类都必须实现Serializable接口并且最好显式声明serialVersionUID。如果忘了实现Serializable运行时调用会直接抛序列化异常。这也是为什么实体类放在 dubbo-api 模块的原因之一两端必须使用完全相同的类定义否则反序列化会失败。另外 Dubbo 3.3 引入了序列化安全检查机制serialize-check-status默认会校验反序列化的类是否在信任白名单中。开发阶段设为WARN只打日志不阻断生产环境建议配置信任列表。九、Maven BOM 的管理思路父 POM 通过dependencyManagement导入了两个 BOMBill of MaterialsSpring Boot BOM锁定所有 Spring 相关依赖的版本Dubbo BOM锁定所有 Dubbo 相关依赖的版本子模块引入依赖时不需要写version标签版本号由父 POM 统一管理。这种方式的好处是避免了版本冲突也方便日后统一升级——只需改父 POM 里的一个版本号。特别注意 ZooKeeper 客户端的选择ZK 3.8 要用dubbo-zookeeper-curator5-spring-boot-starterCurator 5不要用老的不带5的 Starter否则会有兼容性问题。十、Spring Boot 3 的特殊注意点Spring Boot 3 基于 Spring Framework 6 和 Jakarta EE 9有几个容易踩的坑JDK 最低要求 17不再支持 JDK 8/11编译器必须开启-parameters选项即maven-compiler-plugin配置parameterstrue/parameters否则RequestParam、PathVariable等注解在运行时无法解析参数名会报绑定错误包名从javax.*迁移到jakarta.*如果你在项目中直接用了 Servlet API 等需要注意 import 路径的变化十一、本地存根 (Stub) 和 本地伪装 (Mock)两者代码都是在消费者这边Stub 是为了**“优化”能不能不调能不能先查缓存它是主动**的拦截器。Mock是为了**“保命”提供者挂了怎么办降级使用它是被动**的备胎。DubboReference(version 1.0, loadbalance roundrobin, stub com.example.dubbo.consumer.stub.UserServiceStub, mock com.example.dubbo.consumer.mock.UserService_mock ) private UserService userServiceAny;速记口诀API 定契约两端都依赖 Service 贴提供Reference 贴消费 EnableDubbo 是开关启动类上不能忘 版本号控灰度星号通配全都上 负载均衡五策略Consumer 说了算 实体必须序列化不然传输全白搭。