使用influxdb-client-go是连接InfluxDB 2.x最稳妥方式，它由官方维护、仅支持2.x及以上版本，不兼容1.x；需正确配置url、token（非用户名密码）、org（组织名，非数据库名）和bucket（数据容器），并注意字段类型、时间戳、批量写入及QueryAPI取值规范。
用 influxdb-client-go 连接 InfluxDB 2.x 是当前最稳妥的方式
Go 官方不维护 InfluxDB 驱动，社区主流方案是 influxdb-client-go（由 InfluxData 官方维护）。它只支持 InfluxDB 2.x 及以上（含 Cloud），**不兼容 1.x 的 HTTP API**。如果你还在用 1.8 或更早版本，得先确认是否能升级——否则只能退回到用 net/http 手写请求，或改用第三方兼容库（如 influxdb1-client，但已归档且无维护）。
初始化 client 时必须传对 url、token 和 org
连接失败最常见的原因是参数错位或权限不足。InfluxDB 2.x 认证靠 token，不是用户名密码；org 是组织名（不是数据库名），bucket 才是实际写入/查询的数据容器。
示例代码片段：
import "github.com/influxdata/influxdb-client-go/v2"
client := influxdb2.NewClient("http://localhost:8086", "my-token-here")
defer client.Close()
// 注意：queryAPI 和 writeAPI 都要指定 org
queryAPI := client.QueryAPI("my-org-name")
writeAPI := client.WriteAPI("my-org-name", "my-bucket-name")
-
url末尾不要加/api/v2，客户端内部会自动拼接 -
token必须有对应org和bucket的读/写权限（在 UI 的 “Load Data > Tokens” 里生成） -
org名区分大小写，且不能是 ID（比如1234abcd...），得填你在 UI 里看到的组织名称（如acme-inc）
写入数据时别直接用 Point 构造器拼 tag/field，优先用 WriteAPI 的批处理接口
手动 new Point 容易漏掉时间戳或类型转换错误（比如把 int 当 float64 写），而且单点写入性能极差。推荐用 WriteAPI 的批量写法，自动处理序列化和重试。
立即学习“go语言免费学习笔记（深入）”；
正确姿势：
point := influxdb2.NewPoint("cpu",
map[string]string{"host": "server01", "region": "us-west"},
map[string]interface{}{"usage_idle": 90.1, "usage_user": 9.9},
time.Now(),
)
writeAPI.WritePoint(point)
// 或批量：
points := []influxdb2.Point{point1, point2, point3}
writeAPI.WritePoint(points...)
- 所有
field值必须是string、bool、int64、uint64或float64；其他类型（如int）会 panic - 没显式传时间戳时，
NewPoint默认用time.Now()，但生产环境建议统一用纳秒级 Unix 时间戳避免时区歧义 -
WriteAPI默认启用异步缓冲（5s flush 或 1000 点触发），如需强一致性，调writeAPI.Flush()
QueryAPI 返回的 Record 没有字段名映射，得靠索引或列名取值
查出来的 Record 不像 ORM 那样自动绑定结构体，字段顺序固定但不直观。容易踩坑的是：直接用 r.Value() 拿不到原始 field 值（它返回的是 _value 列），而 r.Field() 返回字段名，r.ValueByKey("usage_user") 才是正解。
result, err := queryAPI.Query(ctx, `from(bucket:"my-bucket") |> range(start:-1h) |> filter(fn: (r) => r._measurement == "cpu")`)
if err != nil { panic(err) }
for result.Next() {
r := result.Record()
// ❌ 错误：r.Value() 是 _value 列，可能被重命名覆盖
// ✅ 正确：显式按字段名取
usageUser := r.ValueByKey("usage_user")
host := r.ValueByKey("host")
timestamp := r.Time()
}
- 如果用了
|> keep(columns: ["host", "usage_user"])，列顺序会变，但ValueByKey仍可靠 -
Record.Table()可拿到表元信息，用于调试列名和类型 - 聚合查询（如
mean()）后，_field列名可能变成_value，注意检查r.Field()输出
