不能直接用 std::ostream 或内存拷贝序列化 C++ 类到 BSON，因为 BSON 是带类型标签、长度前缀和字段名的二进制结构，而 C++ 类存在内存布局不匹配、非 POD 类型（如 std::string）、虚表指针、padding 等问题，直接 memcpy 或 reinterpret_cast 会导致解析失败或异常。
为什么不能直接用 std::ostream 或内存拷贝序列化 C++ 类到 BSON
因为 BSON 是带类型标签、长度前缀、字段名字符串的二进制结构，不是裸内存布局。C++ 类的成员顺序、padding、虚表指针、非 POD 类型（如 std::string、std::vector）都无法通过 memcpy 安全转出。直接 reinterpret_cast 会导致 mongocxx::exception 或服务端解析失败，常见错误是 invalid BSON document: size is too large 或字段缺失。
- BSON 文档必须以 int32_t length 开头，而类对象没有这个头部
-
std::string在内存中是 pointer+size+capacity 三段式，BSON 要的是 null-terminated UTF-8 字节流 - 嵌套对象/数组需递归编码，不能靠 flat layout 硬塞
- 时间、ObjectId、二进制等 MongoDB 特有类型，C++ 原生无对应表示
用 mongocxx::builder::stream::document 手动构建 BSON 文档最稳妥
这是官方驱动推荐方式，明确控制每个字段的类型和值，避免隐式转换陷阱。适用于字段数量固定、结构清晰的类（如 User、LogEntry）。
示例：将一个简单类转为 BSON
struct User {
std::string name;
int age;
std::chrono::system_clock::time_point created_at;
};
User u{"Alice", 32, std::chrono::system_clock::now()};
auto doc = mongocxx::builder::stream::document{};
doc << "name" << u.name
<< "age" << u.age
<< "created_at" << mongocxx::bsoncxx::types::b_date{u.created_at};
auto bson = doc.view(); // 得到 const bsoncxx::v_noabi::document::view
- 所有字段名必须是
const char*或字面量，不能是std::string.c_str()临时变量（生命周期问题） - 时间必须显式转成
b_date，否则会误为 int64 或 string - 浮点数默认为
b_double，如需b_decimal128需手动构造 - 嵌套对象用
mongocxx::builder::stream::open_document，别漏掉close_document
对复杂类或高频序列化场景，封装 to_bson() 成员函数更可控
避免每次调用都手写 builder 流，也防止不同模块对同一结构编码不一致。重点是把“类型映射”逻辑收口，而不是追求全自动反射。
立即学习“C++免费学习笔记（深入）”；
建议接口设计：
class Order {
public:
std::string id;
std::vector<Item> items;
double total;
bsoncxx::document::value to_bson() const {
using namespace bsoncxx::builder::stream;
document builder{};
builder << "_id" << bsoncxx::oid{id}
<< "items" << open_array;
for (const auto& item : items) {
builder << open_document
<< "name" << item.name
<< "qty" << item.qty
<< close_document;
}
builder << close_array
<< "total" << total;
return builder.extract();
}
};
- 返回
bsoncxx::document::value（含所有权），比view更安全，避免悬垂引用 - 数组必须用
open_array/close_array包裹，不能只写<< "items" << items（会调用隐式 operator<<，行为不可控） - 自定义类型（如
Item）也应提供自己的to_bson()，不要在父类里展开其字段 - 若字段可能为空（
std::optional），需显式判断是否写入，BSON 不支持 null 字段跳过
千万别碰运行时反射或宏代码生成（除非你维护自己的 ORM 层）
像 BOOST_FUSION_ADAPT_STRUCT 或 magic_enum + 模板递归看似能自动导出，但实际踩坑极多：
- 无法处理
std::shared_ptr、std::variant、引用成员等非常规类型 - 字段顺序依赖编译器 ABI，跨平台或升级 STL 后可能错位
- 错误信息全是模板展开堆栈，定位不到具体哪个字段出问题
- 性能开销大（动态 type_info 查找 + 多次小内存分配），比手写慢 3–5 倍
- 与 MongoDB 的
ObjectId、DBRef、Decimal128等类型无自然映射
真正需要自动化时，优先考虑 IDL 工具链（如 MongoDB 自家的 libbson + 自定义 codegen），而不是在运行时硬塞反射。
最易被忽略的一点：BSON 文档大小上限是 16MB，序列化前务必检查 to_bson().view().length()，尤其当类含 std::vector<uint8_t> 或 base64 字符串时——它们在 BSON 中会膨胀成原始字节，不压缩。
