to_dict()的orient参数决定字典结构：'dict'按列组织（列名→{索引:值}），'list'按列组织（列名→值列表），'records'按行组织（每行→{列名:值}字典），'index'按索引组织（索引→{列名:值}）。
to_dict() 的 orient 参数怎么选
选错 orient 是最常导致结果“不是你想要的字典”的原因。它不决定“能不能转”，而决定键和值的组织逻辑。
-
orient='dict'（默认）：列名为外层 key，每列数据转成 {index: value} 形式 —— 适合按列查数据 -
orient='list'：列名为 key，值是该列所有元素组成的list—— 适合后续传给 JSON 或批量处理 -
orient='records'：生成一个list，每个元素是行对应的 {列名: 值} 字典 —— 最贴近“每行一条记录”的直觉，也最常用在 API 返回或写入数据库前 -
orient='index'：用 DataFrame 的 index 做外层 key，值是该行的 {列名: 值} 字典 —— 当 index 有业务含义（如用户 ID）时才真正有用
别硬记，记住一个口诀：想按列组织就用 dict 或 list，想按行组织就用 records 或 index。
含 NaN 值时 to_dict() 的行为
Pandas 默认把 NaN 转成 Python 的 None，但这是隐式转换，容易在下游引发 TypeError（比如传给 requests.post 的 json 参数时）。
- 如果目标系统不接受
None（如某些 REST API 要求空字符串或 0），得先用df.fillna("")或df.fillna(0)预处理 -
to_dict()不会报错也不提醒你有NaN，得自己检查：df.isna().any().any() - 注意
object类型列里的NaN和字符串"NaN"是两回事，后者不会被自动识别为缺失值
性能敏感场景下 to_dict() 的取舍
对百万行以上的 DataFrame，to_dict(orient='records') 比循环 + dict() 快，但比 to_numpy() 慢一个数量级 —— 因为它要构造大量 Python 字典对象。
- 纯数值计算后只需导出结构化数据？优先考虑
df.to_numpy().tolist()+ 手动 zip 列名，内存和速度都更优 - 如果只是临时调试，用
df.head(3).to_dict('records')，别对全量数据调用再切片 - 避免嵌套调用：
json.dumps(df.to_dict('records'))比df.to_json(orient='records')多一次序列化，且前者无法控制日期/NaN 输出格式
多级索引或列名含特殊字符时的坑
to_dict() 本身不处理列名合法性，但下游系统（比如 JSON 解析器、SQL 字段映射）可能对 key 名敏感。
- 列名含空格、点号、中文或以数字开头？转出来的字典 key 就是那样，但用
dict['user.name']会语法错误，得改用dict.get('user.name') - 多级列（
MultiIndex）默认转出来是 tuple 形式 key，如('sales', '2023')—— 大部分 JSON 库不支持 tuple 作 key，必须先df.columns = ['_'.join(col) for col in df.columns] - 索引名（
df.index.name）不会自动进入字典，除非你用orient='index'并确保 index 有 name；否则它就丢了
真正麻烦的从来不是“怎么转”，而是转完之后那个字典能不能被下一手代码安静地接住 —— 多看一眼 key 类型、缺失值表示、嵌套深度，比查文档还管用。
