实战①：需求分析与整体架构设计

这一篇不写一行业务代码，但它决定后面三篇是「往上盖楼」还是「往下填坑」。我们要做的事情只有一件：把一个模糊的愿望——「用户能下单」——变成一份谁都不用猜的合同：合同里写清楚谁提什么要求（用户故事与验收标准）、世界里有哪些东西和规矩（领域模型与状态机）、各部分站在哪（分层与模块边界）、以及对外说些什么话（接口清单）。

先把这篇反复出现的六个词一句话解释掉：

• 需求（requirement）：对方嘴里那句「我要一个下单功能」——它不是需求，它是愿望；能写出测试用例的那一句才是需求
• 用户故事（user story）：把愿望写成「作为〈谁〉，我想要〈干什么〉，以便〈得到什么好处〉」的一句话，后面必须跟一串可验证的验收标准
• 领域模型（domain model）：这门生意里真实存在的名词和规矩——订单、库存、支付，以及「库存不能为负」这类铁律，跟数据库表还没有关系
• 聚合根（aggregate root）：一组必须一起变动的对象里那个「唯一入口」。改订单项必须通过订单来改，就像改发票明细得重新开一张发票
• 分层（layering）：按「谁离用户近」把代码排成一列纵队：Controller 在最前，Service 居中，Mapper 最后，依赖只能从前指向后
• 契约（contract）：前后端共同签字的一份说明书，规定请求长什么样、响应长什么样、出错给什么码。签了字就不许单方面改

上面这张地图就是本篇的目录：第一条分支是「调用方向」（第六节），后面五条分支是六个业务包各自负责什么（第八节），最后一条 common 是全项目共用的三样小工具。看的时候盯住一件事：图上没有任何一条箭头是从右往左指回去的——这条纪律比任何框架知识都重要，违反它的代价在第十节的风险清单和第十三节的报错速查表里都会现场复现。

学完这一篇，你应该能回答三个问题：

1. 「下单要快」和「P99 响应 < 500ms」这两句话，为什么只有第二句能进需求文档？判断标准是什么？
2. order 可以调 inventory，反过来为什么不行？一旦反了，最先出问题的是编译期、启动期还是运行期？第十三节的报错表会给你答案。
3. 单体项目和微服务项目，真正的分界线画在哪里——是「拆成几个 jar」，还是「谁能独立扩容、独立上线」？

前 40 篇我们把 Spring 的零件一件件拆开讲完了——IoC、AOP、Web、数据访问、事务、缓存、安全、异步与事件、监控。但知识点是散的，真实开发却要求你把它们装进同一个工程里协同运转。从这一篇开始，我们用 4 篇文章完整交付一个可上线的项目：BeeOrder · 蜂巢订单中心。

先亮明这个项目的边界。它是一个电商订单中台单体应用，把「一个用户从注册到收到商品」的主链路跑通：

同样重要的是不做清单——明确不做什么，比列功能更能防止范围失控：

• 不做前端：所有交付物是 REST API，用 curl / Postman 即可验证（本教程第 46 篇会给出用 Docker 起前端的可选演示，但非必需）。
• 不做真实支付：接入真实支付需要商户资质与密钥，我们用「模拟支付网关」+ 回调接口完整还原支付流程的状态与幂等。
• 不做微服务拆分：先做单体，把边界划清；文末会讲「何时才该拆」，但本项目不拆。
• 不做大数据与推荐：运营统计只做到「按天汇总订单量与金额」这一层。

最初的需求往往只有一句话：「用户能下单。」但这一句话要写多少代码、怎么算完成，没人说得清。需求分析做的就是把模糊的期望变成可验收的用户故事。

用户故事的标准格式是「作为〈角色〉，我想要〈能力〉，以便〈价值〉」，并附上验收标准（Acceptance Criteria）。BeeOrder 的核心故事卡如下：

注意最后两行——它们不是「用户点击」触发的，而是系统自身的行为。真实项目里这类需求最容易被漏掉，却直接决定库存能否正确释放。

上面那张表是成品的模样；下面这段动画把它倒放一遍——看一句模糊的愿望，是怎么被三个追问逼成一张可验收的故事卡的：

三个追问里最容易跳过的是「什么场景」，而它恰好是「30 分钟未支付自动关单」这类系统行为的来源。写不出验收标准的故事，说明追问还没问完。

需求梳理清楚后，先把世界里的「名词」找出来。BeeOrder 的核心领域对象有 7 个：

它们的关系可以这样理解：一个用户有多个订单；一个订单包含多个订单项；每个订单项指向一个商品；每个商品对应一条库存记录；一次支付对应一个订单。 订单是聚合根，改动订单项必须通过订单进行。

关键业务规则必须白纸黑字写下来，因为它们直接对应代码里的分支与约束：

• 订单总价 = Σ(商品单价 × 数量)，且使用 DECIMAL / 分为单位，禁止用 double。
• 库存不能为负：扣减必须在数据库层面用条件更新（WHERE available >= ?）兜底。
• 订单状态只能按状态机流转，不允许「从 CREATED 直接跳到 COMPLETED」这种越级。
• 同一订单的有效支付只有一次：重复回调必须幂等。
• 金额、库存的每一次变动都要留流水，便于对账。

订单状态是这个项目里最核心的抽象。一旦状态定义乱了、流转约束松了，就会出现「已取消的订单又收到支付成功」这类脏数据。BeeOrder 的状态集合定为六个：

CREATED（已创建）→ PAID（已支付）→ SHIPPED（已发货）→ COMPLETED（已完成），另有 CLOSED（已关闭） 与 REFUNDED（已退款） 两个终态分支。完整流转如下：

这张表就是状态机的全部法律条文，但条文读三遍，不如图看一眼。把它画成一张可以贴在显示器边上的图：

读图的口诀是「一条主链路、两个终态、三条铁律」：主链路 CREATED → PAID → SHIPPED → COMPLETED 只许向右；CLOSED 与 REFUNDED 各自从指定入口进入后不再流出；三条铁律（状态与事件匹配、目标在允许集合内、副作用同事务或可靠事件）会在下一篇被逐条写成校验代码。

任何一次状态变更都必须满足三个条件：当前状态与事件匹配、目标状态在允许集合内、副作用在同一事务或可靠事件中执行。把这张表变成代码里的一个枚举 + 校验方法，是下一篇要做的事。

技术选型不是堆砌名词，而是做取舍。BeeOrder 的选型表：

每一行都值得追问一句「为什么不用另一个」。例如为什么用 MyBatis 而不是 JPA：本项目最关键的两条 SQL——UPDATE inventory SET available = available - ? WHERE product_id = ? AND available >= ?（原子扣减）和按天聚合的报表查询——都是「精确控制 SQL」的场景，JPA 的自动生成反而碍事。

BeeOrder 采用单体分层架构，自上而下四层，请求的流向是单向的：

• 接入层（Controller）：只做协议转换——参数校验、DTO ↔ 领域对象转换、调用 Service、包装统一响应。绝不放业务逻辑。
• 应用层（Service）：业务编排与事务边界所在。下单要「校验库存 → 创建订单 → 扣减库存 → 记录流水」，这一串编排属于应用层。
• 领域与数据层（Mapper / Repository）：MyBatis Mapper 负责持久化，Redis 承担缓存与分布式锁，MySQL 是唯一事实源。
• 基础设施：Actuator 提供可观测性，日志贯穿全链路，Docker Compose 负责本地与部署编排。

同一张图再读一遍，这次换个读法：从上往下逐层问一句「这一层有没有伸手够到别人家的活」——接入层的四个芯片全是协议活儿（鉴权、校验、转换、包装响应），应用层的四个芯片是「谁编排谁」，数据层只有存取没有判断。读完整张图，你会发现没有任何一条线从下面指回上面：

模块边界用包来体现。单模块内按业务分包，每个包内部再分 controller / service / mapper / domain / dto：

边界纪律：跨模块调用只允许「上层调下层」「order 调 inventory」，禁止双向依赖。order 依赖 inventory 和 product 是允许的；inventory 反过来依赖 order 则会造成循环，必须避免。

这条纪律管住了什么，一格一格点着看——前四格是四层各自的「不许」，最后一格是违反它的账单：

点完最后一格再回头看第七节的接口清单：清单上的每个接口都只会沿着这条链往下走，没有任何一个绕开 Service 直接摸 Mapper。

那到底哪些模块值得从单体里拆出去？别凭感觉，用两个轴量一量：横轴是这个包改动的频率，纵轴是它是否需要独立的扩容能力。

读这张图只用记两条结论：右上角的 common 改动会波及全项目，所以要用测试冻住它；左上角的 inventory 是唯一同时满足「写压力大 + 接口窄」的包，真到需要拆的那天，它是第一个切口。有边界不等于要拆服务——右下角的 order 与 product 天天在变，但一条单向依赖就够了。

接口契约是前后端协作的「合同」。BeeOrder 的接口统一前缀 /api/v1，完整清单如下（约 15 个）：

约定：所有响应统一包装为 { "code": 0, "message": "ok", "data": ... }；code != 0 表示业务错误。/payments/callback 虽不校验 JWT，但必须校验网关签名并做幂等——它是唯一对外暴露的写接口，也是攻击面最大的地方。

进入编码前，最后一个结构决定：项目是拆成多模块（Maven multi-module），还是单模块内分包？ 很多团队一上来就拆 beeorder-user、beeorder-order 等一堆模块，结果改一个接口要动三个 pom，编译一次等半天。

BeeOrder 选单模块分包。目录树如下：

第八节的结论加上第六节那张象限图，正好凑成一局配对闯关：左边是每个模块或方案的处境，右边是给你的处置结论，配错了当场解释：

整个项目拆成 4 个迭代，恰好对应本系列的 4 篇文章，每篇都有明确交付物：

把这张动图当成进度条来用：它走的六帧正好落在上面那张表的四行里——第 1 帧是本篇，第 2 帧是 #44，第 3 帧是 #45，第 4~6 帧全在 #46。读到哪一帧卡住了，就回头对照自己现在站在哪一行。每帧只交付一样东西，前一样不验收就不许进下一帧，这条纪律比任何工具都更能保证四篇写完真能跑起来：

项目启动时列出风险，比出事后复盘更有价值。BeeOrder 的四个主要风险：

设计定稿之前，先用四个实验把「这套架构到底在防什么」亲手跑一遍。实验一：分层调用与依赖方向——它把餐厅那条传菜通道画成真实调用：

实验二：一个请求穿全站。架构图上只有四个盒子，可请求真正走过的路比这长得多——鉴权、校验、事务、扣库存、发消息各有各的位置：

实验三：条件装配。它解决「同一个功能，测试环境和生产环境想不一样」的问题。条件注解（@Conditional 家族——按「类在不在、Bean 在不在、配置项是什么」决定要不要装配的那个开关） 就是自动配置的守门人：

实验四：自定义 Starter，把上面三件事打包。Starter（把一堆依赖 + 一组自动配置预先装好、引入即用）就是把「别人踩过的坑」装进盒子里。BeeOrder 后面要用 spring-boot-starter-web、mybatis-spring-boot-starter 等一堆盒子，值得知道盒子里装了什么：

实验五：把以上结论敲进一台真容器。 前面四张图给的是「看」，这一台给的是「敲」——boot 起容器、beans 点名，再用 lab 把分层、越层、请求旅程、条件判定依次跑成一条流水：

敲完 beans 再回忆第六节那张分层图：容器里每个 Bean 的座位，都由它所在的包与依赖方向决定——这比背目录树直观得多。

架构决定不了一天的工作量，但能决定改一个需求要动几个文件。下面这个沙盘把第六节和第八节的两个选择合成一个三档开关：切一档，同屏看「启动能不能起来、加字段要改几处、跨模块调用要不要走网络」三个结果。

第一道是热身题，考第五节那张选型表的读法：

第二道是综合题，把第六节、第七节和第十节串起来：

设计稿定得再漂亮，第一天写代码照样会撞墙。下面每一行「报错原文」都可以整段复制去搜索，别意译也别缩写。

表格第二行那种环，读文字和看原件是两回事。下面就是当时的原始报错，每一段都能点，点错也会告诉你为什么不是它：

复盘只需一句：这条报错里真正要改的地方，就是 inventory 包里那一行反向 import；其余每一帧都在告诉你「为什么不是别的东西」。

三档难度，第一档照做就能跑通，第三档做完你就有了自己的架构评审清单。

目标：亲手搭出 BeeOrder 的工程骨架，并且故意制造一次包位置错误，亲眼看到那条 could not be found。

第一步，新建 pom.xml（Spring Boot 3.2.5 + Web + JDBC，MySQL 先不接也能启动）：

这份 pom 不用逐字抄，勾一遍就有。默认勾的三项（Web / Validation / JDBC）正是第一档要跑通的最小骨架；再把后面三篇才会真正吃进来的依赖也看全——先知道总数，再决定哪些现在就引：

第二步，按第八节的目录建包，写启动类和两个最小类。注意启动类必须放在 com.beeorder，也就是所有业务包的共同父包：

第三步，启动并访问：

预期响应（正文就一行，没有 JSON 信封——信封是下一篇的活）：

第四步，制造一次「扫不到 Bean」。把 OrderMapper.java 改成 MyBatis 那种接口 + @Mapper 的写法（真实项目里就是这么写的），并把包声明从 com.beeorder.order.mapper 挪到 com.beeorder.dao——注意它仍然在启动类 com.beeorder 的子树里，所以「包在外头」这个借口这次不成立：

重启，预期控制台直接停在这里：

真正的原因有两层，一层比一层隐蔽：① 接口没有实现类，容器没法反射把它 new 出来——Mapper 接口的实例是靠 MyBatis 的动态代理现造的，不是靠组件扫描；② @Mapper 这个注解本身不带 @Component 语义，所以哪怕包在子树里也一样扫不到。少了 mybatis-spring-boot-starter（或没告诉它去哪找接口），这条链路就断在装配阶段。

第五步，把它救活：在启动类上加一行 @MapperScan("com.beeorder.dao")，同时确保 pom.xml 里有 MyBatis 的 starter，重启后再 curl 一次，仍然返回 mapper-ok。这一步的意义在于你会永久记住：「包能不能被扫到」和「这类东西归谁装配」是两个问题——普通类靠组件扫描，Mapper 接口靠 @MapperScan，第三方组件靠 starter 的自动配置。

验收清单：① 说得出第四行为什么失败、第五行为什么成功；② 能指出这条报错里真正决定成败的那个词（scan）；③ 把 PingController 的构造器注入改成字段 @Autowired，其余不动，重启——仍然启动失败，因为「有没有这个 Bean」发生在装配阶段，跟用哪种注入方式无关。能讲清这一点，你就分清了「装配缺失」和「装配时序」两类问题。

每条只改一个地方，观察结论完全不同：

1. 造一个跨层反向依赖：给 OrderMapper 加 private final OrderService orderService;（构造器注入），同时 OrderService 构造器注入 OrderMapper。你会观察到：启动直接失败，日志里画出 orderService ==> orderMapper ==> orderService 的环。再把 OrderMapper 那侧改成字段注入，Boot 3 默认仍然报错——因为 Spring Boot 2.6 起 spring.main.allow-circular-references 默认为 false；只有显式把它设成 true，字段注入那一侧才会靠三级缓存被哄起来，程序能跑，但模块边界已经塌了。
2. 把 @Transactional 从 OrderService 的 public 编排方法上挪走，改成标在同类另一个私有方法上，并在编排方法里用 this.helper() 自调用它。你会观察到：两种写法既不报错也不回滚——事务靠代理包装，而代理只能拦到「从外面调进来的公开方法」。再把注解放回 public 方法、由 Controller 通过注入的 Bean 调用，第二次写入失败时第一次会被撤销。对照第十节实验一的「事务边界落在哪」那一档，两边结论应当完全一致。（注意别指望 getClass() 打印出 CGLIB 类名来验证：只有真的命中切面的 Bean 才会被代理，控制器通常不在其中。）
3. 把 spring-boot-starter-jdbc 从 pom.xml 删掉。你会观察到：如果代码里没有注入 JdbcTemplate，应用照常启动（少引一个 starter 只是少一批能力，不一定报错）；一旦注入了 JdbcTemplate，启动就报 No qualifying bean。对照 --debug 输出的条件评估报告，找到 DataSourceAutoConfiguration 那一行的 matched: false。

提示：做完第 1 条回头翻第十三节表格的第二行，两边应当完全对得上。

给自己写一份架构体检脚本，以后接手任何项目先跑一遍。

需求：

• 一个 LayerRulesTest（纯 JUnit + 反射，不许修改任何业务类），扫描 src/main/java 下所有 .java 文件的 package 与 import 声明
• 校验三条规则：① controller 包不许 import mapper 包；② 任何包不许 import order 包里再 import 回来的类（检测长度为 2 的依赖环）；③ common 包不许 import 任何业务包
• 违规时输出一张表：文件、行号、违规 import、违反了哪条规则、建议怎么拆
• 附带一份 ARCHITECTURE.md 模板，把第六节的分层图、第七节的接口清单和这张规则表钉在一起

验收清单：① 在当前骨架上跑，规则 ① 立刻抓到 PingController 直接 import OrderMapper 这条违规；② 按建议插入一个 OrderService 后测试转绿；③ 人为制造一个 inventory → order → inventory 的环，脚本能在测试阶段报出而不必等到应用启动；④ 全流程不需要修改业务代码一行。