尧图网页设计 
1. 内容整体设计与思路拆解Spring Boot 3.x 出来这么久我发现很多人的项目还停在 2.x 的老写法上。javax 换 jakarta 这些表面改动不说Spring Security 6、虚拟线程、GraalVM 原生镜像这些新东西配合订单这类典型业务系统踩坑的地方一抓一大把。这篇博文我直接用订单项目当靶子从搭建骨架、拆解状态机、编写核心接口一路走到集成缓存和日志把 Spring Boot 3.x 实战里那些绕不开的坎一个个过一遍。适合正在做订单、商城、预约这类业务系统的开发者也适合刚接触 3.x 想快速上手的同学。1.1 订单系统为什么是练手 Spring Boot 3.x 的最佳靶子先说说我为什么选订单项目而不是做个简单的 CRUD 案例。订单系统的核心特征是状态多、金额敏感、并发压力大、对数据一致性要求高它天然能覆盖 Spring Boot 3.x 的大部分关键知识点。一个完整的订单模块至少涉及这几块RESTful API 接口设计、Spring Data JPA 或 MyBatis 的持久层操作、数据库事务与乐观锁、Redis 缓存、分布式锁、Bean 生命周期管理、参数校验、全局异常处理。这还没算上订单超时关单、支付回调幂等、库存扣减这类进阶场景。你把这些东西走一遍基本就把 Spring Boot 3.x 在业务系统里的主力玩法摸清了。校园讲座预约、办公用品申领、餐饮点单这些系统本质也都是订单状态机加库存资源控制骨架完全通用。Spring Boot 3.x 和 2.x 最大的区别在于底层基线的整体升级。3.x 强制要求 Java 17 起步整个 Spring 框架迁移到了 Jakarta EE 9 命名空间这意味着你过去写的javax.persistence.*、javax.validation.*这类包名全部要改成jakarta.*。同时 Spring Security 6、Spring Data、Spring Cloud 的配套版本也跟着大版本换代配置文件里的很多属性路径都发生了变化。这些升级对老项目来说是一次需要正视的迁移但对新项目来说直接建立在 3.x 之上反而是顺势而为。1.2 技术选型为什么是这组搭配而不是别家我先给出一份实际项目里的技术栈参考大家可以根据自己的场景替换组件。组件推荐方案选型说明开发框架Spring Boot 3.2.x / 3.5.x3.2 是当前最稳的版本线3.5 对 Java 21 虚拟线程优化更完善JDKJava 17 / Java 2117 是起步要求21 可开启虚拟线程两者 LTS 都安全持久层Spring Data JPA QueryDSL订单查询条件多、动态组合强QueryDSL 的类型安全查询很好用数据库MySQL 8.0主流稳定事务支持完善适合订单这种强一致场景缓存Caffeine RedisCaffeine 做本地热点缓存Redis 做分布式缓存和锁接口文档springdoc-openapi 2.x3.x 对应版本 2.x自动生成 OpenAPI 3 文档参数校验Jakarta Validation通用 Bean Validation配合全局异常处理日志Logback MDCLogback 是 Boot 默认MDC 用来关联 TraceId持久层这块我特意多说两句。很多人纠结 JPA 还是 MyBatis其实两个都能用关键在于匹配场景。订单系统查询条件多比如按用户查、按时间范围查、按状态过滤、按订单号模糊搜JPA 的JpaSpecificationExecutor或 QueryDSL 能优雅地组合这些条件还天然带一级缓存和懒加载机制。MyBatis-Plus 的优势是简单直接但动态 SQL 写多了以后容易变成一坨 XML维护成本会慢慢上来。我的实际推荐是新项目且团队习惯面向对象建模选 JPA 加 QueryDSL老团队本身熟悉 MyBatis 且业务以复杂报表 SQL 为主用 MyBatis-Plus 也没问题。Spring Boot 3.x 还有个容易被忽略的点循环依赖的默认禁止策略。2.x 时代 Spring 还能自动解决 setter 循环依赖3.x 直接默认关闭启动就报错。这意味着从设计层面就要尽量避免A 依赖 B、B 又依赖 A的结构方法就是多用构造器注入配合Lazy解决个别场景后面我会专门展开讲。2. 数据模型与状态流转订单系统的地基工程很多新人上手做订单系统第一步就建表这没错但容易忽略状态流转的设计。表结构是静态的订单状态是动态的二者必须同时考虑。我的习惯是先把状态机画清楚再回头设计字段这样表结构里的状态字段、版本号字段、时间字段才会有明确的业务含义。2.1 订单主表与明细表的核心设计订单系统至少需要两张核心表订单主表和订单明细表。主表记录一笔订单的整体信息明细表记录该订单下具体买了哪些商品、数量多少、单价多少。为什么要拆两张表原因很简单订单主表会被高频更新比如支付回调要改支付状态、发货要改物流单号如果把商品明细也塞在主表里每次更新都会牵动明细数据并发和锁的粒度就变粗了。我提供一个可以直接用的建表 SQL大家根据各自业务增减字段。CREATE TABLE t_order ( id bigint NOT NULL AUTO_INCREMENT COMMENT 主键, order_no varchar(32) NOT NULL COMMENT 业务订单号, user_id bigint NOT NULL COMMENT 下单用户ID, total_amount decimal(10,2) NOT NULL COMMENT 订单总金额, pay_amount decimal(10,2) NOT NULL DEFAULT 0.00 COMMENT 实付金额, status tinyint NOT NULL DEFAULT 0 COMMENT 订单状态: 0待支付 1已支付 2已发货 3已完成 4已取消, receiver_name varchar(64) DEFAULT NULL COMMENT 收货人, receiver_phone varchar(20) DEFAULT NULL COMMENT 收货电话, receiver_address varchar(255) DEFAULT NULL COMMENT 收货地址, remark varchar(500) DEFAULT NULL COMMENT 订单备注, version int NOT NULL DEFAULT 0 COMMENT 乐观锁版本号, create_time datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT 创建时间, update_time datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 更新时间, PRIMARY KEY (id), UNIQUE KEY uk_order_no (order_no), KEY idx_user_create (user_id, create_time) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT订单主表; CREATE TABLE t_order_item ( id bigint NOT NULL AUTO_INCREMENT COMMENT 主键, order_id bigint NOT NULL COMMENT 订单主表ID, product_id bigint NOT NULL COMMENT 商品ID, product_name varchar(255) NOT NULL COMMENT 商品名称快照, product_price decimal(10,2) NOT NULL COMMENT 商品单价快照, quantity int NOT NULL COMMENT 购买数量, subtotal_amount decimal(10,2) NOT NULL COMMENT 小计金额, create_time datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY idx_order_id (order_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT订单明细表;这里有两个容易踩的坑我重点说一下。第一金额字段必须用decimal(10,2)绝对不能图省事用float或double。二进制浮点数表示十进制的 0.1 时存在精度误差金额计算用浮点类型累计下来差一分钱是常有的事。涉及金额的加减乘除要么在数据库层面用decimal计算要么在 Java 端用BigDecimal二选一但不要混着来。第二为什么主键之外还要单独建order_no业务订单号因为自增主键虽然性能好但会把业务量暴露给外部而且分布式环境下多个服务同时生成订单靠数据库自增无法保证全局唯一。实际项目里我一般用雪花算法生成订单号格式可能是${前缀}${时间戳}${机器ID}${序列号}这样既保证唯一性也能从订单号直接读出大致下单时间。2.2 订单状态机用枚举把流转规则锁死订单系统的灵魂是状态机不是 CRUD。一笔订单从创建到完结合法状态流转必须严格限制否则就会出现已取消的订单还能支付成功这种搞笑的 bug。我建议把状态和允许的流转动作封装进枚举里让非法流转在编译期就能被约束。public enum OrderStatus { PENDING_PAYMENT(0, 待支付), PAID(1, 已支付), SHIPPED(2, 已发货), COMPLETED(3, 已完成), CANCELED(4, 已取消); private final int code; private final String desc; OrderStatus(int code, String desc) { this.code code; this.desc desc; } public int getCode() { return code; } public String getDesc() { return desc; } public static OrderStatus fromCode(int code) { for (OrderStatus status : values()) { if (status.code code) { return status; } } throw new IllegalArgumentException(未知订单状态: code); } public boolean canTransitionTo(OrderStatus target) { return switch (this) { case PENDING_PAYMENT - target PAID || target CANCELED; case PAID - target SHIPPED || target CANCELED; case SHIPPED - target COMPLETED; case COMPLETED, CANCELED - false; }; } }用 Java 21 的switch表达式来定义状态流转规则代码清晰而且写错了编译直接报错。实际切换状态时先查出当前订单状态校验canTransitionTo通过之后再更新而更新语句里必须带上状态条件确保并发情况下状态被其他线程改掉了也不会误更新。这里最典型的案例是重复支付回调。用户支付成功后支付平台会异步通知你的后端但通知可能因为网络原因发送多次甚至出现极端情况下用户已经取消订单但支付回调还是到了。如果回调处理逻辑不做状态校验直接把一笔已取消的订单改成已支付后面发货环节就会闹出大问题。正确做法是更新语句写成UPDATE t_order SET status 1 WHERE id ? AND status 0影响行数为 0 说明状态已经被改过直接忽略这次回调。2.3 幂等设计和并发扣库存的钱与货安全订单系统里最需要小心的两个并发问题是重复下单和超卖扣库存。这两类问题的解法不太一样我分开讲。重复下单的防线在入口。前端在提交订单时生成一个全局唯一的requestIdUUID 就行后端接单后把它作为幂等键存到 Redis 里SETNX requestId 1返回成功才继续处理返回失败说明这单已经处理过了直接返回重复请求。注意SETNX要配合过期时间一起用防止业务处理过程中宕机导致幂等键永远占着。扣库存的超卖问题最朴素的方案是数据库层面的条件更新加乐观锁。Modifying Query(UPDATE Product p SET p.stock p.stock - :quantity, p.version p.version 1 WHERE p.id :productId AND p.stock :quantity AND p.version :version) int deductStock(Param(productId) Long productId, Param(quantity) Integer quantity, Param(version) Long version);WHERE p.stock :quantity保证了库存不会被扣成负数影响行数为 0 说明库存不足或版本号冲突业务层需要重试或直接提示用户。我在实际项目中见过不少团队用 Redisson 分布式锁把整个下单流程锁起来库存问题解决了但下单接口的吞吐量被锁给拖垮了。我的习惯是库存扣减这种单行更新的场景优先用数据库条件更新分布式锁留给跨资源协调的场景比如同时操作多个商品的库存和账户余额。事务的粒度也要控制好。订单创建、明细插入、库存扣减这三个动作要么全成功要么全失败所以要在 Service 方法上标注Transactional。但事务方法里不要塞远程调用、发送消息这类外部操作因为外部操作不受本地事务控制一旦失败回滚消息可能已经发出去了会出现数据不一致。我的做法是事务内只做数据库写操作事务提交之后再通过ApplicationEventPublisher发布领域事件由监听器去发消息或通知。3. 核心功能实现从建项目到跑通下单流程设计做完开始动手。这一部分我把从零到接口跑通的全过程拆开来讲每一步都给出能直接落地的方案。3.1 用 Spring Initializr 快速搭建 3.x 项目骨架你可能习惯了在 IDEA 里新建项目其实用 start.spring.io 更直观也可以直接在 IDEA 的 Spring Initializr 向导里操作。选择的关键参数如下ProjectMavenLanguageJavaSpring Boot3.2.x 或 3.5.x推荐 3.2 求稳3.5 尝鲜Groupcom.exampleArtifactorder-servicePackagingJarJava17 或 21DependenciesSpring Web、Spring Data JPA、Validation、Redis、Lombok生成项目后解压导入pom.xml里会自动带上核心依赖。我自己还会补上几个 3.x 项目里很常用的依赖给大家一个参考dependency groupIdcom.querydsl/groupId artifactIdquerydsl-jpa/artifactId version5.1.0/version /dependency dependency groupIdcom.querydsl/groupId artifactIdquerydsl-apt/artifactId version5.1.0/version scopeprovided/scope /dependency dependency groupIdcom.github.ben-manes.caffeine/groupId artifactIdcaffeine/artifactId /dependency dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.6.0/version /dependencyapplication.yml的配置也顺手给出几个容易配置错的点我会在旁边注释server: port: 8080 spring: application: name: order-service datasource: url: jdbc:mysql://localhost:3306/order_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: root hikari: maximum-pool-size: 20 minimum-idle: 5 jpa: hibernate: ddl-auto: none show-sql: true open-in-view: false data: redis: host: localhost port: 6379 database: 0 threads: virtual: enabled: true springdoc: swagger-ui: path: /swagger-ui.html logging: level: com.example.order: debug注意 3.x 里 Redis 配置的前缀从 2.x 的spring.redis改成了spring.data.redis如果你把老项目的配置直接搬过来启动时会发现 Redis 连接配置竟然完全没生效这个坑我在第 4 部分还会专门提。JPA 的open-in-view我建议显式设为false虽然 Spring Boot 默认是true但它在 Controller 层保持数据库连接的方式容易掩盖懒加载异常也会撑满连接池生产环境这样配置是有风险的。3.2 订单核心接口与业务逻辑落地项目骨架建好后我们开始写代码。我习惯按Controller 层接收参数、Service 层做业务逻辑、Repository 层操作数据库的分层方式来组织这也是最不容易出错、最适合团队协作的结构。先看 Controller 层的实现。订单模块对外主要暴露这几个接口创建订单、订单详情查询、订单列表查询、支付订单、取消订单。RestController RequestMapping(/api/orders) public class OrderController { private final OrderService orderService; public OrderController(OrderService orderService) { this.orderService orderService; } PostMapping public ResponseEntityOrderVO createOrder(Valid RequestBody CreateOrderRequest request) { return ResponseEntity.status(HttpStatus.CREATED) .body(orderService.createOrder(request)); } GetMapping(/{orderNo}) public ResponseEntityOrderVO getOrder(PathVariable String orderNo) { return ResponseEntity.ok(orderService.getOrderByOrderNo(orderNo)); } GetMapping public ResponseEntityPageResultOrderVO listOrders(OrderQuery query) { return ResponseEntity.ok(orderService.listOrders(query)); } PostMapping(/{orderNo}/pay) public ResponseEntityVoid payOrder(PathVariable String orderNo) { orderService.payOrder(orderNo); return ResponseEntity.noContent().build(); } PostMapping(/{orderNo}/cancel) public ResponseEntityVoid cancelOrder(PathVariable String orderNo) { orderService.cancelOrder(orderNo); return ResponseEntity.noContent().build(); } }注意我全部使用了构造器注入这在 Spring Boot 3.x 里是官方推荐的方式。字段上加Autowired虽然在 Boot 3 里还能用但在 IDEA 里会看到警告而且构造器注入能保证依赖不可变配合 3.x 默认禁止循环依赖的策略项目结构会健康很多。Service 层是业务逻辑的重心以创建订单为例整个流程的代码骨架是这样的Service public class OrderService { private final OrderRepository orderRepository; private final OrderItemRepository orderItemRepository; private final ProductRepository productRepository; private final OrderNoGenerator orderNoGenerator; public OrderService(OrderRepository orderRepository, OrderItemRepository orderItemRepository, ProductRepository productRepository, OrderNoGenerator orderNoGenerator) { this.orderRepository orderRepository; this.orderItemRepository orderItemRepository; this.productRepository productRepository; this.orderNoGenerator orderNoGenerator; } Transactional public OrderVO createOrder(CreateOrderRequest request) { // 1. 校验幂等键 // 2. 生成订单号 String orderNo orderNoGenerator.generate(); // 3. 计算订单金额 ListOrderItem items request.getItems().stream() .map(item - createOrderItem(item)) .toList(); BigDecimal totalAmount items.stream() .map(OrderItem::getSubtotalAmount) .reduce(BigDecimal.ZERO, BigDecimal::add); // 4. 扣减库存 items.forEach(item - productRepository.deductStock( item.getProductId(), item.getQuantity(), productRepository.findById(item.getProductId()).get().getVersion())); // 5. 保存订单和明细 Order order new Order(); order.setOrderNo(orderNo); order.setUserId(request.getUserId()); order.setTotalAmount(totalAmount); order.setStatus(OrderStatus.PENDING_PAYMENT); orderRepository.save(order); items.forEach(item - item.setOrderId(order.getId())); orderItemRepository.saveAll(items); return OrderVO.from(order, items); } }这里我刻意把扣减库存的版本号查询简化了真正生产环境不会先查一次再带进去而是直接用条件更新返回的影响行数来判断。简化是为了让大家看清流程实际写的时候要注意Product实体的version字段上要加Version注解JPA 会在更新时自动带上版本号做乐观锁校验不需要手写WHERE version ?。不过对于UPDATE ... SET stock stock - ? WHERE stock ?这种场景JPA 的Version还不够还是得用Modifying自定义更新语句两者结合使用才能既防超卖又防更新丢失。Repository 层的实现里条件查询比较能体现 Spring Data JPA 的优势。订单查询通常要支持按用户、按状态、按时间范围、按订单号模糊等组合过滤我推荐用 QueryDSL它的查询写法是类型安全的编译期就能发现字段拼写的低级错误。public class OrderRepositoryCustomImpl implements OrderRepositoryCustom { private final JPAQueryFactory queryFactory; public OrderRepositoryCustomImpl(JPAQueryFactory queryFactory) { this.queryFactory queryFactory; } Override public PageOrder searchOrders(OrderQuery query, Pageable pageable) { QOrder order QOrder.order; var predicate new BooleanBuilder(); if (StringUtils.hasText(query.getOrderNo())) { predicate.and(order.orderNo.contains(query.getOrderNo())); } if (query.getStatus() ! null) { predicate.and(order.status.eq(query.getStatus())); } if (query.getUserId() ! null) { predicate.and(order.userId.eq(query.getUserId())); } ListOrder content queryFactory.selectFrom(order) .where(predicate) .offset(pageable.getOffset()) .limit(pageable.getPageSize()) .orderBy(order.createTime.desc()) .fetch(); long total queryFactory.select(order.countFrom(order)) .from(order) .where(predicate) .fetchOne(); return new PageImpl(content, pageable, total); } }使用 QueryDSL 需要配置一个JPAQueryFactory的 Bean并且让自定义接口和实现类名遵循Repository Custom的命名规范Spring Data JPA 会自动把它合并到主 Repository 里。这个方案在订单列表这种动态查询场景里比 JPA 自带的Specification更顺手也比拼接 SQL 字符串安全得多。3.3 缓存、日志与虚拟线程的实战配置业务接口跑通之后接下来要做的是让系统更健壮、更高效。这一节我挑三个实际项目中必然会用到的能力来展开Caffeine 本地缓存、Logback 日志与 MDC 链路追踪、Java 21 虚拟线程。Caffeine 和 Spring Cache 的整合在 Boot 3 里很简单先定义一个CacheManagerConfiguration public class CacheConfig { Bean public CacheManager cacheManager() { CaffeineCacheManager cacheManager new CaffeineCacheManager(order, product); cacheManager.setCaffeine(Caffeine.newBuilder() .maximumSize(500) .expireAfterWrite(Duration.ofMinutes(10)) .recordStats()); cacheManager.setAllowNullValues(false); return cacheManager; } }订单详情这种读多写少的接口很适合用Cacheable做缓存Service public class OrderQueryService { Cacheable(cacheNames order, key #orderNo, unless #result null) public OrderVO getOrderByOrderNo(String orderNo) { return loadOrderFromDb(orderNo); } }但要注意一点不能把缓存用在状态频繁变更的接口上。比如订单支付成功后状态会改变如果缓存了旧的待支付状态用户刷新页面看到的订单还是待支付就会造成业务混乱。我的经验是缓存只用于订单创建后短时间内不会变化的展示数据而支付、取消这样涉及状态变更的操作要么不走缓存要么在更新数据库后显式调用CacheEvict清掉对应缓存。日志方面Spring Boot 3.x 默认使用 Logback支持直接写logback-spring.xml放在src/main/resources下。我通常在日志配置里加入 TraceId 的生成和传递逻辑一次请求无论是 Controller 层、Service 层还是调用外部接口所有日志都能通过同一个 TraceId 串联起来排查问题的时候特别管用。configuration appender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - [%X{traceId}] %msg%n/pattern /encoder /appender appender nameASYNC_FILE classch.qos.logback.classic.AsyncAppender appender-ref refFILE / queueSize512/queueSize discardingThreshold0/discardingThreshold /appender root levelINFO appender-ref refCONSOLE / appender-ref refASYNC_FILE / /root /configurationMDC 的traceId需要在请求入口处生成并放入。最直接的方式是注册一个HandlerInterceptor在preHandle里放入MDC.put(traceId, UUID.randomUUID().toString())在afterCompletion里MDC.remove(traceId)。这样同一个请求的所有日志就都能带上同一个traceId包括异步线程池的逻辑但要注意异步线程默认不会继承父线程的 MDC 上下文需要额外处理后面我会在常见问题部分展开。虚拟线程是 Java 21 带来的一个重要特性Spring Boot 3.2 及以上版本可以直接开启spring: threads: virtual: enabled: true开启之后Tomcat 会把每个 HTTP 请求承载在虚拟线程上执行而不是传统的平台线程。虚拟线程的调度完全由 JVM 负责阻塞 IO 操作时它会自动让出底层载体线程所以在高并发 IO 密集场景下系统的吞吐量提升非常可观。我实测过订单列表接口在同样的压力下开启虚拟线程后线程数从 200 个平台线程缩减到几十个虚拟线程同时并发处理能力还更稳了。不过要注意虚拟线程并不适合 CPU 密集的计算任务而且代码里如果用到synchronized或者ThreadLocal需要仔细检查是否会有阻塞或上下文丢失的问题。4. 常见问题与排查技巧实录这一节我把实际开发和升级过程中遇到的高频问题整理成一份速查表每个问题都给出现象、原因和解决思路。4.1 从 2.x 升级到 3.x 的配置迁移清单很多人拿着 2.x 的项目升级到 3.x启动直接报错原因基本都是这几个问题现象原因解决方法编译报错javax.servlet不存在3.x 迁移到 Jakarta EE 9全局替换javax.*为jakarta.*Redis 配置不生效属性前缀改变spring.redis改为spring.data.redis懒加载报错LazyInitializationException循环依赖默认被禁构造函数设计避免循环依赖必要时LazyWebSecurityConfigurerAdapter不存在Spring Security 6 大改改为SecurityFilterChainBean 模式关于安全相关的配置迁移我用一个实际例子说明。2.x 时代我们都是继承WebSecurityConfigurerAdapter重写configure方法来定义授权规则3.x 直接废弃了这个类正确姿势是通过SecurityFilterChainBean 来声明Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .csrf(AbstractHttpConfigurer::disable) .sessionManagement(session - session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) .authorizeHttpRequests(auth - auth .requestMatchers(/api/orders/**).authenticated() .anyRequest().permitAll() ); return http.build(); }这里顺带说一下很多博主喜欢贴密码加密、Token 认证那套完整配置但订单系统实战里安全体系往往是和公司统一的认证中心对接的单体项目直接集成 Spring Security 做 JWT 的场景反而不多。你需要的是掌握配置模型的写法而不是把一套完整的认证代码背下来。4.2 依赖版本对应与 Bean 注入疑难点Spring Boot 3.x 的生态里很多第三方库的版本必须跟着 Boot 版本走版本错配是启动失败的常见原因。我整理了一份实际使用过的版本对应关系组件Spring Boot 3.2.xSpring Boot 3.5.xJDK 基线1717 或 21QueryDSL5.1.05.1.0OpenFeign4.x4.xspringdoc-openapi2.3.x2.6.xSpring Cloud2023.0.x2026.0.xspring-boot-starter-data-redis3.2.x 内置3.5.x 内置这里的io.github.openfeign.querydsl其实是一个在 Feign 场景下做查询拦截的扩展库它和 Spring Boot 的版本对应关系本质上由 Spring Cloud OpenFeign 模块决定。我的经验是如果你不确定版本最简单的方式是不要手动写版本号直接用spring-boot-dependenciesBOM 管理的传递依赖第三方库只保留自己的版本号这样能最大程度避免版本冲突。Bean 注入的疑难点主要集中在一个问题上同类型多个 Bean 时怎么选。比如项目里有OrderService和OrderQueryService你注入OrderService时 Spring 可能找到两个候选此时可以用Qualifier指定名字或者用Primary标记默认优先的 Bean。我在 Boot 3 项目里的建议是优先用构造器注入配合Qualifier尽量避免字段注入因为字段注入在单元测试时替换 Mock 对象很麻烦而且隐藏了依赖关系。还有一个高频问题java.util.concurrent.ThreadLocal和虚拟线程的冲突。虚拟线程数量不受线程池限制如果代码里用ThreadLocal存储用户信息由于虚拟线程会被复用ThreadLocal的值可能会泄漏到下一个请求。Spring Boot 3.2 提供了方案使用io.netty.util.concurrent.FastThreadLocal或者干脆在过滤器中每次清理ThreadLocal。我在订单模块里就用了一个简单的HandlerInterceptor在afterCompletion中统一清理避免脏数据串号。最后一个常见但很隐蔽的问题Transactional自调用失效。同一个类里一个方法调用另一个标注了Transactional的方法事务是不会生效的因为 Spring 的事务代理只在外部调用时才起作用。这个坑几乎每个人都会踩排查思路是createOrder调本类的deductStock方法即使deductStock标了Transactional事务也不会开启。解决办法有两个要么把需要事务的方法拆到独立的Service类中要么通过AopContext.currentProxy()获取代理对象再调用但后者代码可读性差不太推荐。实际运行中的性能调优与后续扩展订单系统跑通之后我一般会继续做两件事性能调优和架构演进。这里分享一些实测数据和个人经验供大家参考。先聊性能调优。以订单创建接口为例瓶颈往往不在计算而在数据库的写入放大效应。每笔订单要插入主表一条、明细表 N 条还要更新商品库存对 MySQL 来说就是至少 1 N N 次写操作。我的优化思路是把明细表的批量插入合并成一条 SQL用saveAllAndFlush或者 JDBC 的rewriteBatchedStatementstrue参数实测在 MySQL 8 下批量插入性能能提升一个数量级。库存扣减则尽量合并到事务的最后执行缩短事务持有锁的时间。另一个实测有效的优化点是热点数据的本地缓存。Caffeine 作为进程内缓存查询订单详情和商品信息命中率极高压测时 QPS 从 800 提升到 2200而且 Redis 的访问量也降下去了。但要注意缓存一致性问题我在订单状态变更后调cacheManager.getCache(order).evict(orderNo)保证用户下单后立刻能看到最新状态这才符合业务预期。架构演进方面如果订单量持续上涨单库单表迟早会成为瓶颈。我自己的演进路径是先引入消息队列把支付回调、订单超时关单等异步事件解耦再按用户维度做分库分表最后才是微服务拆分。微服务拆分要谨慎订单服务、商品服务、支付服务三个模块之间的调用链路一旦拉长一致性保障的复杂度会成倍增加。Spring Boot 3.x 配合 Spring Cloud 的 OpenFeign 做服务间调用很顺手但分布式事务这块能规避就要规避别一上来就上 Seata大多数场景通过状态机加重试就能解决。关于虚拟线程我再说点实际体会。Spring Boot 3.5 加上 Java 21 的虚拟线程对订单这种 IO 密集型的业务非常友好但代码里如果有自旋锁、synchronized修饰的静态方法、或者依赖线程池隔离的场景需要重新评估。我的做法是新项目直接开虚拟线程老项目先做压测对比再决定是否切换。最后日志切面在订单系统里非常值得投入。我写了一个简单的Around切面自动记录每个订单接口的入参、出参、耗时和异常信息配合 MDC 的 traceId排查线上问题时效率提升非常明显。这是所有订单项目必做的一项工程代码量很小收效却是实打实的。我个人在实际项目中最深的体会是状态机设计得足够严谨订单系统的绝大多数问题都能在写代码之前被挡掉。数据模型先行、状态流转锁定、并发边界想清楚剩下的编码只是把这些设计翻译成实现罢了。 Spring Boot 3.x订单系统实战：状态机、虚拟线程与升级迁移
1. 内容整体设计与思路拆解Spring Boot 3.x 出来这么久我发现很多人的项目还停在 2.x 的老写法上。javax 换 jakarta 这些表面改动不说Spring Security 6、虚拟线程、GraalVM 原生镜像这些新东西配合订单这类典型业务系统踩坑的地方一抓一大把。这篇博文我直接用订单项目当靶子从搭建骨架、拆解状态机、编写核心接口一路走到集成缓存和日志把 Spring Boot 3.x 实战里那些绕不开的坎一个个过一遍。适合正在做订单、商城、预约这类业务系统的开发者也适合刚接触 3.x 想快速上手的同学。1.1 订单系统为什么是练手 Spring Boot 3.x 的最佳靶子先说说我为什么选订单项目而不是做个简单的 CRUD 案例。订单系统的核心特征是状态多、金额敏感、并发压力大、对数据一致性要求高它天然能覆盖 Spring Boot 3.x 的大部分关键知识点。一个完整的订单模块至少涉及这几块RESTful API 接口设计、Spring Data JPA 或 MyBatis 的持久层操作、数据库事务与乐观锁、Redis 缓存、分布式锁、Bean 生命周期管理、参数校验、全局异常处理。这还没算上订单超时关单、支付回调幂等、库存扣减这类进阶场景。你把这些东西走一遍基本就把 Spring Boot 3.x 在业务系统里的主力玩法摸清了。校园讲座预约、办公用品申领、餐饮点单这些系统本质也都是订单状态机加库存资源控制骨架完全通用。Spring Boot 3.x 和 2.x 最大的区别在于底层基线的整体升级。3.x 强制要求 Java 17 起步整个 Spring 框架迁移到了 Jakarta EE 9 命名空间这意味着你过去写的javax.persistence.*、javax.validation.*这类包名全部要改成jakarta.*。同时 Spring Security 6、Spring Data、Spring Cloud 的配套版本也跟着大版本换代配置文件里的很多属性路径都发生了变化。这些升级对老项目来说是一次需要正视的迁移但对新项目来说直接建立在 3.x 之上反而是顺势而为。1.2 技术选型为什么是这组搭配而不是别家我先给出一份实际项目里的技术栈参考大家可以根据自己的场景替换组件。组件推荐方案选型说明开发框架Spring Boot 3.2.x / 3.5.x3.2 是当前最稳的版本线3.5 对 Java 21 虚拟线程优化更完善JDKJava 17 / Java 2117 是起步要求21 可开启虚拟线程两者 LTS 都安全持久层Spring Data JPA QueryDSL订单查询条件多、动态组合强QueryDSL 的类型安全查询很好用数据库MySQL 8.0主流稳定事务支持完善适合订单这种强一致场景缓存Caffeine RedisCaffeine 做本地热点缓存Redis 做分布式缓存和锁接口文档springdoc-openapi 2.x3.x 对应版本 2.x自动生成 OpenAPI 3 文档参数校验Jakarta Validation通用 Bean Validation配合全局异常处理日志Logback MDCLogback 是 Boot 默认MDC 用来关联 TraceId持久层这块我特意多说两句。很多人纠结 JPA 还是 MyBatis其实两个都能用关键在于匹配场景。订单系统查询条件多比如按用户查、按时间范围查、按状态过滤、按订单号模糊搜JPA 的JpaSpecificationExecutor或 QueryDSL 能优雅地组合这些条件还天然带一级缓存和懒加载机制。MyBatis-Plus 的优势是简单直接但动态 SQL 写多了以后容易变成一坨 XML维护成本会慢慢上来。我的实际推荐是新项目且团队习惯面向对象建模选 JPA 加 QueryDSL老团队本身熟悉 MyBatis 且业务以复杂报表 SQL 为主用 MyBatis-Plus 也没问题。Spring Boot 3.x 还有个容易被忽略的点循环依赖的默认禁止策略。2.x 时代 Spring 还能自动解决 setter 循环依赖3.x 直接默认关闭启动就报错。这意味着从设计层面就要尽量避免A 依赖 B、B 又依赖 A的结构方法就是多用构造器注入配合Lazy解决个别场景后面我会专门展开讲。2. 数据模型与状态流转订单系统的地基工程很多新人上手做订单系统第一步就建表这没错但容易忽略状态流转的设计。表结构是静态的订单状态是动态的二者必须同时考虑。我的习惯是先把状态机画清楚再回头设计字段这样表结构里的状态字段、版本号字段、时间字段才会有明确的业务含义。2.1 订单主表与明细表的核心设计订单系统至少需要两张核心表订单主表和订单明细表。主表记录一笔订单的整体信息明细表记录该订单下具体买了哪些商品、数量多少、单价多少。为什么要拆两张表原因很简单订单主表会被高频更新比如支付回调要改支付状态、发货要改物流单号如果把商品明细也塞在主表里每次更新都会牵动明细数据并发和锁的粒度就变粗了。我提供一个可以直接用的建表 SQL大家根据各自业务增减字段。CREATE TABLE t_order ( id bigint NOT NULL AUTO_INCREMENT COMMENT 主键, order_no varchar(32) NOT NULL COMMENT 业务订单号, user_id bigint NOT NULL COMMENT 下单用户ID, total_amount decimal(10,2) NOT NULL COMMENT 订单总金额, pay_amount decimal(10,2) NOT NULL DEFAULT 0.00 COMMENT 实付金额, status tinyint NOT NULL DEFAULT 0 COMMENT 订单状态: 0待支付 1已支付 2已发货 3已完成 4已取消, receiver_name varchar(64) DEFAULT NULL COMMENT 收货人, receiver_phone varchar(20) DEFAULT NULL COMMENT 收货电话, receiver_address varchar(255) DEFAULT NULL COMMENT 收货地址, remark varchar(500) DEFAULT NULL COMMENT 订单备注, version int NOT NULL DEFAULT 0 COMMENT 乐观锁版本号, create_time datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT 创建时间, update_time datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT 更新时间, PRIMARY KEY (id), UNIQUE KEY uk_order_no (order_no), KEY idx_user_create (user_id, create_time) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT订单主表; CREATE TABLE t_order_item ( id bigint NOT NULL AUTO_INCREMENT COMMENT 主键, order_id bigint NOT NULL COMMENT 订单主表ID, product_id bigint NOT NULL COMMENT 商品ID, product_name varchar(255) NOT NULL COMMENT 商品名称快照, product_price decimal(10,2) NOT NULL COMMENT 商品单价快照, quantity int NOT NULL COMMENT 购买数量, subtotal_amount decimal(10,2) NOT NULL COMMENT 小计金额, create_time datetime NOT NULL DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (id), KEY idx_order_id (order_id) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4 COMMENT订单明细表;这里有两个容易踩的坑我重点说一下。第一金额字段必须用decimal(10,2)绝对不能图省事用float或double。二进制浮点数表示十进制的 0.1 时存在精度误差金额计算用浮点类型累计下来差一分钱是常有的事。涉及金额的加减乘除要么在数据库层面用decimal计算要么在 Java 端用BigDecimal二选一但不要混着来。第二为什么主键之外还要单独建order_no业务订单号因为自增主键虽然性能好但会把业务量暴露给外部而且分布式环境下多个服务同时生成订单靠数据库自增无法保证全局唯一。实际项目里我一般用雪花算法生成订单号格式可能是${前缀}${时间戳}${机器ID}${序列号}这样既保证唯一性也能从订单号直接读出大致下单时间。2.2 订单状态机用枚举把流转规则锁死订单系统的灵魂是状态机不是 CRUD。一笔订单从创建到完结合法状态流转必须严格限制否则就会出现已取消的订单还能支付成功这种搞笑的 bug。我建议把状态和允许的流转动作封装进枚举里让非法流转在编译期就能被约束。public enum OrderStatus { PENDING_PAYMENT(0, 待支付), PAID(1, 已支付), SHIPPED(2, 已发货), COMPLETED(3, 已完成), CANCELED(4, 已取消); private final int code; private final String desc; OrderStatus(int code, String desc) { this.code code; this.desc desc; } public int getCode() { return code; } public String getDesc() { return desc; } public static OrderStatus fromCode(int code) { for (OrderStatus status : values()) { if (status.code code) { return status; } } throw new IllegalArgumentException(未知订单状态: code); } public boolean canTransitionTo(OrderStatus target) { return switch (this) { case PENDING_PAYMENT - target PAID || target CANCELED; case PAID - target SHIPPED || target CANCELED; case SHIPPED - target COMPLETED; case COMPLETED, CANCELED - false; }; } }用 Java 21 的switch表达式来定义状态流转规则代码清晰而且写错了编译直接报错。实际切换状态时先查出当前订单状态校验canTransitionTo通过之后再更新而更新语句里必须带上状态条件确保并发情况下状态被其他线程改掉了也不会误更新。这里最典型的案例是重复支付回调。用户支付成功后支付平台会异步通知你的后端但通知可能因为网络原因发送多次甚至出现极端情况下用户已经取消订单但支付回调还是到了。如果回调处理逻辑不做状态校验直接把一笔已取消的订单改成已支付后面发货环节就会闹出大问题。正确做法是更新语句写成UPDATE t_order SET status 1 WHERE id ? AND status 0影响行数为 0 说明状态已经被改过直接忽略这次回调。2.3 幂等设计和并发扣库存的钱与货安全订单系统里最需要小心的两个并发问题是重复下单和超卖扣库存。这两类问题的解法不太一样我分开讲。重复下单的防线在入口。前端在提交订单时生成一个全局唯一的requestIdUUID 就行后端接单后把它作为幂等键存到 Redis 里SETNX requestId 1返回成功才继续处理返回失败说明这单已经处理过了直接返回重复请求。注意SETNX要配合过期时间一起用防止业务处理过程中宕机导致幂等键永远占着。扣库存的超卖问题最朴素的方案是数据库层面的条件更新加乐观锁。Modifying Query(UPDATE Product p SET p.stock p.stock - :quantity, p.version p.version 1 WHERE p.id :productId AND p.stock :quantity AND p.version :version) int deductStock(Param(productId) Long productId, Param(quantity) Integer quantity, Param(version) Long version);WHERE p.stock :quantity保证了库存不会被扣成负数影响行数为 0 说明库存不足或版本号冲突业务层需要重试或直接提示用户。我在实际项目中见过不少团队用 Redisson 分布式锁把整个下单流程锁起来库存问题解决了但下单接口的吞吐量被锁给拖垮了。我的习惯是库存扣减这种单行更新的场景优先用数据库条件更新分布式锁留给跨资源协调的场景比如同时操作多个商品的库存和账户余额。事务的粒度也要控制好。订单创建、明细插入、库存扣减这三个动作要么全成功要么全失败所以要在 Service 方法上标注Transactional。但事务方法里不要塞远程调用、发送消息这类外部操作因为外部操作不受本地事务控制一旦失败回滚消息可能已经发出去了会出现数据不一致。我的做法是事务内只做数据库写操作事务提交之后再通过ApplicationEventPublisher发布领域事件由监听器去发消息或通知。3. 核心功能实现从建项目到跑通下单流程设计做完开始动手。这一部分我把从零到接口跑通的全过程拆开来讲每一步都给出能直接落地的方案。3.1 用 Spring Initializr 快速搭建 3.x 项目骨架你可能习惯了在 IDEA 里新建项目其实用 start.spring.io 更直观也可以直接在 IDEA 的 Spring Initializr 向导里操作。选择的关键参数如下ProjectMavenLanguageJavaSpring Boot3.2.x 或 3.5.x推荐 3.2 求稳3.5 尝鲜Groupcom.exampleArtifactorder-servicePackagingJarJava17 或 21DependenciesSpring Web、Spring Data JPA、Validation、Redis、Lombok生成项目后解压导入pom.xml里会自动带上核心依赖。我自己还会补上几个 3.x 项目里很常用的依赖给大家一个参考dependency groupIdcom.querydsl/groupId artifactIdquerydsl-jpa/artifactId version5.1.0/version /dependency dependency groupIdcom.querydsl/groupId artifactIdquerydsl-apt/artifactId version5.1.0/version scopeprovided/scope /dependency dependency groupIdcom.github.ben-manes.caffeine/groupId artifactIdcaffeine/artifactId /dependency dependency groupIdorg.springdoc/groupId artifactIdspringdoc-openapi-starter-webmvc-ui/artifactId version2.6.0/version /dependencyapplication.yml的配置也顺手给出几个容易配置错的点我会在旁边注释server: port: 8080 spring: application: name: order-service datasource: url: jdbc:mysql://localhost:3306/order_db?useUnicodetruecharacterEncodingutf8serverTimezoneAsia/Shanghai username: root password: root hikari: maximum-pool-size: 20 minimum-idle: 5 jpa: hibernate: ddl-auto: none show-sql: true open-in-view: false data: redis: host: localhost port: 6379 database: 0 threads: virtual: enabled: true springdoc: swagger-ui: path: /swagger-ui.html logging: level: com.example.order: debug注意 3.x 里 Redis 配置的前缀从 2.x 的spring.redis改成了spring.data.redis如果你把老项目的配置直接搬过来启动时会发现 Redis 连接配置竟然完全没生效这个坑我在第 4 部分还会专门提。JPA 的open-in-view我建议显式设为false虽然 Spring Boot 默认是true但它在 Controller 层保持数据库连接的方式容易掩盖懒加载异常也会撑满连接池生产环境这样配置是有风险的。3.2 订单核心接口与业务逻辑落地项目骨架建好后我们开始写代码。我习惯按Controller 层接收参数、Service 层做业务逻辑、Repository 层操作数据库的分层方式来组织这也是最不容易出错、最适合团队协作的结构。先看 Controller 层的实现。订单模块对外主要暴露这几个接口创建订单、订单详情查询、订单列表查询、支付订单、取消订单。RestController RequestMapping(/api/orders) public class OrderController { private final OrderService orderService; public OrderController(OrderService orderService) { this.orderService orderService; } PostMapping public ResponseEntityOrderVO createOrder(Valid RequestBody CreateOrderRequest request) { return ResponseEntity.status(HttpStatus.CREATED) .body(orderService.createOrder(request)); } GetMapping(/{orderNo}) public ResponseEntityOrderVO getOrder(PathVariable String orderNo) { return ResponseEntity.ok(orderService.getOrderByOrderNo(orderNo)); } GetMapping public ResponseEntityPageResultOrderVO listOrders(OrderQuery query) { return ResponseEntity.ok(orderService.listOrders(query)); } PostMapping(/{orderNo}/pay) public ResponseEntityVoid payOrder(PathVariable String orderNo) { orderService.payOrder(orderNo); return ResponseEntity.noContent().build(); } PostMapping(/{orderNo}/cancel) public ResponseEntityVoid cancelOrder(PathVariable String orderNo) { orderService.cancelOrder(orderNo); return ResponseEntity.noContent().build(); } }注意我全部使用了构造器注入这在 Spring Boot 3.x 里是官方推荐的方式。字段上加Autowired虽然在 Boot 3 里还能用但在 IDEA 里会看到警告而且构造器注入能保证依赖不可变配合 3.x 默认禁止循环依赖的策略项目结构会健康很多。Service 层是业务逻辑的重心以创建订单为例整个流程的代码骨架是这样的Service public class OrderService { private final OrderRepository orderRepository; private final OrderItemRepository orderItemRepository; private final ProductRepository productRepository; private final OrderNoGenerator orderNoGenerator; public OrderService(OrderRepository orderRepository, OrderItemRepository orderItemRepository, ProductRepository productRepository, OrderNoGenerator orderNoGenerator) { this.orderRepository orderRepository; this.orderItemRepository orderItemRepository; this.productRepository productRepository; this.orderNoGenerator orderNoGenerator; } Transactional public OrderVO createOrder(CreateOrderRequest request) { // 1. 校验幂等键 // 2. 生成订单号 String orderNo orderNoGenerator.generate(); // 3. 计算订单金额 ListOrderItem items request.getItems().stream() .map(item - createOrderItem(item)) .toList(); BigDecimal totalAmount items.stream() .map(OrderItem::getSubtotalAmount) .reduce(BigDecimal.ZERO, BigDecimal::add); // 4. 扣减库存 items.forEach(item - productRepository.deductStock( item.getProductId(), item.getQuantity(), productRepository.findById(item.getProductId()).get().getVersion())); // 5. 保存订单和明细 Order order new Order(); order.setOrderNo(orderNo); order.setUserId(request.getUserId()); order.setTotalAmount(totalAmount); order.setStatus(OrderStatus.PENDING_PAYMENT); orderRepository.save(order); items.forEach(item - item.setOrderId(order.getId())); orderItemRepository.saveAll(items); return OrderVO.from(order, items); } }这里我刻意把扣减库存的版本号查询简化了真正生产环境不会先查一次再带进去而是直接用条件更新返回的影响行数来判断。简化是为了让大家看清流程实际写的时候要注意Product实体的version字段上要加Version注解JPA 会在更新时自动带上版本号做乐观锁校验不需要手写WHERE version ?。不过对于UPDATE ... SET stock stock - ? WHERE stock ?这种场景JPA 的Version还不够还是得用Modifying自定义更新语句两者结合使用才能既防超卖又防更新丢失。Repository 层的实现里条件查询比较能体现 Spring Data JPA 的优势。订单查询通常要支持按用户、按状态、按时间范围、按订单号模糊等组合过滤我推荐用 QueryDSL它的查询写法是类型安全的编译期就能发现字段拼写的低级错误。public class OrderRepositoryCustomImpl implements OrderRepositoryCustom { private final JPAQueryFactory queryFactory; public OrderRepositoryCustomImpl(JPAQueryFactory queryFactory) { this.queryFactory queryFactory; } Override public PageOrder searchOrders(OrderQuery query, Pageable pageable) { QOrder order QOrder.order; var predicate new BooleanBuilder(); if (StringUtils.hasText(query.getOrderNo())) { predicate.and(order.orderNo.contains(query.getOrderNo())); } if (query.getStatus() ! null) { predicate.and(order.status.eq(query.getStatus())); } if (query.getUserId() ! null) { predicate.and(order.userId.eq(query.getUserId())); } ListOrder content queryFactory.selectFrom(order) .where(predicate) .offset(pageable.getOffset()) .limit(pageable.getPageSize()) .orderBy(order.createTime.desc()) .fetch(); long total queryFactory.select(order.countFrom(order)) .from(order) .where(predicate) .fetchOne(); return new PageImpl(content, pageable, total); } }使用 QueryDSL 需要配置一个JPAQueryFactory的 Bean并且让自定义接口和实现类名遵循Repository Custom的命名规范Spring Data JPA 会自动把它合并到主 Repository 里。这个方案在订单列表这种动态查询场景里比 JPA 自带的Specification更顺手也比拼接 SQL 字符串安全得多。3.3 缓存、日志与虚拟线程的实战配置业务接口跑通之后接下来要做的是让系统更健壮、更高效。这一节我挑三个实际项目中必然会用到的能力来展开Caffeine 本地缓存、Logback 日志与 MDC 链路追踪、Java 21 虚拟线程。Caffeine 和 Spring Cache 的整合在 Boot 3 里很简单先定义一个CacheManagerConfiguration public class CacheConfig { Bean public CacheManager cacheManager() { CaffeineCacheManager cacheManager new CaffeineCacheManager(order, product); cacheManager.setCaffeine(Caffeine.newBuilder() .maximumSize(500) .expireAfterWrite(Duration.ofMinutes(10)) .recordStats()); cacheManager.setAllowNullValues(false); return cacheManager; } }订单详情这种读多写少的接口很适合用Cacheable做缓存Service public class OrderQueryService { Cacheable(cacheNames order, key #orderNo, unless #result null) public OrderVO getOrderByOrderNo(String orderNo) { return loadOrderFromDb(orderNo); } }但要注意一点不能把缓存用在状态频繁变更的接口上。比如订单支付成功后状态会改变如果缓存了旧的待支付状态用户刷新页面看到的订单还是待支付就会造成业务混乱。我的经验是缓存只用于订单创建后短时间内不会变化的展示数据而支付、取消这样涉及状态变更的操作要么不走缓存要么在更新数据库后显式调用CacheEvict清掉对应缓存。日志方面Spring Boot 3.x 默认使用 Logback支持直接写logback-spring.xml放在src/main/resources下。我通常在日志配置里加入 TraceId 的生成和传递逻辑一次请求无论是 Controller 层、Service 层还是调用外部接口所有日志都能通过同一个 TraceId 串联起来排查问题的时候特别管用。configuration appender nameCONSOLE classch.qos.logback.core.ConsoleAppender encoder pattern%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - [%X{traceId}] %msg%n/pattern /encoder /appender appender nameASYNC_FILE classch.qos.logback.classic.AsyncAppender appender-ref refFILE / queueSize512/queueSize discardingThreshold0/discardingThreshold /appender root levelINFO appender-ref refCONSOLE / appender-ref refASYNC_FILE / /root /configurationMDC 的traceId需要在请求入口处生成并放入。最直接的方式是注册一个HandlerInterceptor在preHandle里放入MDC.put(traceId, UUID.randomUUID().toString())在afterCompletion里MDC.remove(traceId)。这样同一个请求的所有日志就都能带上同一个traceId包括异步线程池的逻辑但要注意异步线程默认不会继承父线程的 MDC 上下文需要额外处理后面我会在常见问题部分展开。虚拟线程是 Java 21 带来的一个重要特性Spring Boot 3.2 及以上版本可以直接开启spring: threads: virtual: enabled: true开启之后Tomcat 会把每个 HTTP 请求承载在虚拟线程上执行而不是传统的平台线程。虚拟线程的调度完全由 JVM 负责阻塞 IO 操作时它会自动让出底层载体线程所以在高并发 IO 密集场景下系统的吞吐量提升非常可观。我实测过订单列表接口在同样的压力下开启虚拟线程后线程数从 200 个平台线程缩减到几十个虚拟线程同时并发处理能力还更稳了。不过要注意虚拟线程并不适合 CPU 密集的计算任务而且代码里如果用到synchronized或者ThreadLocal需要仔细检查是否会有阻塞或上下文丢失的问题。4. 常见问题与排查技巧实录这一节我把实际开发和升级过程中遇到的高频问题整理成一份速查表每个问题都给出现象、原因和解决思路。4.1 从 2.x 升级到 3.x 的配置迁移清单很多人拿着 2.x 的项目升级到 3.x启动直接报错原因基本都是这几个问题现象原因解决方法编译报错javax.servlet不存在3.x 迁移到 Jakarta EE 9全局替换javax.*为jakarta.*Redis 配置不生效属性前缀改变spring.redis改为spring.data.redis懒加载报错LazyInitializationException循环依赖默认被禁构造函数设计避免循环依赖必要时LazyWebSecurityConfigurerAdapter不存在Spring Security 6 大改改为SecurityFilterChainBean 模式关于安全相关的配置迁移我用一个实际例子说明。2.x 时代我们都是继承WebSecurityConfigurerAdapter重写configure方法来定义授权规则3.x 直接废弃了这个类正确姿势是通过SecurityFilterChainBean 来声明Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .csrf(AbstractHttpConfigurer::disable) .sessionManagement(session - session.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) .authorizeHttpRequests(auth - auth .requestMatchers(/api/orders/**).authenticated() .anyRequest().permitAll() ); return http.build(); }这里顺带说一下很多博主喜欢贴密码加密、Token 认证那套完整配置但订单系统实战里安全体系往往是和公司统一的认证中心对接的单体项目直接集成 Spring Security 做 JWT 的场景反而不多。你需要的是掌握配置模型的写法而不是把一套完整的认证代码背下来。4.2 依赖版本对应与 Bean 注入疑难点Spring Boot 3.x 的生态里很多第三方库的版本必须跟着 Boot 版本走版本错配是启动失败的常见原因。我整理了一份实际使用过的版本对应关系组件Spring Boot 3.2.xSpring Boot 3.5.xJDK 基线1717 或 21QueryDSL5.1.05.1.0OpenFeign4.x4.xspringdoc-openapi2.3.x2.6.xSpring Cloud2023.0.x2026.0.xspring-boot-starter-data-redis3.2.x 内置3.5.x 内置这里的io.github.openfeign.querydsl其实是一个在 Feign 场景下做查询拦截的扩展库它和 Spring Boot 的版本对应关系本质上由 Spring Cloud OpenFeign 模块决定。我的经验是如果你不确定版本最简单的方式是不要手动写版本号直接用spring-boot-dependenciesBOM 管理的传递依赖第三方库只保留自己的版本号这样能最大程度避免版本冲突。Bean 注入的疑难点主要集中在一个问题上同类型多个 Bean 时怎么选。比如项目里有OrderService和OrderQueryService你注入OrderService时 Spring 可能找到两个候选此时可以用Qualifier指定名字或者用Primary标记默认优先的 Bean。我在 Boot 3 项目里的建议是优先用构造器注入配合Qualifier尽量避免字段注入因为字段注入在单元测试时替换 Mock 对象很麻烦而且隐藏了依赖关系。还有一个高频问题java.util.concurrent.ThreadLocal和虚拟线程的冲突。虚拟线程数量不受线程池限制如果代码里用ThreadLocal存储用户信息由于虚拟线程会被复用ThreadLocal的值可能会泄漏到下一个请求。Spring Boot 3.2 提供了方案使用io.netty.util.concurrent.FastThreadLocal或者干脆在过滤器中每次清理ThreadLocal。我在订单模块里就用了一个简单的HandlerInterceptor在afterCompletion中统一清理避免脏数据串号。最后一个常见但很隐蔽的问题Transactional自调用失效。同一个类里一个方法调用另一个标注了Transactional的方法事务是不会生效的因为 Spring 的事务代理只在外部调用时才起作用。这个坑几乎每个人都会踩排查思路是createOrder调本类的deductStock方法即使deductStock标了Transactional事务也不会开启。解决办法有两个要么把需要事务的方法拆到独立的Service类中要么通过AopContext.currentProxy()获取代理对象再调用但后者代码可读性差不太推荐。实际运行中的性能调优与后续扩展订单系统跑通之后我一般会继续做两件事性能调优和架构演进。这里分享一些实测数据和个人经验供大家参考。先聊性能调优。以订单创建接口为例瓶颈往往不在计算而在数据库的写入放大效应。每笔订单要插入主表一条、明细表 N 条还要更新商品库存对 MySQL 来说就是至少 1 N N 次写操作。我的优化思路是把明细表的批量插入合并成一条 SQL用saveAllAndFlush或者 JDBC 的rewriteBatchedStatementstrue参数实测在 MySQL 8 下批量插入性能能提升一个数量级。库存扣减则尽量合并到事务的最后执行缩短事务持有锁的时间。另一个实测有效的优化点是热点数据的本地缓存。Caffeine 作为进程内缓存查询订单详情和商品信息命中率极高压测时 QPS 从 800 提升到 2200而且 Redis 的访问量也降下去了。但要注意缓存一致性问题我在订单状态变更后调cacheManager.getCache(order).evict(orderNo)保证用户下单后立刻能看到最新状态这才符合业务预期。架构演进方面如果订单量持续上涨单库单表迟早会成为瓶颈。我自己的演进路径是先引入消息队列把支付回调、订单超时关单等异步事件解耦再按用户维度做分库分表最后才是微服务拆分。微服务拆分要谨慎订单服务、商品服务、支付服务三个模块之间的调用链路一旦拉长一致性保障的复杂度会成倍增加。Spring Boot 3.x 配合 Spring Cloud 的 OpenFeign 做服务间调用很顺手但分布式事务这块能规避就要规避别一上来就上 Seata大多数场景通过状态机加重试就能解决。关于虚拟线程我再说点实际体会。Spring Boot 3.5 加上 Java 21 的虚拟线程对订单这种 IO 密集型的业务非常友好但代码里如果有自旋锁、synchronized修饰的静态方法、或者依赖线程池隔离的场景需要重新评估。我的做法是新项目直接开虚拟线程老项目先做压测对比再决定是否切换。最后日志切面在订单系统里非常值得投入。我写了一个简单的Around切面自动记录每个订单接口的入参、出参、耗时和异常信息配合 MDC 的 traceId排查线上问题时效率提升非常明显。这是所有订单项目必做的一项工程代码量很小收效却是实打实的。我个人在实际项目中最深的体会是状态机设计得足够严谨订单系统的绝大多数问题都能在写代码之前被挡掉。数据模型先行、状态流转锁定、并发边界想清楚剩下的编码只是把这些设计翻译成实现罢了。