第 16 章：把实验转换成团队可以维护的交付

16.1 先保留已验证的能力

本书真实执行了 HTTP、Redis、RocketMQ 和 OTLP 连接，并从 Tempo、Prometheus 与 Collector 日志取得返回。它验证了特定场景的父子关系、上下文断点、客户端注入等待、异步等待、受控错误、告警状态与采样。读者可以复核代码、镜像摘要和查询 JSON，再决定哪些机制适合迁移到自己的系统。

但三个逻辑服务共用 JVM，不能验证独立进程间的时钟差异、主机失效和网络隔离。Redis 与 Broker 都是单实例，也没有展示生产持久化、身份认证和高可用。没有部署 Grafana、Loki 或 Alertmanager，所以图形探索、日志索引和通知链都需要另外实现和验收。

把这些边界写清楚，可以帮助团队安排真正需要补的工作，避免为了“架构完整”先堆叠一批尚无问题要回答的组件。

16.2 用合同约束遥测变化

服务名、操作名、路由标签和事件名会进入查询与运行手册，修改它们相当于修改一个接口。上线新版本前，应检查旧查询是否仍然可用，标签是否突然增多，采样和脱敏规则是否保持预期。需要更名时，可以制定迁移窗口，而不是在一次重构里无声地让告警失效。

自动仪表化可以补充客户端、框架和运行时信息，但应先检查与现有手工 span 的重复。一个请求出现两层同名区间，并不意味着观测变得更准确。团队应明确哪些 span 是框架边界，哪些是业务决定，哪些指标按什么分母累计。

来源版本也属于合同。官方文档的 latest 页面可能变化，本书记录访问日期、页面指纹、依赖版本和容器摘要。升级时重新运行真实验收，比仅更新版本号并保留旧截图更可靠。

16.3 让运行手册从用户症状开始

一份好的手册不只是罗列 dashboard。它从“用户等待”“错误比例增加”“异步结果滞后”“trace 断开”等症状出发，给出第一条查询、预期结果、下一步分支和停止条件。明确什么时候应扩大影响判断，什么时候证据不足以继续归因。

每条告警最好连接到相关查询和近期变更，而不是附上几百行原始日志。需要通知到人时，还要测试路由、去重、静默和恢复，而不是以 Prometheus firing 代替完整闭环。本书的短窗口规则是演示，生产阈值应由真实服务目标与响应能力决定。

最后，把完整发布对应到一个提交、一次构建和一份证据包。网页和 EPUB 由同一份正文生成，代码附录与实验源码同源；结构检查能够发现内容漂移，但不会替代事实审阅。真正可维护的结果，是下一位读者能够独立运行、解释失败，并知道哪些结论还没有证据。

结业练习。 为你自己的一个 Java 服务写一页交付说明：定义用户完成条件，画出至少一个异步边界，列出三条查询与一个反例，估计指标维度上限，并说明 Collector 不可用时允许怎样退化。完成一次专用环境实跑后，再把“计划验证”改成带提交和证据的“已经验证”。