技术实验报告的作用是让另一个人在相同条件下得到相同结果，并看清结论不能覆盖的范围。它不是操作流水账，也不是 为了证明作者一开始的想法正确。
Table of contents
先区分实验与演示
演示证明一个功能可以工作，实验比较变量变化是否影响结果。两者都重要，但不能用一次成功演示证明性能、稳定性或 普遍适用性。
例如，“程序打印了问候语”是演示；“对 1、100、10,000 个字符输入分别测量耗时和内存”才是带变量的实验。
写出可证伪假设
**假设（Hypothesis）**是实验开始前写下、可能被证据推翻的预测。避免使用“性能更好”这类缺少指标的表述。
一个可测试假设包含条件、变化和指标：
在 JDK 21、固定堆大小和相同输入集下，方案 B 的 P99 延迟比方案 A 至少降低 20%，错误率不增加。如果结果只降低 8%，或者错误率上升，假设就没有得到支持。报告失败假设同样有价值，它能阻止团队在生产环境重复 错误尝试。
固定实验环境
环境差异会改变结果。报告至少记录以下信息。
| 类别 | 需要记录的内容 |
|---|---|
| 代码 | Git 提交、分支、未提交修改 |
| 运行时 | JDK 发行版、版本、JVM 参数 |
| 构建 | Maven 和依赖版本 |
| 机器 | CPU 架构、核心数、内存、操作系统 |
| 容器 | 镜像摘要、CPU/内存限制、网络模式 |
| 数据 | 数据版本、规模、生成方式、脱敏规则 |
版本不要只写“最新版”。“最新版”会变化，无法帮助未来复测。
控制变量和对照组
自变量是你主动改变的因素，因变量是你测量的结果，控制变量是实验期间保持不变的条件。对照组提供 比较基线。
以 GC 参数实验为例：
- 自变量：垃圾收集器类型。
- 因变量：吞吐、P99 延迟、暂停时间和错误率。
- 控制变量：代码、流量、堆大小、机器和数据。
- 对照组：当前生产参数。
一次改变多个因素时，即使结果变好，你也无法判断哪个变化有效。
保留命令和原始证据
报告应包含可以复制的命令，以及原始结果的保存位置。不要只粘贴对结论有利的截图。
用实验工程运行一个指定测试：
./mvnw -Dtest=GreetingServiceTest test记录退出码、测试数量、耗时和失败详情。性能实验还要保留原始测量文件，报告中的图表应能从原始数据重新生成。
敏感生产数据必须先脱敏。报告中记录数据生成或脱敏规则，不要复制用户姓名、Token、订单详情和内部地址。
区分观察、推断与决定
三者混在一起会让结论看起来比证据更强。
- 观察：测试运行 30 次，方案 B 的 P99 在 180—195 ms。
- 推断：方案 B 可能减少了锁竞争，需要使用 Profile 进一步确认。
- 决定：先在 5% 流量中灰度方案 B，错误率超过 0.1% 时回滚。
推断必须标注不确定性。决定还要考虑迁移成本、安全和可运维性，不能只看一个性能指标。
使用统一报告结构
下载技术实验报告模板下载，并按下面顺序填写：
- 写明问题、目标和非目标。
- 在运行前写出假设和验收阈值。
- 记录环境、代码版本、数据和工具。
- 定义自变量、因变量、控制变量和对照组。
- 保存执行步骤、原始结果和异常情况。
- 分开写观察、推断、结论与适用边界。
- 记录后续动作、负责人和复测条件。
发布前检查
用这份清单检查报告是否能支持决策。
- 另一个人能否在 30 分钟内找到代码、数据和运行命令？
- 实验失败时是否仍保留完整记录？
- 图表是否标明单位、样本数、时间范围和聚合方式？
- 结论是否超出了测试环境和输入范围？
- 是否写明安全、成本和回滚影响？
- 是否删除身份信息、凭证和受保护数据？
下一步
阅读用 ADR 保存架构决策，学习如何把实验结论与业务约束 转换成可追溯的架构决定。