必须先确认驱动版本≥v1.12、连接已建立且权限正确，再用opendownloadstream或opendownloadstreambyname按_id或filename读取；流需显式close，禁止io.readall大文件。
GridFS 文件读取前必须确认驱动版本和连接状态
Go 官方 MongoDB 驱动 v1.12+ 才完整支持 gridfs.Bucket 的流式读取；低于该版本（比如 v1.7）调用 Find 或 OpenDownloadStream 会 panic 或返回空结果。连接必须已通过 mongo.Connect 建立，且数据库名、集合前缀（bucketName）要与写入时一致，默认是 fs。
常见错误现象：panic: runtime error: invalid memory address —— 多因 bucket 初始化失败却未检查错误；或传入了 nil context。
- 初始化
bucket时务必检查err：bucket, err := gridfs.NewBucket(db, options.GridFSBucket().SetName("fs")) - 不要复用
context.Background()做长耗时读取，改用带 timeout 的context.WithTimeout(ctx, 30*time.Second) - 确保 MongoDB 用户有对应数据库的
read权限，否则OpenDownloadStream返回nil且无明确错误提示
用 OpenDownloadStream 按 _id 或 filename 精确读取文件
OpenDownloadStream 是最常用方式，它返回一个 *gridfs.DownloadStream，底层封装了 chunk 合并逻辑，无需手动拼接 fs.chunks。
使用场景：已知文件唯一标识（_id ObjectId 或 filename 字符串），需完整读取内容。
- 按
_id查：stream, err := bucket.OpenDownloadStream(ObjectIDHex("65a1b2c3d4e5f67890123456")) - 按
filename查：stream, err := bucket.OpenDownloadStreamByName("report.pdf") - 若文件不存在，
err为mongo.ErrNoDocuments，不是nil；务必判断而非忽略 -
stream必须显式Close()，否则可能泄漏 goroutine 和内存 —— 即使读取失败也要 deferstream.Close()
读取大文件时避免一次性加载到内存
GridFS 文件可能达 GB 级，io.ReadAll(stream) 会导致 OOM。应按需流式处理，比如直接写入磁盘、转发 HTTP 响应或分块校验。
- 写入本地文件：
dst, _ := os.Create("out.jpg")<br>io.Copy(dst, stream)<br>dst.Close()<br>stream.Close() - HTTP 流式响应（搭配
w.Header().Set("Content-Type", "image/jpeg")）：http.ServeContent(w, r, filename, modTime, stream)
- 若需校验 SHA256，用
hash.Hash包边读边计算，不要先全读再哈希 - 注意
stream.Read()可能返回io.EOF或部分字节，需循环处理，io.Copy内部已处理该逻辑，优先用它
为什么 Find 查询不能直接拿到文件内容？
bucket.Find 只查 fs.files 元数据文档（如 filename, length, uploadDate），不包含实际二进制数据。它的作用是筛选、分页、获取元信息，不是读取主体。
- 错误做法：
cur, _ := bucket.Find(ctx, bson.M{"filename": "log.txt"})<br>var fileDoc struct{ Filename string `bson:"filename"` }<br>cur.Next(ctx)<br>cur.Decode(&fileDoc) // 这里只有元数据，没有 content - 正确链路：先
Find获取_id→ 再用OpenDownloadStream读内容 - 如果只关心是否存在或大小，
Find+Decode足够，比打开 stream 更轻量
真正容易被忽略的是：OpenDownloadStreamByName 在多个同名文件存在时，只返回最新上传的那个 —— 它内部按 uploadDate 降序取第一个，不会报错也不会提醒。需要精确版本控制时，必须用 _id。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
