简介：OnlineTaxi 是基于 Spring Cloud 的网约车全流程实战项目，面向具备一定 Java 基础、希望学习微服务架构的开发者或相关专业学生。项目按乘客端、司机端与能力层拆分为订单、派单、乘客用户、短信、计价、验证码、钱包、支付、地图等多个服务，并整合了 Eureka 注册中心、Config 配置中心、Zuul 网关、Hystrix 熔断监控、Zipkin 链路追踪等常用组件，能帮助读者理解真实业务下的服务拆分与组件选型。资源压缩包共 1081 个文件，大小 137.48MB，包含大量 Java 源码、XML 配置、YML 配置文件以及编译后的 Class 文件，同时配有 PNG 图片与 JS 等辅助资源，目录结构清晰，便于对照学习。演示流程覆盖登录注册、验证码、司机接单、到达约定地点、接待旅客、开始行程、发起收款等关键环节，能直观掌握业务闭环。已有 2287 人学习，适合作为微服务项目实践、毕业设计或课程设计的参考资料。 手头这个OnlineTaxi网约车项目，是我最近复盘次数最多的一个Spring Cloud微服务实践。当初做它的动机很简单——市面上大多数demo项目都是"订单+用户+库存"那种三板斧，真正能把网约车这种业务跑通的却不多。网约车看着不复杂，可一旦把乘客端、司机端、派单、计价、支付、消息推送全部串起来，分布式事务、流量削峰、服务治理这些Spring Cloud的核心痛点会全暴露出来，做一遍比单纯看十遍文档都靠谱。
这篇文章我尽量按实际开发顺序来写，适合几类人看：准备做微服务选型、想找真实业务练手的后端开发；已经在用Spring Cloud但想看看网约车场景里怎么落地的同行；还有那些把黑马Spring Cloud课程刷完、急着找一个完整项目来验证所学内容的朋友。文章里不会只讲概念，我会把服务拆分思路、派单流程、缓存策略、网关集群、Feign超时陷阱这些问题全部串起来说，代码和配置都会给出可以直接用的版本。
1. 项目为什么这么设计：OnlineTaxi的整体思路与模块划分
1.1 一个网约车项目到底要拆多少个服务
很多人做微服务项目最容易犯的错，是上来就照着网上的架构图一顿拆，结果服务拆了十几个，每个服务里就两三个接口，部署和运维成本倒比单体架构高出一大截。我在一开始就定了一个原则：按业务域拆分，能合则合，能独立则独立。
OnlineTaxi最终拆成了下面这些服务：
api-gateway：统一入口，负责路由、鉴权、限流。auth-server：认证中心，负责登录、Token签发与校验。passenger-service：乘客端服务，管理乘客信息、常用地址。driver-service：司机端服务，管理司机信息、车辆信息、出车状态。order-service：订单中心，负责订单生命周期管理。dispatch-service：派单中心，负责匹配司机、推送订单、超时重派。payment-service：支付中心，负责订单计价、支付流水、对账。message-service：消息中心，负责短信、App推送、站内信。map-service：地图与路径服务，封装第三方地图API，做距离计算和路径规划。
重点说一下派单中心。派单这个动作在业务上要同时读取订单状态、司机实时位置、计价规则和当前拥堵情况，如果揉在订单服务里，后续每次调整派单策略都要改动核心订单链路，风险非常大。独立成服务后，订单服务只负责"下单—改状态—关单"，派单服务只负责"找车—推送—派单"，两边通过MQ解耦，各自演进互不干扰。
1.2 选型复盘：注册中心、网关、配置中心为什么这样选
这个项目的技术栈是Spring Cloud Alibaba全家桶：Nacos做注册中心和配置中心，Gateway做网关，OpenFeign做服务间调用，Sentinel做熔断限流，RocketMQ做消息中间件。
选Nacos而不是Eureka，原因很直接：Eureka 2.x已经停止维护，而且它只是一个注册中心，配置中心还得额外搭Spring Cloud Config。Nacos同时搞定注册发现和配置管理，控制台界面也友好，还能直接支持命名空间隔离，测试环境和生产环境用一套Nacos就能分开管理。
网关选了Spring Cloud Gateway而不是Zuul 1.x，是因为Zuul 1.x基于Servlet，本质上是同步阻塞模型，高并发场景下线程容易被IO阻塞占满。Gateway基于WebFlux，底层是Netty的异步非阻塞模型，同样配置下性能表现明显更好。而且Spring Cloud Gateway从Spring Cloud Finchley版本开始就进入了官方主推序列，后续版本迭代和生态支持都更稳。
还有朋友问为什么不直接用Dubbo。Dubbo和Spring Cloud最大的区别在于：Dubbo是一个高性能RPC框架，核心优势是二进制传输和内置服务治理，但网关、配置中心、分布式追踪这些组件并没有官方全家桶，需要自己拼装；Spring Cloud则是一整套微服务解决方案，从注册发现到网关到配置管理都有标准化的实现。网约车这种业务场景对单次RPC性能并不敏感，但对团队协作、运维监控、系统集成的标准化要求很高，所以Spring Cloud更合适。
2. 核心业务链路：订单服务如何与其他服务协作
2.1 订单主链路拆解：从乘客下单到司机接单
订单主链路是整个项目最核心的流程，我把它分成几个阶段来设计。
第一阶段，乘客创建订单。passenger-service调用order-service的/api/order/create接口，order-service校验乘客状态、用车起点终点、预估价格后写入订单表，订单状态为CREATED。
第二阶段，进入派单流程。order-service在订单落库后，不直接同步调用dispatch-service，而是发送一条OrderCreatedEvent到RocketMQ的ORDER_DISPATCH_TOPIC。这样做的原因是派单流程比较重，需要查司机位置、计算距离、推送抢单，如果全部做成同步调用，乘客在下单接口上可能等上好几秒，体验极差。
第三阶段，司机抢单。dispatch-service消费消息后，通过地理位置匹配出一批候选司机，把订单推送到司机端App。司机点击"接单"后，dispatch-service调用order-service的/api/order/grab接口，订单状态变为ACCEPTED，同时通知乘客端"司机已接单"。
第四阶段，行程与支付。司机到达上车点后开始行程，行程结束触发计费，order-service调用payment-service创建支付单，乘客完成支付后，payment-service通过消息通知order-service更新订单状态为PAID。
这里同步和异步调用的划分原则是：主链路上需要立即返回结果、且失败后必须让用户感知的操作，用Feign同步调用；不需要用户等待、允许后台慢慢处理的操作，用MQ异步解耦。比如创建订单和确认接单必须同步，否则用户不知道结果；派单通知和支付完成后的订单状态更新则完全可以异步。
下面是一个典型的Feign调用示例，order-service需要调用payment-service创建支付单：
@FeignClient(name = "payment-service", fallback = PaymentClientFallback.class) public interface PaymentClient { @PostMapping("/api/payment/create") Result<PaymentOrderVO> createPayment(@RequestBody CreatePaymentRequest request); } @Component @Slf4j public class PaymentClientFallback implements PaymentClient { @Override public Result<PaymentOrderVO> createPayment(CreatePaymentRequest request) { log.error("调用支付服务创建支付单失败，orderId：{}", request.getOrderId()); return Result.error("支付服务暂不可用，请稍重试"); } }2.2 消息驱动在网约车场景里的三个关键用处
RocketMQ在这个项目里承担了三个职责：业务解耦、流量削峰、最终一致性。
先说业务解耦。订单服务、派单服务、支付服务、消息服务之间的调用，凡是异步的都走消息。以支付成功为例，payment-service发送PaymentSuccessEvent，order-service和message-service各自消费这个消息，订单服务改状态，消息服务发推送，两边互不依赖。
再说流量削峰。早高峰和晚高峰的订单量是平峰的十几倍，如果所有请求都直接打到数据库，连接池很快就会被耗尽。我的做法是：订单创建请求先写Redis缓存，立即返回"呼叫中"状态，然后通过消息队列慢慢把订单写入数据库并由派单服务消费。消息队列本身就有削峰填谷的能力，哪怕瞬间涌入大量订单，dispatch-service也能按照自己的消费能力稳定处理。
最后是最终一致性。乘客下单后，订单状态和派单状态要保证最终一致，但不能用分布式事务硬做。这里用的是RocketMQ事务消息：order-service先发半消息，然后执行本地事务（订单落库），本地事务成功后提交半消息，dispatch-service才能看到这条订单。如果本地事务失败，半消息被回滚，dispatch-service永远收不到，这就保证了"有订单才有派单"的一致性约束。
消费端做幂等是必须的，因为RocketMQ本身不保证消息只被消费一次。我的做法是在消费逻辑里用订单号作为业务键查询一次，如果发现订单已经在派单中，直接返回消费成功，避免重复派单。
3. 高并发场景的实战处理：派单、缓存与一致性
3.1 派单服务里的延迟队列实现
网约车业务里，"超时无司机接单"是常态。乘客下单后如果5秒内没有司机抢单，系统不能干等，要把订单重新推给一批新的司机。这个"等待后重试"的需求，用RocketMQ的延迟消息最合适。
我定义了三级延迟：5秒、15秒、30秒。5秒后如果还没有司机接单，系统把订单重新放入派单队列，这次扩大范围推送；如果15秒后仍无人接单，再扩大一次范围；30秒后还没接单，则取消订单并通知乘客"暂时没有司机接单，请稍后再试"。
RocketMQ的延迟消息实现非常简单，发送时设置延迟等级即可：
Message message = new Message( "ORDER_DISPATCH_TOPIC", orderId.getBytes(StandardCharsets.UTF_8) ); // 延迟级别3表示延迟10秒，具体对应关系参考RocketMQ配置 message.setDelayTimeLevel(3); SendResult sendResult = rocketMQTemplate.getProducer().send(message);这里有一个坑：RocketMQ的延迟消息用的是固定的延迟级别，最多支持18个等级，并不支持任意秒数的延迟。所以在设计重试间隔时，一定要对照实际支持的延迟级别来选，不要想当然地写个"延迟7秒"。
3.2 缓存设计：热点订单和司机位置的Redis策略
网约车场景里，热门商圈的订单数据、司机实时位置是被查询最多的数据。如果每次都打到数据库，数据库压力会非常大。但缓存也不能乱用，我踩过几个典型问题。
第一个是缓存穿透。乘客端如果反复查询一个不存在的订单号，每次都会穿透到数据库。解决办法有两个：一是对不存在的订单也缓存一个空值，并设置较短的过期时间；二是在代码里加一个布隆过滤器，订单创建时写入过滤器，查询前先判断订单号是否存在。
第二个是缓存击穿。某个热门司机的位置key过期瞬间，大量请求同时涌到数据库。解决办法是加互斥锁，只允许一个线程去数据库查询并重建缓存，其他线程等待后直接读取新缓存。下面是加锁重建缓存的伪代码：
public DriverLocation getDriverLocation(String driverId) { String cacheKey = "driver:location:" + driverId; Object cacheValue = redisTemplate.opsForValue().get(cacheKey); if (cacheValue != null) { return (DriverLocation) cacheValue; } // 加互斥锁，只放行一个请求去查数据库 String lockKey = "driver:location:lock:" + driverId; boolean locked = redisTemplate.opsForValue() .setIfAbsent(lockKey, "1", Duration.ofSeconds(3)); if (!locked) { Thread.sleep(50); return getDriverLocation(driverId); } try { DriverLocation location = driverLocationMapper.selectById(driverId); redisTemplate.opsForValue().set(cacheKey, location, Duration.ofMinutes(10)); return location; } finally { redisTemplate.delete(lockKey); } }第三个是缓存雪崩。大量key同时过期会导致请求集中打到数据库。处理方式很简单：在设置过期时间时加入一个随机值，比如基础过期时间10分钟加随机0到120秒，避免key在同一时刻集体失效。
3.3 接口幂等与分布式事务
网约车场景里，幂等是必须处理的。乘客在弱网环境下点"呼叫"按钮可能连点三次，司机抢单时也可能因为网络抖动重复提交。我在项目里做了一个自定义注解@Idempotent，配合Redis实现接口幂等。
实现思路是：请求进入接口时生成一个幂等键（业务唯一标识），比如乘客下单用"乘客ID+时间戳+随机数"，司机接单用"司机ID+订单ID"。把幂等键存入Redis，设置一个合理的过期时间。如果Redis里已经有这个键，说明是重复请求，直接返回之前的结果；如果没有，则执行业务逻辑，处理完成后删除幂等键。
数据库层面也可以加上唯一索引做兜底，比如t_order_grab表对driver_id和order_id建立联合唯一索引，即使并发请求都通过了Redis校验，数据库的唯一索引也能拦住重复数据。
分布式事务是另一个重点。订单服务和支付服务分属两个不同数据库，支付成功后需要更新订单状态，这里不可能用强一致事务。我的方案是：payment-service先写本地支付流水表，再发事务消息；order-service消费消息更新订单状态。如果消费者一直消费失败，消息进入死信队列，通过定时任务扫描死信队列人工处理。这套方案不复杂，但能保证最终一致性，也方便排查。
4. Spring Cloud基础设施搭建要点
4.1 Spring Cloud Gateway集群部署与路由配置
热搜词里有人问"Spring Cloud Gateway能做集群吗"，答案是不仅能，而且必须能。Gateway本身是无状态的，多个Gateway实例挂到同一个负载均衡器后面就组成了集群。
我在项目里用Nginx对Gateway做负载均衡，配置类似下面这样：
upstream gateway_cluster { server 192.168.1.10:8080 weight=5; server 192.168.1.11:8080 weight=5; server 192.168.1.12:8080 weight=5; } server { listen 80; server_name api.onlinetaxi.com; location / { proxy_pass http://gateway_cluster; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }Gateway本身就是无状态的，所以多个Gateway实例之间不需要做session同步。但要注意的是，网关层的限流如果用了本地限流（比如Guava限流），那每台网关实例是独立的限流器，集群10台机器意味着限流阈值被放大了10倍。解决方案是用Redis配合Sentinel实现分布式限流，或者直接用Sentinel Dashboard配置集群流控规则。
下面是Gateway的路由配置示例，重点看StripPrefix的用法：
spring: cloud: gateway: routes: - id: order-service uri: lb://order-service predicates: - Path=/api/order/** filters: - StripPrefix=1 - id: dispatch-service uri: lb://dispatch-service predicates: - Path=/api/dispatch/** filters: - StripPrefix=1全局过滤器是网关层必须写的，我在GlobalFilter里做Token校验，校验通过后把乘客ID或司机ID放入请求头，转发给下游服务。
4.2 Feign调用的超时、熔断与降级配置
服务间调用最容易出问题的就是超时。网约车项目里，一个下单请求要经历网关、订单服务、派单服务、支付服务多个节点，任何一环超时都可能导致整个链路失败。
Feign的超时配置要分连接超时和读取超时。连接超时是指建立TCP连接的最长等待时间，读取超时是指等待对端返回数据的最长等待时间。我的配置是连接超时3秒、读取超时5秒，这样既能容忍正常的业务处理时间，又不会让线程长时间挂起。
feign: client: config: default: connectTimeout: 3000 readTimeout: 5000熔断用的是Sentinel，相比Hystrix来说，Sentinel支持动态规则配置和实时监控控制台，不需要重启应用就能调整规则。在Feign接口上加上@SentinelResource并指定fallback方法：
@SentinelResource( value = "order-service#createOrder", fallback = "createOrderFallback", blockHandler = "createOrderBlock" ) public Result<OrderVO> createOrder(CreateOrderRequest request) { return orderFeignClient.createOrder(request); }Sentinel规则建议通过控制台动态推送，不要写死在代码里。早期版本我试过直接在代码里加载规则，后面加了新接口想调阈值，每次都要重新发布，太痛苦了。换成nacos数据源之后，规则改完秒级生效，运维效率提升很明显。
4.3 配置中心的动态刷新实践
Nacos做配置中心的一个好处是支持配置动态刷新。我在bootstrap.yml里配置了Nacos地址，把数据库连接池参数、业务开关、推送文案这些高频变更的配置都放到Nacos配置中心。
需要动态刷新的Bean加上@RefreshScope注解：
@RefreshScope @Component @ConfigurationProperties(prefix = "order.business") public class OrderBusinessConfig { private Integer dispatchTimeoutSeconds; private Integer cancelOrderMinutes; // getter and setter }这个功能用好了非常舒服，比如线上突然要调整派单超时时间，直接在Nacos控制台改配置发布，不需要重启服务就能生效。
但这里要注意两个坑：第一，@RefreshScope会和@Scheduled冲突，如果同一个类里既有定时任务又要动态刷新配置，定时任务的cron表达式不会随配置刷新而更新；第二，配置刷新会触发Bean重新创建，如果有初始化资源（比如连接池、线程池）在@PostConstruct里创建，刷新后可能重复创建导致资源泄漏。我的经验是，动态刷新只用于简单属性，复杂的初始化逻辑还是老老实实重启。
5. 常见问题与排查技巧实录
5.1 服务注册了但调不通：Nacos实例IP的坑
这个坑我印象太深了。当时部署了两台order-service，Nacos控制台显示两个实例都健康，但passenger-service调用时偶尔报连接拒绝。查了半天，发现问题出在实例IP注册。
服务器有多块网卡时，Nacos客户端默认拿到的IP可能是内网Docker网桥IP，这个IP只能本机访问，其他机器当然连不上。解决办法是在application.yml里显式指定注册IP：
spring: cloud: nacos: discovery: # 指定为服务器对外提供服务的网卡IP ip: 192.168.1.20 # 指定使用哪块网卡 network-interface: eth0同样的问题在Docker部署时也很常见，容器内的IP是动态的，注册到Nacos的IP对宿主机外的服务不可达。建议在容器启动时通过环境变量注入宿主机IP，然后手动指定spring.cloud.nacos.discovery.ip。
5.2 Feign超时引发重复下单事故
这是我线上遇到的最严重的一次问题。乘客端因为网络波动，请求在网关层超时后重试，结果订单服务里出现了两条一模一样的订单。
排查下来有两个原因：一是Feign的读取超时设置太短，订单服务的创建订单逻辑包含了距离计算和计价，正常需要2秒，我把读取超时设成了1秒，导致大量正常请求被判超时；二是网关层开启了重试机制，请求超时后自动重新转发。
这个问题的处理分两步：第一步，把Feign读取超时调整到合理值，并给订单创建接口加幂等键；第二步，在网关的路由过滤器里关闭对幂等敏感接口的重试，只允许对GET请求重试。
spring: cloud: gateway: routes: - id: order-service uri: lb://order-service predicates: - Path=/api/order/** filters: - name: Retry args: retries: 0隐患排查的通用思路是：服务间调用必须默认加超时时间，重试只加到幂等的接口上，否则宁可失败也不要重试。
5.3 分布式事务消息丢失的排查记录
另一个典型问题是订单创建了但一直停在"等待派单"状态。初步判断是OrderCreatedEvent消息丢了，但RocketMQ一般不会无故丢消息，仔细排查下来发现，问题出在事务消息的回查接口上。
RocketMQ事务消息的流程是：先发半消息，然后执行本地事务，再提交或回滚半消息。如果第一步发送成功了，但第二步提交半消息时网络超时，RocketMQ会反向回查本地事务状态。我当时的回查接口直接返回了UNKNOWN，导致RocketMQ无法确认这个半消息是提交还是回滚，多次回查无果后消息就被丢弃了。
正确的回查逻辑应该是根据本地事务表反查真实状态：如果订单表中存在这条订单，返回COMMIT；如果不存在，返回ROLLBACK。排查到最后，是代码里回查时查错了表，查了缓存没查数据库。
最终的兜底方案是加一个定时巡检任务，每隔5分钟扫描一次订单表里状态为CREATED且创建时间超过5分钟的订单，如果发现异常就重新发送派单消息。定时任务兜底虽然不优雅，但在分布式场景里非常实用，能解决绝大部分消息丢失的边界问题。
5.4 常见问题排查速查表
整理一份排查清单，方便大家直接参考：
| 症状 | 根因 | 解决措施 |
|---|---|---|
| 服务A调服务B报连接拒绝 | Nacos实例IP错误 | 显式指定spring.cloud.nacos.discovery.ip |
| 网关重试导致重复下单 | 非幂等接口开启了Retry | 关闭写接口的重试，接口加幂等键 |
| 订单创建但一直等待派单 | 事务消息回查逻辑错误 | 回查本地事务表，增加定时巡检兜底 |
| 服务重启后配置丢失 | 配置中心未配置命名空间 | 按环境配置spring.cloud.nacos.config.namespace |
| Sentinel规则不生效 | 使用了本地加载而非动态推送 | 改成nacos数据源推送规则 |
| 消息重复消费 | 消费者未做幂等 | 使用业务主键查询去重，再做数据处理 |
最后说一点我个人的体会。做OnlineTaxi这个项目最花时间的，其实不是写代码，而是反复调各种"看似正常但实际有问题"的配置。微服务架构的难点不在某个单一服务，而在于服务之间的协作和边界。每次踩坑，本质上都是在加深对分布式系统底层逻辑的理解——超时、重试、幂等、一致性，这些东西光看书很难有切身体会，真的做一遍项目才能感受到它们的分量。如果你也在做类似的网约车项目，建议先从订单主链路跑通，再逐步加入派单、支付、消息这些复杂度，迭代着来，比一次性搭完整个系统要靠谱得多。
本文还有配套的精品资源，点击获取
