WriteAPI.WritePoint()不报错≠数据已写入，必须调Flush()暴露真实错误；QueryAPI.Query()返回空≠没数据，90%因Flux漏yield()或时间范围错。
WriteAPI.WritePoint() 不报错 ≠ 数据已写入，QueryAPI.Query() 返回空 ≠ 没数据——这是 Go 接入 InfluxDB 时最常被误判的两个“假成功”信号。
WritePoint() 静默失败：异步机制吞掉所有错误
默认 WriteAPI 是异步的：调用 WritePoint() 只是把点塞进内存缓冲区，不发网络请求，也不校验 token、bucket 或时间戳。网络中断、401 token 过期、404 bucket 不存在、零值时间戳（time.Time{}）全被静默丢弃，err == nil 是常态。
- 必须在每次写完后显式调
writeAPI.Flush()，它才真正提交并返回真实错误 - 调试阶段建议每写 1–10 条就
Flush()一次；生产环境可用定时 + 数量双触发的批处理，但 Flush 仍不可省 - 想绕过异步陷阱？改用
WriteAPIBlocking，但它会阻塞 goroutine，高并发采集场景慎用 - 时间戳必须非零：
SetTime(time.Now().UTC())，别依赖默认值或留空
Query() 返回空 slice 的真实原因
QueryAPI.Query() 返回 []*flux.Table 且 err == nil，但遍历不出数据？90% 不是连接问题，而是 Flux 脚本本身没生效。
- 漏写
|> yield()：Flux 默认不输出任何结果，必须显式声明，否则返回空 - 时间范围错：
range(start: -1h)查最近 1 小时，但你的数据可能在 2 小时前，改成range(start: -24h)或具体时间戳再试 - 字段名含特殊字符（如
cpu-usage）必须用双引号："cpu-usage"，否则解析失败 - Flux 字符串建议用反引号包裹：
`from(bucket:"my-bucket")|>range(start:-1h)`，避免 Go 字符串转义干扰
解析 Query 结果必须过两层结构
Flux 查询返回的是嵌套结构：多个 Table → 每个 Table 包含多个 Record。跳过 Table 层直接调 result.Records() 会 panic。
立即学习“go语言免费学习笔记（深入）”；
- 正确路径：
for _, table := range result.Tables() { for _, record := range table.Records() { ... } } -
record.ValueByKey("_value")可能为nil，不判空直接.Float()或类型断言会 panic - 时间统一用
record.Time()，数值用record.ValueByKey("field_name")，别混用已废弃的record.Field() - 字段名动态时（比如来自 tag），先用
record.Values()看实际键名，别硬编码 key
初始化 client 和 writeAPI 的参数易混淆点
URL 和 token 是 client 初始化时传的；org 和 bucket 是 WriteAPI 或 QueryAPI 创建时才指定——这个分离设计导致大量参数错位。
-
influxdb2.NewClient("http://localhost:8086", "your-token")：只接受两个参数，末尾不能带/api/v2 -
client.WriteAPI("my-org", "my-bucket")：org 和 bucket 名大小写、下划线、连字符必须完全匹配，输错一位就是 404 - SDK 不提供创建 org/bucket 的接口，必须提前在 UI 或 CLI 完成，且 token 需有对应 bucket 的 write 权限
- 自签名 HTTPS 或本地测试需显式配
influxdb2.HTTPConfig{InsecureSkipVerify: true}
最麻烦的不是语法，而是那些不报错却让数据消失的隐性约束：时间戳精度错位、tag 基数失控、Flux yield 缺失、table 层级跳过——它们不会打断编译，但会让监控系统在关键时候彻底失明。
