InsertOne 必须传 context.Context，应复用请求上下文并设超时；结构体需显式 bson 标签；InsertedID 需类型断言；默认 WriteConcern 有丢数据风险，生产环境应设 Majority。
InsertOne 函数必须传入 context.Context
不传 context.Context 会直接编译失败，因为 Go driver 的 InsertOne 签名强制要求第一个参数是 context.Context。很多人照着旧文档或 Python 思路写，漏掉这个，报错类似 not enough arguments in call to collection.InsertOne。
实际用法中，别硬写 context.Background() 就完事——如果操作在 HTTP handler 或定时任务里，应该复用传入的 ctx，方便超时控制和取消传播：
result, err := collection.InsertOne(ctx, bson.M{"name": "alice", "age": 30})
- 用
ctx.WithTimeout()包一层更稳妥，比如ctx, cancel := context.WithTimeout(r.Context(), 5*time.Second) - 不要在循环里反复调用
context.Background()，容易掩盖上下文生命周期问题 - 测试时可用
context.TODO()，但生产环境禁用
插入结构体时得加 BSON 标签，否则字段全为空
Go struct 默认不会自动映射到 BSON 字段名，InsertOne 写入的是空文档或只含零值，常见现象是 MongoDB 里看到 {} 或 {"_id": ObjectId(...)}，其他字段消失。
必须为每个导出字段显式声明 bson tag：
立即学习“go语言免费学习笔记（深入）”；
Golang Uber Dig
下载
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器，提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象，支持命名依赖等
type User struct {
ID primitive.ObjectID `bson:"_id,omitempty"`
Name string `bson:"name"`
Age int `bson:"age"`
}
-
_id字段建议用primitive.ObjectID类型 +omitempty，避免手动 new 一个空 ID - 字段名大小写敏感：
Name对应"name"，不是"Name" - 嵌套结构体也要逐层打 tag，BSON 不会自动递归解析
InsertOne 返回的 InsertedID 是 interface{}，要断言成 ObjectID 才能用
返回值 result.InsertedID 类型是 interface{}，直接打印可能看到 ObjectIdHex("...")，但想用于后续查询或转换字符串时，不转型就 panic：
id := result.InsertedID.(primitive.ObjectID) // 注意类型断言
- 安全写法是用类型断言 + 检查 ok：
if oid, ok := result.InsertedID.(primitive.ObjectID); ok { ... } - 别用
fmt.Sprintf("%v", result.InsertedID)拼 ID 字符串，可能输出不可靠格式 - 如果插入时用了自定义
_id（比如字符串），InsertedID就是那个值，类型不一定是ObjectID
没设 WriteConcern 时默认是“尽力而为”，丢数据风险真实存在
默认配置下，InsertOne 成功返回 ≠ 数据已落盘。网络中断、主节点崩溃、写入未同步到多数节点都可能导致丢失，尤其在副本集或分片集群中。
生产环境务必显式配置 WriteConcern：
opts := options.InsertOne().SetWriteConcern(writeconcern.Majority())
-
writeconcern.Acknowledged()（默认）只保证主节点接收，不保持久化 -
writeconcern.Majority()保证多数节点写入成功，推荐用于关键业务 - 设太强（如
writeconcern.W(5)）可能拖慢响应，需权衡一致性与延迟
真正难处理的是写入后服务崩溃、但 MongoDB 已确认成功——这时候没有回滚机制，应用层得靠幂等设计兜底。
