ARC 1先看见共享状态第 1–4 章

第 2 章 —— 启动第一个 Runtime

本章目标： 本章完成后，开发者能够构建一个单节点 DsmRuntime，注册 route-hints，并准确解释本地写入成功的含义。

学习目标

  1. 识别 Runtime、membership 和 collection spec 的职责。
  2. 按正确顺序完成 build、register、start、close。
  3. 写入并读取第一个 RouteHint。
  4. 区分本地 API 成功与远端可见。

前置条件

案例进度

履约网关现在需要发布 fulfillment-primary → 10.0.0.8:8080。本章只让一个节点保存并读取该提示，不讨论网络传播。

四步生命周期

第一个 Runtime 的生命周期

DsmRuntimeBuilder 负责组装运行时；ClusterMembership 提供节点身份和通信；CollectionSpec 给集合稳定的定位与 schema；DsmRegister 才是业务读写句柄。

NodeInfo self = new NodeInfo("gateway-a", "127.0.0.1", 19090);
DsmRuntime runtime = DsmRuntimeBuilder.builder()
        .clusterId("fulfillment-local")
        .serviceId("gateway")
        .membership(new StandaloneClusterMembership(self))
        .build();

CollectionSpec<RouteHint> routes =
        CollectionSpecBuilder.<RouteHint>register("demo", "gateway", "route-hints")
                .schemaId("route-hints/v1")
                .recordCodec(RouteHint.class)
                .build();
DsmRegister<RouteHint> register = runtime.register(routes);
runtime.start();

先注册集合再启动，使 Runtime 在进入 RUNNING 时已经知道集合 schema。使用完毕调用 close()；示例和测试应放在 try/finally 或 try-with-resources 等价结构中。

第一个本地提交

register.put(new RouteHint(
        "fulfillment-primary",
        EntityMetadata.empty(),
        "10.0.0.8:8080"));

String address = register.get("fulfillment-primary")
        .orElseThrow()
        .address();

put 返回表示当前节点已接受本次本地变更。它没有返回复制确认数量，也没有承诺另一个节点此刻已经读到。单节点 membership 更不会凭空产生远端副本。

反例与故障注入

尝试在 runtime.start() 之前把 Runtime 当成已经对外服务，或忘记 close()。前者混淆配置完成与可运行状态；后者让测试泄漏线程和资源。另一个常见错误是看到本地 get 成功就宣称「集群已经一致」。

实验

运行上游 Runtime/REPL 示例测试：

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

观察命令处理器可以存储、列出条目，同时保留测试中显式创建和关闭 Runtime 的边界。该命令使用受控的 fake peers，因此成功结果仅表示单进程路径可用，不构成真实网络验收。

实验验收卡

字段 内容
运行命令 cd submodule/dsm-examples/basic-usage-examples && ./mvnw -q -Dtest=DsmReplTest test
输入或故障 单节点读写；测试内受控 peer
可观察结果 DsmReplTest 的 3 个测试通过；Runtime 被显式关闭
证据等级 E2：运行固定源码的进程内测试
本实验未证明 真实网络、生产发现机制、远端写入确认和容量

回顾

下一步

第 3 章把 RouteHint 拆成 entry identity、实体字段、metadata、codec 和 schema，让传播双方谈论同一份状态。

证据链接