HL7 给出 v2 到 FHIR 的映射表,转换代码得自己写
用约 40 行 Python 把一条 ADT 示例消息转成合法的 Patient 资源,并避开新手常踩的 R4 与 R5 陷阱。
要点速览
- v2-to-FHIR 映射表只说明哪个字段对应哪里,转换逻辑要自己写。
- python-hl7 支持按规范中从 1 开始的编号访问字段,代码读起来和文档一致。
- v2-to-FHIR IG 基于 R4,而 fhir.resources 默认是 R5,因此要从 R4B 分支导入。
HL7 关于把 v2 消息转换为 FHIR 的官方指南写得很直白:它描述的是哪个字段对应哪个元素,而不是如何完成转换。它告诉你 PID-8 等同于 gender,但里面没有一行代码负责把字符串 M 变成 male。这部分要自己写。
如果你是医疗项目上的前线部署工程师(FDE),源系统发送 v2 消息,而你的产品读取 FHIR,那么中间这层转换总得有人来写。能写出这层代码、并讲清每个字段去向的人,就是数据一出偏差、客户集成团队第一个找的人。
本指南在一台笔记本上走完整个流程:解析一条 ADT 示例消息,读取 PID 段,按官方映射表转成 Patient 资源,再校验结果。代码大约 40 行。
需要准备什么?
Python 3 和三个库。python-hl7 是轻量库,可把 HL7 v2.x 消息解析为 Python 对象。hl7apy 理解 HL7 的 schema,需要交叉核对时很有用。fhir.resources 基于 Pydantic v2 构建 FHIR 资源。
python -m venv .venv && source .venv/bin/activate
pip install hl7 hl7apy fhir.resources
同时打开 HL7 v2-to-FHIR IG 的两个页面:ADT_A01 消息到 Bundle 的映射,以及 PID 段到 Patient 的映射。
第 1 步:编写一条示例消息
下面这条消息是为本教程构造的,不是真实数据。
MSG = "\r".join([
"MSH|^~\\&|LAB|HOSP_A|EHR|HOSP_A|202611190830||ADT^A01|MSG0001|P|2.5",
"PID|1||123456^^^HOSP_A^MR||NGUYEN^AN^VAN||19850412|M",
])
检查: 数一数 PID 行中的 |。第 3 个字段是 123456^^^HOSP_A^MR,第 5 个是姓名,第 7 个是出生日期,第 8 个是 M。数错一位,后面每一步都会出错,而且不会报错。
第 2 步:解析消息,按规范编号读取字段
对消息字符串调用 hl7.parse(),得到一棵对象树,有两种访问方式:当作从 0 开始索引的 Python 列表,或者像函数一样调用,沿用 HL7 从 1 开始计数的惯例。建议用第二种,这样代码里的编号和文档中的字段编号一致。
import hl7
h = hl7.parse(MSG)
pid = h.segment("PID") # PID 只出现一次
print(pid(3)(1)) # PID-3 的第一个重复
print(str(pid(5)), str(pid(7)), str(pid(8)))
segment() 是一个快捷方法,适用于在消息中只出现一次的段,例如 PID 或 MSH。检查: 第一行打印患者 ID 及 ^ 分隔符后的各组件;第二行打印姓名、出生日期和 M。
第 3 步:把 PID 映射为 Patient
IG 规定,处理 ADT_A01 消息中的 PID 时要新建一个 Patient。在段这一层,映射表把 PID-3 对应到 identifier,PID-5 对应 name,PID-7 对应 birthDate,PID-8 对应 gender。
GENDER = {"M": "male", "F": "female", "U": "unknown"} # 简化版对照表
def v2_date(s):
return f"{s[0:4]}-{s[4:6]}-{s[6:8]}"
def pid_to_patient(pid):
mrn = str(pid(3)(1)).split("^")[0]
parts = str(pid(5)).split("^")
return {
"resourceType": "Patient",
"identifier": [{"value": mrn}],
"name": [{"family": parts[0],
"given": [p for p in parts[1:3] if p]}],
"birthDate": v2_date(str(pid(7))),
"gender": GENDER.get(str(pid(8)), "unknown"),
}
这是简化版:没有处理转义序列,忽略了 PID-3 和 PID-5 的第二个重复,并假设出生日期总是 8 个字符。GENDER 表也做了删减:在真实项目中,必须对照客户系统实际使用的代码表核实。
第 4 步:按正确的 FHIR 版本校验
新手最容易在这一步出错。v2-to-FHIR IG 的版本是 1.0.0(STU1),基于 FHIR R4。而 fhir.resources 默认是 R5,R4B 和 STU3 作为旧版本保留。直接导入默认版本,就等于用 R5 的 schema 校验 R4 数据。
from fhir.resources.R4B.patient import Patient
patient = Patient.model_validate(pid_to_patient(pid))
print(patient.model_dump_json(indent=2))
按该库 README 的说明,model_validate 从 dict 构建 Patient。也不要把 R4B 和 R4 当成一回事:名字不同,是因为它们是不同的发布版本。映射到基础 Patient 以外的资源时,要再对照 IG 所用的 R4 定义核对一遍。
检查: 把 PID-7 改成 19851345,重新运行,看校验如何响应。如果仍然通过,不要以为数据没问题:在 v2_date 里加上自己的日期检查。
第 5 步:用理解 schema 的解析器交叉核对
python-hl7 不知道 PID-5 叫什么,只知道位置。hl7apy 用 parse_message 解析 ER7 字符串,可以按名称访问子组件,且不区分大小写。
from hl7apy.parser import parse_message
m = parse_message(MSG, find_groups=False)
print(m.pid.patient_name.to_er7())
hl7apy 默认会把段组织成 HL7 分组。传入 find_groups=False 可关闭这一行为,从而直接调用 m.pid。如果你安装的库版本中这个调用不同,请查阅 hl7apy 教程。检查: 打印出的字符串必须与第 2 步中 str(pid(5)) 的结果完全一致。
两个不同的解析器给出相同结果,就多了一层保证:你没有数错字段。
真实消息会在哪里让代码出错?
示例消息只有一个 PID。含多个 OBX 段的消息就不同了:按照映射指南,段的每次重复都要生成对应资源的一个新实例,因此 10 个 OBX 段会变成 10 个 Observation。
这时 segment() 快捷方法就不管用了。必须遍历整棵树,例如 [s for s in h if str(s[0]) == "OBX"],再逐个映射。
第二个出错点是 IG 没有映射的字段。指南允许添加本地映射,并鼓励通过 JIRA 把它们反馈给 HL7。
对 FDE 来说,每一条本地映射都应该是一项写成文档、经客户确认的决定,而不是悄悄藏在代码里的一个 if 语句。
这项技能在客户现场是什么样子?
医院项目启动时,第一件事是向客户要几条去标识化的示例消息,然后对每种消息类型跑一遍第 2 步和第 5 步。
产出是一张逐字段对照表,拿着这张表去和对方的集成团队开会。
这张表也是写进简历的最好证据。当 FDE 岗位描述提到 HL7、FHIR 或接口引擎时,一个包含一组测试消息、一个标注“遵循 v2-to-FHIR IG,R4”的 PID 到 Patient 函数,以及一个能抓出错误出生日期的测试的代码仓库,远比一句“熟悉医疗标准”有说服力。
解析是容易的部分。难的是和客户坐下来,确定他们医院 PID-8 里的 U 到底是什么意思。
这篇文章对你有帮助吗?
感谢你的反馈!
7 个信源
- python-hl7 - Easy HL7 v2.x Parsing
- Getting started — hl7apy tutorial
- Message ADT_A01 to Bundle Map - HL7 Version 2 to FHIR v1.0.0
- Segment PID to Patient Map - HL7 Version 2 to FHIR v1.0.0
- Mapping Guidelines - HL7 Version 2 to FHIR
- Message Maps - HL7 Version 2 to FHIR v1.0.0 · 2025-10-07
- nazrulworld/fhir.resources (GitHub README)