第 16 章 —— 使用 Spring Boot 装配 Runtime

本章目标： 本章完成后，开发者能够用 dsm.* 属性创建 Runtime 和命名集合 bean，理解自动装配的失败门禁，并验证应用上下文和生命周期。

学习目标

1. 说明 DsmProperties、DsmAutoConfiguration 与集合 bean 的装配顺序。
2. 配置 clusterId、serviceId、membership 和三类集合。
3. 通过 bean name 注入 typed collection handle 或领域适配器。
4. 让错误配置在启动期 fail fast。

前置条件

• 已完成第 15 章的领域端口与 composition root。
• 熟悉 Spring Boot configuration properties 和 bean 生命周期。
• 能区分「上下文启动成功」与「多节点网络已验证」。

案例进度

履约应用不再手写所有 builder。application.yml 描述 Runtime 与集合，auto-configuration 先创建 membership 和 Runtime，再注册命名集合 bean，最后把它们注入 DSM 领域适配器。

从配置到业务端口

核心顺序不能倒置：集合注册需要已存在的 Runtime；领域适配器需要已注册的 handles；上下文关闭时 lifecycle 需要停止 Runtime。

最小属性合同

第 16 章资产给出三类集合的完整配置。关键字段如下：

dsm:
  cluster-id: fulfillment
  service-id: fulfillment-control-plane
  cluster:
    mode: standalone
  collections:
    - bean-name: routeHintsCollection
      tenant-id: shared
      application-id: gateway
      collection-id: route-hints
      schema-id: route-hints/v1
      type: REGISTER
      consistency-tier: REGISTER
      entity-type: com.example.RouteHint

真实类名和 codec/merger/entity factory 需要存在。完整资产使用占位的 com.example.* 教学类型，因此用于配置评审，不直接冒充可启动应用；实际启动证据来自固定源码中的 DsmAutoConfigurationTest 与 SpringBootDsmApplicationTest。

Bean 名称有两种

auto-configuration 为 locator 建立规范名，例如：

dsmCollection:shared/gateway/route-hints

配置中的 bean-name 再提供业务友好别名，例如 routeHintsCollection。两者指向同一个注册结果。业务适配器应使用显式 qualifier/bean name，避免容器仅凭原始泛型推断目标 bean。

Record codec 的便利与边界

设置 entity-type 且类型是 record 时，自动装配可以派生 RecordCodec。非 record 实体没有显式 codec-bean 会启动失败。CRDT 还需要提供 state codec、initial state 与 merger；Lease 需要提供 entity factory。

这种 fail fast 很重要：配置缺项若等到第一条远端消息才暴露，故障位置已经离装配错误太远。

启动门禁

DsmAutoConfigurationTest 固定了这些失败或成功行为：

反例与故障注入

复制第 16 章配置资产，删除 CRDT merger bean 或让两个集合使用相同 locator。预期结果是上下文直接拒绝启动并指出配置边界，错误不应延迟到业务功能执行阶段。

实验

cd submodule/dsm
mvn -q -pl dsm-spring-boot-autoconfigure -am \
  -Dtest=DsmAutoConfigurationTest,DsmSpringBootSmokeTest \
  -Dsurefire.failIfNoSpecifiedTests=false test

再运行真实示例应用上下文：

cd submodule/dsm-examples/basic-usage-examples
./mvnw -q -Dtest=SpringBootDsmApplicationTest test

实验验收卡

回顾

• Spring Boot 只替代装配，不改变集合语义和失败边界。
• Runtime 需要先于集合，集合需要先于领域适配器。
• locator 规范名和业务别名都应明确、稳定、可测试。
• 配置错误应在启动期失败，而不是运行中静默降级。

下一步

第 17 章拆开两层身份：clusterId/serviceId 控制通信域，locator 控制同一 Runtime 内的集合域。

证据链接

• DsmProperties
• DsmAutoConfiguration
• DsmAutoConfigurationTest
• SpringBootDsmApplicationTest