唯一能稳定写入的路径是复用全局influxdb-client-go/v2单例客户端，禁止单次请求新建client；初始化需传URL、token并配置HTTPConfig，写入时显式SetTime、批量Flush且控制tag基数。
直接用 influxdb-client-go/v2，别拼 HTTP、别用老库、别在 handler 里 new client——这是唯一能稳定写入的路径。
初始化 client 必须复用全局单例
每次 HTTP 请求都调 influxdb2.NewClient()，不出三分钟就耗尽连接池，Gin 会卡在 http.Transport 的 MaxIdleConnsPerHost 上。client 内部已管理连接池和重试，但只对复用实例生效。
- 在
main.go或pkg/infra/influxdb.go中初始化一次，注入到 Gin*gin.Engine的Engine.Keys或用依赖注入容器传入 - URL 必须带协议和端口：
"http://localhost:8086"或"https://influx.example.com:8086"；若用自签名证书，加influxdb2.HTTPConfig{InsecureSkipVerify: true} - token 要提前在 InfluxDB UI 的 Load Data → Tokens 页面创建，并绑定到目标 org 和 bucket 的 Write 权限；org 填 name（如
"my-org"），不是 ID
写入时时间戳必须显式设为 time.Time
Gin 解析 JSON 后的 time.Time 字段不会被自动识别为 Line Protocol 时间戳；不手动调 point.SetTime()，InfluxDB 就用服务端接收时刻，设备上报时间全丢。
- 从字符串解析：用
time.Parse(time.RFC3339, "2026-10-10T12:30:45Z")，别用time.Parse("2006-01-02...", ...)漏掉时区 - 秒级指标要对齐：写入前必须
t.Truncate(time.Second)，否则range(start: -1m)查不到数据 - 禁止传
int64或字符串时间戳给SetTime()—— 它只收time.Time；也别用.UnixMilli()，纳秒精度被截断会导致多点覆盖
批量写入必须配 WriteOptions 并定期 Flush()
WriteAPI.WritePoint() 是异步缓冲，不调优等于没写：不 Flush() 进程退出就丢数据，不设 BatchSize 就是单条 HTTP 请求压垮服务端。
- 推荐配置：
BatchSize: 1000、FlushInterval: 1000（毫秒）、ErrorCallback捕获后台失败 - 别在 Gin handler 里每条都
writeAPI.Flush()；应启动一个 goroutine 定期 flush，或在程序退出前统一调writeAPI.Close()（它会自动 flush） - 高并发下 tag 基数必须控制：
host、service可以放 tag，request_id、user_ip必须进 field，否则 series 爆炸直接 OOM
Line Protocol 格式错误会静默丢点
InfluxDB 对格式极其敏感，字段名含空格、tag 值含逗号、measurement 以数字开头……整行都会被跳过，且返回 204，日志里啥也没有。
- measurement、tag key、field key 禁止空格、逗号、等号、换行符；tag value 里的空格允许，但逗号和等号必须转义为
\,、\= - 字段类型不能混用：同一 measurement 下，
value=123（int）之后写value=123.0（float），后者会被忽略；统一用float64或后缀8i - 别手拼 Line Protocol 字符串——用
influxdb2.NewPoint()+SetTime()+AddField()，SDK 会自动编码并校验
最易被忽略的是：写入后不检查 writeAPI.Flush() 返回的 error，以及 query 时不循环 result.Next() —— 这两个点导致“明明写了却查不到”成为高频故障。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
