PostgreSQL二进制COPY格式以11字节魔数PGCOPY\n\377\r\n\0开头，后跟标志位、头长度、字段描述块（含OID与修饰符），再是带长度前缀的行数据；所有长度为大端序，需ntohl()转换，字段类型须依OID按规范解包。
PostgreSQL二进制COPY格式的结构到底长什么样
它不是简单字节流，而是一个带魔数、字段描述块和行数据块的协议级格式。开头 11 字节固定魔数 PGCOPY\n\377\r\n\0（注意 \377 是八进制，即 0xFF），接着是标志位（16 位整数，通常为 0）、头长度（32 位，通常是 0x18）。之后才是字段数量、每个字段的 OID 和修饰符（用于类型推导），最后才是实际元组数据。
关键点在于：字段描述块只出现一次，但每行数据前都有一个 32 位长度前缀（表示该行字节长度），行内每个字段又以 32 位长度前缀开头——这些长度都是网络字节序（大端），必须用 ntohl() 转换。
常见错误现象：Invalid message type 或读到乱码，往往是没校验魔数、或忘了字节序转换导致长度解析错位，后续全部偏移。
如何用C++安全读取并还原int4、text、timestamp等常见类型
不能直接 reinterpret_cast，必须按 PostgreSQL 的二进制格式规范解包。例如：
立即学习“C++免费学习笔记（深入）”；
-
int4：4 字节大端有符号整数 → 用ntohl()转后强转int32_t -
text/varchar：先读 4 字节长度 L，再读 L 字节 raw data；它不以 \0 结尾，且可能含 \0 —— 必须用std::string(data, len)构造，不能用 C 字符串函数 -
timestamp（无时区）：8 字节大端整数，表示自 2000-01-01 00:00:00 UTC 起的微秒数；需转为std::chrono::system_clock::time_point时注意 epoch 偏移 -
bool：1 字节，值为 0 或 1，非 C++ 的 true/false
OID 是关键线索：字段描述块中每个字段带 atttypid（类型 OID），需查 PostgreSQL 系统表（如 pg_type）映射到具体类型。硬编码 OID（如 23→int4、25→text、1184→timestamptz）可行但脆弱；生产环境建议预加载 OID 映射表。
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
为什么直接用libpq的PQgetCopyData会更稳
自己解析二进制 COPY 容易漏掉边界条件：NULL 字段用 -1 长度标记、对齐填充（某些类型如 numeric 有内部结构）、数组/复合类型的嵌套格式。而 PQgetCopyData() 在 libpq 内部已处理魔数校验、长度解析、缓冲区管理，你只需按返回的 int 值判断状态（>0 是数据长度，0 是结束，-1 是错误，-2 是需要等待）。
实操建议：
- 调用
PQputCopyEnd()后，**必须循环调用PQgetCopyData()直到返回 0**，否则残留数据会卡在连接状态里 - 返回的数据指针由 libpq 管理，**不可长期持有或跨调用复用**，需立即 memcpy 或 move
- 若启用了 SSL，libpq 自动处理加解密后的二进制流，你不用额外干预
性能影响：libpq 封装几乎没有额外开销，反而避免了手动解析中的重复内存拷贝和边界检查失误。
遇到numeric、jsonb、geometry这类复杂类型怎么办
它们没有标准跨语言二进制 ABI，PostgreSQL 的二进制格式是服务器内部约定，文档极少公开细节。例如 numeric 是变长结构，含权重、小数位数、数字数组；jsonb 是自定义二进制树形结构；geometry（PostGIS）更是依赖 WKB 标准但带 PostgreSQL 扩展头。
务实做法：
- 优先走文本 COPY：设置
COPY ... TO STDOUT WITH (FORMAT text)，用 CSV 或制表符分隔，类型转换交给客户端 string parsing（如std::stod、nlohmann::json::parse） - 对
jsonb/xml等，服务端转成 text 再传输，比逆向解析二进制格式可靠得多 - 真要解析
numeric？参考 PostgreSQL 源码src/backend/utils/adt/numeric.c中numeric_recv()实现，但需同步维护其 ABI 兼容性——升级 PG 小版本都可能破坏
最容易被忽略的是：即使你完整实现了 numeric 解析，PostgreSQL 不保证二进制格式向后兼容；而文本格式只要 SQL 层语义不变，就始终可用。
