用h5py写入结构化数组前必须显式定义dtype，如np.dtype([('x','f8'),('y','i4'),('label','S20')])，字符串须用固定长度字节类型（如'S32'），create_dataset时必须显式传入dtype参数，读取时字段名大小写和顺序需严格匹配，大文件应预分配并分块写入。
用 h5py 写入结构化数组前必须定义 dtype
直接把 NumPy 结构化数组（如 np.array([...], dtype=[('name', 'S10'), ('age', 'i4')])）丢进 HDF5，h5py 会报错：TypeError: Object dtype dtype('O') is not supported。这不是数据问题，而是没告诉 HDF5 “这个结构长什么样”。h5py 不接受 Python 的动态 object 类型，必须显式声明复合 dtype。
实操要点：
- 用
np.dtype显式构造，字段名、类型、字节对齐都要写清楚，比如np.dtype([('x', 'f8'), ('y', 'i4'), ('label', 'S20')]) - 避免用
np.recarray或自动推导的dtype，它们常含O类型或不兼容的字符串编码 - 字符串字段必须用固定长度字节类型（如
'S32'），不能用str或U（Unicode）——HDF5 5.x 原生不支持 UTF-8 字符串，除非用vlen，但那是另一套逻辑
create_dataset 时传入 dtype 参数，别依赖自动推断
HDF5 数据集创建是显式契约行为。即使你传入一个已带 dtype 的 NumPy 数组，h5py 仍可能因字段命名规则或对齐差异拒绝写入。最稳的方式是：在 create_dataset 调用中明确指定 dtype，且与数组 dtype 完全一致。
示例：
立即学习“Python免费学习笔记（深入）”；
import h5py
import numpy as np
<p>dt = np.dtype([('timestamp', 'f8'), ('value', 'i4'), ('tag', 'S16')])
data = np.array([(1.23, 42, b'OK'), (2.45, -17, b'ERR')], dtype=dt)</p><p>with h5py.File('sensor.h5', 'w') as f:</p><div class="aritcle_card flexRow">
<div class="artcardd flexRow">
<a class="aritcle_card_img" href="/xiazai/skill11526" title="Python Hardener"><img
src="https://img.php.cn/upload/skill/001/246/273/6adaf20dbae7c507.jpg" alt="Python Hardener" ></a>
<div class="aritcle_card_info flexColumn">
<a href="/xiazai/skill11526" title="Python Hardener">Python Hardener</a>
<p>通过完整的安全审查、代码整洁重构、健壮的错误处理、正确的日志记录以及完整的文档字符串覆盖，强化 Python 脚本。</p>
</div>
<a href="/xiazai/skill11526" title="Python Hardener" class="aritcle_card_btn flexRow flexcenter"><b></b><span>下载</span> </a>
</div>
</div><h1>✅ 正确：显式传 dtype，且 shape 匹配</h1><pre class='brush:python;toolbar:false;'>dset = f.create_dataset('readings', data=data, dtype=dt)
# ❌ 错误：省略 dtype，或 dtype 与 data 不一致，会出错写入后读取时字段名大小写和顺序必须严格匹配
HDF5 本身区分字段名大小写，且不保证字段顺序等价于 NumPy 视图顺序。如果你用 dset[:]['timestamp'] 读取，字段名拼写错一个字母就返回 KeyError；如果用布尔索引或切片再取字段，顺序不对可能导致数据错位。
关键提醒：
- 读取时用
dset['field_name']，不是dset['FIELD_NAME'] - 不要依赖
dset.dtype.names的输出顺序做索引，应始终用字段名访问 - 若需转换为 Pandas DataFrame，用
pd.DataFrame(dset[:])即可，它会自动识别字段名；但手动构造列顺序时，务必按dset.dtype.names的实际顺序来
大文件写入要分块，别一次性 create_dataset 全量数据
结构化数据一旦超过几百 MB，直接传整个 NumPy 数组给 create_dataset 会吃光内存，还可能触发 HDF5 的默认 chunking 策略导致后续读写变慢。正确做法是预分配数据集，再分块写入。
操作方式：
- 先调用
f.create_dataset(..., shape=(N,), dtype=dt, chunks=True)，让 HDF5 自动选 chunk size，或手动设chunks=(10000,) - 用
dset[start:end] = chunk_data分批赋值，chunk_data 的dtype必须和 dset 完全一致 - 避免用
np.append或反复resize——结构化数据 resize 很容易破坏字段对齐，出 silent corruption
字段对齐、字符串长度、chunk 边界、dtype 显式声明——这些不是可选项，是 HDF5 结构化 I/O 的硬性前提。漏掉任何一个，轻则读不出数据，重则文件损坏且不可逆。
