[/metrics] — 验证写入逻辑规则
# 一、实验目标与背景本章聚焦：写入行为验证
目的：基于三组对照实验，验证 相同时间戳是否覆盖、新增时间戳是否追加、以及 多对象数组是否等价支持，并用查询结果闭环校验。
适用场景
- 自定义指标联调：判定“补点/纠错/回灌”的生效方式
- 大规模上报压测：确认写入与查询一致性
- 看板对齐：避免前端误解为“脏读/丢点”
# 二、实验一：追加写入 —— 新时间戳应追加
# 1、操作步骤
替换 metrics，去掉最早的 2384，新增 1758095682884:77：
"metrics": {
"1758095682484": 8,
"1758095682584": 9,
"1758095682684": 99,
"1758095682784": 10,
"1758095682884": 77
}
1
2
3
4
5
6
7
2
3
4
5
6
7
发起请求（APIFOX 执行）：
# 2、查询与结果对比
执行查询接口：
返回体关键片段（对比追加前后）：
// 追加前
"metrics": {
"1758095682384": 7.0,
"1758095682484": 8.0,
"1758095682584": 9.0,
"1758095682684": 99.0,
"1758095682784": 10.0
}
// 追加后
"metrics": {
"1758095682384": 7.0,
"1758095682484": 8.0,
"1758095682584": 9.0,
"1758095682684": 99.0,
"1758095682784": 10.0,
"1758095682884": 77.0
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
结论：新增时间戳被追加，历史点位保留。
# 三、实验二：覆盖写入 —— 相同时间戳应覆盖
# 1、操作步骤
将已有时间戳的值全部替换，并新增 1758095682984:9999：
"metrics": {
"1758095682384": 1,
"1758095682484": 1,
"1758095682584": 1,
"1758095682684": 2,
"1758095682784": 4,
"1758095682884": 3,
"1758095682984": 9999
}
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
执行请求与查询（已完成）：
# 2、查询返回（关键片段）
"metrics": {
"1758095682384": 1.0,
"1758095682484": 1.0,
"1758095682584": 1.0,
"1758095682684": 2.0,
"1758095682784": 4.0,
"1758095682884": 3.0,
"1758095682984": 9999.0
}
1
2
3
4
5
6
7
8
9
2
3
4
5
6
7
8
9
结论：相同时间戳的值被覆盖；新增时间戳正常追加。
# 四、实验三：数组类写入 —— 多对象拆分亦可
# 1、操作步骤
把一次请求拆分为两个对象（同一 metricname/appid/hostname）：
{
"metrics": [
{
"hostname": "dev1",
"metrics": {
"1758095682384": 1
},
"starttime": 1758095682484,
"appid": "amssmoketestfake",
"metricname": "ttbigdata.test"
},
{
"hostname": "dev1",
"metrics": {
"1758095682484": 2323
},
"starttime": 1758095682484,
"appid": "amssmoketestfake",
"metricname": "ttbigdata.test"
}
]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
执行结果：
# 2、现象与结论
- 与“单对象、多个点”的写法效果等价；
- 拆分更利于“补点/错点更正”的发布策略（按批次提交）。
# 五、三类写入方式一览（结论速查）
| 场景 | 请求特征 | 查询表现 | 规则归纳 |
|---|---|---|---|
| 追加写入 | 新增 未出现 的时间戳点 | 原有点位保留，新增点 追加 | 新时间戳 → 追加 |
| 覆盖写入 | 修改 已存在 时间戳对应的值 | 对应时间戳的值被 覆盖，新点仍追加 | 相同时间戳 → 覆盖 |
| 数组类写入 | 多对象拆分（同指标/同主机/同 appId） | 与合并写法一致，便于“补点/分批” | 写法等价，按需选择 |
# 六、易错与实战建议
注意
- 1）时间戳单位=毫秒；
- 2）新指标写入到 METRICS_METADATA_UUID 存在可见性延迟（JVM 缓存 + 聚合），耐心等待数分钟；
- 3）
hostname/appId/metricname必须与查询条件一致，否则“写入成功但查不到”； - 4）批量校验时，务必设置合理的 时间窗口 覆盖到你的点位。
实战建议
- 补点/回灌：优先使用“拆分对象”的数组写法，降低一次请求体积，便于失败重试；
- 幂等校验：同一时间戳多次上报，最后一次的值为准；
- 压测策略：先小批量验证“覆盖/追加”规则，再扩大点位与并发。
# 七、复现清单（可直接照搬）
1）准备初始 5 个点；
2）执行“追加写入”，新增 2884:77，查询应多 1 个点；
3）执行“覆盖写入”，替换已有值并新增 2984:9999，查询应“旧值变化 + 新点追加”；
4）执行“数组类写入”，两对象提交，查询应与合并写法一致。
备注：本章截图与 JSON 片段
均来自同一组实验环境（dev1/amssmoketestfake/ttbigdata.test），便于你在本地快速复现对照。