PyMongo读取BSON int64时会静默转为有符号Python int，导致无符号大整数（如≥2⁶³）溢出为负数；根本解决法是写入时存字符串并用字符串查询，或读取后手动校验修复：raw_ts + 2**64。
PyMongo默认把int64转成Python int，但不保证精度
PyMongo 从 MongoDB 读取 Int64 字段（比如 ObjectId 时间戳、自增ID、分片键）时，底层用 BSON 的 int64 类型传输。问题在于：Python 的 int 虽然任意精度，但 PyMongo **默认会把 BSON int64 解包成 C long 再转 Python int**——在 64 位系统上看似安全，一旦原始值是无符号的（如 9223372036854775808），就会触发有符号溢出，变成负数。
常见现象：collection.find_one({"_id": "xxx"})["ts"] 返回 -9223372036854775808，而 MongoDB 中实际存的是正的 9223372036854775808。
- 根本原因不是 Python 整数溢出，而是 PyMongo 的 BSON 解码器在处理无符号 int64 时，错误映射到有符号范围
- 这个行为与系统架构无关（即使在 64 位 Python 下也会发生）
- 只影响直接读取的
Int64字段，不影响字符串化存储的 ID（如str(ObjectId())）
用 BSON.Int64 显式包装写入，读取时仍需检查类型
写入时用 BSON.Int64 强制标记类型，能避免驱动自动降级，但读取端不会自动还原——PyMongo 仍返回普通 int，且已丢失无符号语义。
正确做法是：写入时统一走字符串，或读取后立刻校验是否为负且绝对值过大：
立即学习“Python免费学习笔记（深入）”；
from bson import Int64
<h1>写入（推荐仅用于必须数值运算的场景）</h1><p>coll.insert_one({"ts": Int64(9223372036854775808)})</p><h1>读取后检查</h1><p>doc = coll.find_one()
raw_ts = doc["ts"]
if isinstance(raw_ts, int) and raw_ts < 0 and abs(raw_ts) > 2**63 - 1:</p><h1>实际应为无符号 int64，手动修复</h1><pre class="brush:php;toolbar:false;">ts = raw_ts + 2**64
- 不要依赖
type(doc["ts"]) is int判断安全性——它永远是int -
Int64包装只影响写入序列化，不改变读取反序列化逻辑 - 修复公式
raw_ts + 2**64仅适用于原始值在[2^63, 2^64)区间
最稳方案：MongoDB 层面存字符串，绕过 BSON int64
真正规避问题的路径不是修 PyMongo，而是让数据不经过它的 int64 解码路径。MongoDB 原生支持字符串字段，且排序、索引、查询性能几乎无损（尤其加了 {sparse: true} 或 TTL 索引后）。
- 写入前把大整数转
str()：{"ts": str(9223372036854775808)} - 查询时用字符串比较（
{"ts": {"$gt": "9223372036854775800"}}），注意补零对齐或用固定长度格式 - 需要数值计算时，用
int()转——此时 Python 不会截断，因为源头没丢精度 - 已有数据迁移可用
update_many(..., [{"$set": {"ts": {"$toString": "$ts"}}}])（MongoDB 4.0+）
为什么不用 codec_options？它不解决根本问题
有人试过给 Collection 配 codec_options=CodecOptions(...) 或自定义 TypeCodec，但 PyMongo 的 Int64 codec 只控制写入，**读取阶段 BSON 解码器早已把字节流转成 Python int，codec 无从介入**。
换句话说：你无法通过配置让 PyMongo 把 BSON int64 解成 int 以外的类型；所有“保留原样”的尝试，最终都落在应用层做补偿判断。
- 第三方库如
umongo或mongomock也不改变这一底层限制 - 如果必须保持数值类型且跨语言兼容（比如和 Node.js 共享 schema），字符串方案仍是事实标准
- 真正的坑是：这个溢出是静默的，没有 warning，也没有 exception，只在业务逻辑出错时才暴露
