MongoDB 查询中精准投影嵌套字段：如何只返回子文档的特定字段

在 go 中使用 mgo 驱动查询 mongodb 时，可通过点号语法（如 `"stats.userstatus"`）在 `select()` 投影中精确指定嵌套结构中的单个字段，无需返回整个子文档；配合结构体字段标签正确映射，即可实现轻量、高效的字段级投影。

MongoDB 原生支持对嵌套文档（embedded document）的字段路径投影，mgo（v2）完全兼容该特性。你只需在 bson.M 投影中使用标准的点号（.）语法指定子字段路径（例如 "stats.userStatus"），MongoDB 服务端便会仅返回该字段，且 mgo 能自动将其反序列化到对应结构体字段中——前提是 Go 结构体字段的 bson 标签与路径严格匹配。

以下是一个可直接运行的完整示例，还原你的场景并聚焦于 Stats.UserStatus 的单字段投影：

type Stats struct {
    UserStatus string `json:"userStatus" bson:"userStatus"`
    // 其他字段（如 TotalLogins、LastActive 等）无需定义，因本次不投影
}

type User struct {
    ID         bson.ObjectId `json:"-" bson:"_id"`
    LastName   string        `json:"lastName" bson:"lastName"`
    FirstName  string        `json:"firstName" bson:"firstName"`
    Role       string        `json:"role" bson:"role"`
    Tags       []string      `json:"tags" bson:"tags"`
    Stats      Stats         `json:"stats" bson:"stats"` // 注意：此处 bson 标签必须为 "stats"
}

// 查询时仅需 lastName、firstName 和 stats.userStatus
type UserNameReport struct {
    LastName   string `json:"lastName" bson:"lastName"`
    FirstName  string `json:"firstName" bson:"firstName"`
    UserStatus string `json:"userStatus" bson:"stats.userStatus"` // ✅ 关键：bson 标签写成 "stats.userStatus"
}

func GetUserNameReport(session *mgo.Session, query bson.M) ([]UserNameReport, error) {
    c := session.DB("yourdb").C("users")

    projection := bson.M{
        "lastName":           1,
        "firstName":          1,
        "stats.userStatus":   1, // ✅ 服务端只返回此字段（而非整个 stats 子文档）
    }

    var results []UserNameReport
    err := c.Find(query).Select(projection).All(&results)
    return results, err
}

✅ 关键要点说明：

• 投影语法 "stats.userStatus": 1 是 MongoDB 官方支持的合法语法（自 2.6+），mgo 完全兼容；
• 结构体字段 UserStatus 的 bson 标签必须显式写为 "stats.userStatus"，才能让 mgo 正确将 BSON 字段 stats.userStatus 映射到该字段；
• 不需要在 UserNameReport 中定义完整 Stats 结构体——只需按需定义扁平化字段，并用点号路径标注 bson 标签；
• 若 stats 是数组（如 []Stats），"stats.userStatus" 会投影每个数组元素中的 userStatus 字段（MongoDB 自动展开）；
• 投影中未包含的字段（包括 _id）默认不返回；如需排除 _id，显式设为 "_id": 0。

⚠️ 注意事项：

• 确保 MongoDB 版本 ≥ 2.6（推荐 ≥ 3.6）；旧版本对嵌套投影支持有限；
• 字段路径区分大小写，bson 标签中的大小写必须与数据库中存储的字段名完全一致；
• 若 stats 字段可能为 null 或缺失，对应 UserStatus 将被设为零值（空字符串），建议业务层做非空判断；
• mgo.v2 已归档，生产环境建议迁移到官方驱动 mongo-go-driver，其投影语法一致（options.Find().SetProjection()），且更安全稳定。

通过这种“字段路径 + 精准标签”的组合方式，你既能享受 MongoDB 的高效服务端投影能力，又能保持 Go 结构体的简洁性与类型安全性。