# HL7 给出 v2 到 FHIR 的映射表，转换代码得自己写

> 用约 40 行 Python 把一条 ADT 示例消息转成合法的 Patient 资源，并避开新手常踩的 R4 与 R5 陷阱。

原文: https://fdetimes.net/zh/guides/hl7-v2-to-fhir-conversion-python/

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 资源。

```bash
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 步：编写一条示例消息

下面这条消息是为本教程构造的，不是真实数据。

```python
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 开始计数的惯例。建议用第二种，这样代码里的编号和文档中的字段编号一致。

```python
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`。

```python
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 数据。

```python
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 字符串，可以按名称访问子组件，且不区分大小写。

```python
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` 到底是什么意思。

**本周动手试试:**

- 运行本文所有代码，然后把 PID-7 改成无效日期，看校验能否发现；如果不能，加上自己的日期检查
- 在示例消息中加入两个 OBX 段，写一个循环生成两个独立的 Observation
- 把脚本和测试消息集一起放到 GitHub，然后在简历中加一行：按 v2-to-FHIR IG（R4）把 PID 映射为 Patient

## 信源

- [python-hl7 - Easy HL7 v2.x Parsing](https://python-hl7.readthedocs.io/en/latest/)

- [Getting started — hl7apy tutorial](https://hl7apy.readthedocs.io/en/latest/tutorial/)

- [Message ADT_A01 to Bundle Map - HL7 Version 2 to FHIR v1.0.0](https://build.fhir.org/ig/HL7/v2-to-fhir/branches/master/ConceptMap-message-adt-a01-to-bundle.html)

- [Segment PID to Patient Map - HL7 Version 2 to FHIR v1.0.0](https://build.fhir.org/ig/HL7/v2-to-fhir/branches/master/ConceptMap-segment-pid-to-patient.html)

- [Mapping Guidelines - HL7 Version 2 to FHIR](https://hl7.org/fhir/uv/v2mappings/mapping_guidelines.html)

- [Message Maps - HL7 Version 2 to FHIR v1.0.0](https://hl7.org/fhir/uv/v2mappings/message_maps.html)

- [nazrulworld/fhir.resources (GitHub README)](https://github.com/nazrulworld/fhir.resources)
