Python生成HL7 CDA文件：结构解析、代码实现与踩坑指南

简介：这是一款专为医疗信息化场景设计的轻量工具，旨在生成符合HL7 CDA标准（临床文档架构）的XML文件，面向需要处理电子病历、检验报告等结构化数据的开发与实施人员，可显著降低手工编写CDA文档的难度与出错率，并提升跨系统共享的效率。资源包共5个文件：EXE可执行程序用于生成与解析CDA，示例XML展示最小化标准实例，XSL样式表可在浏览器中格式化渲染，CSV提供LOINC诊断编码映射，PDF手册则完整说明部署与使用，整体压缩后仅443KB。目前已有545人学习/下载，属于即下即用的实用型工具包。通过运行带GUI的EXE、对照最小示例与手册，读者既能快速产出合规CDA文档，也能拆解文档结构、模板字段和编码映射，为院内系统集成或二次开发提供可复用参考。

1. 生成 CDA 文件的小程序：先搞明白它到底在解决什么问题

接到“写一个小程序生成 CDA 文件”这个需求，多半是医院在做电子病历共享、互联互通评审，或者区域平台要求把出院小结、检验报告上报成标准 XML。CDA 全称 Clinical Document Architecture，是 HL7 组织定义的临床文档结构标准，落地到工程上就是一个 XML 文件，但它的约束比普通 XML 严格得多。某医院报一份出院小结被平台退回来三次，一次说 templateId 不匹配，一次说时间格式不带时区，一次说诊断代码没按 ICD-10 编码。标题里的“小程序”不是微信小程序，而是指一个本地命令行小工具：读入结构化临床数据，输出一份能通过校验的 CDA 文档。适合正在做医院信息集成、区域平台对接、或者被领导安排“把报告转成标准格式”的后端工程师看。

2. 写生成器之前，先拆 CDA 文档结构和模板 ID

很多团队拿到 CDA 需求的第一反应是找个 XML 模板改改，结果改出来的文档平台不认。CDA 不是普通 XML，它的 Header 部分描述了“这份文档是谁、为谁、记录了什么”，Body 部分承载临床内容，而整份文档的合法性由模板 ID 和代码系统决定。这章先把结构和选型讲清楚，再动手写代码，可以少走很多弯路。

2.1 CDA 文件的最小骨架：Header 里的固定元素与 typeId

CDA R2 的根元素是 ClinicalDocument，命名空间是 urn:hl7-org:v3。整个文档分成 Header 和 Body 两段，Header 是文档元数据，Body 是临床内容。Header 里的元素分必选和可选，但实际接入平台时，几乎每个项目都会在此基础上叠加自己的模板约束。

表：CDA Header 常用元素清单

typeId 是固定值，root 和 extension 都不能改，解析器看到这个值就知道按 CDA R2 处理。templateId 则是接入平台给的模板标识，这个值直接决定平台用什么规则校验你的文档。常见错误是以为 templateId 也可以自己随便编一个，结果平台返回“模板不匹配”。

2.2 Structured Body 与 Non-XML Body：两种内容承载方式怎么选

CDA Body 有两种形态。Structured Body 是结构化的，由多个 section 组成，每个 section 里有人类可读的 text 和机器可读的 entry，平台能从里面抽出诊断、用药、检验结果等结构化数据。Non-XML Body 则是把 PDF、图片等原始文件用 Base64 编码嵌入 XML，平台能看但不能直接抽取数据。

实际项目里这两者不是二选一。某区域平台的要求是：结构化数据必须放在 Structured Body 里供系统抓取，原始报告 PDF 同时以 Non-XML Body 嵌入存档。我一般建议先做 Structured Body，因为结构化数据的映射工作量大，越早暴露问题越好；Non-XML Body 相对简单，留到后面处理也不迟。

判断用哪种 Body 也看场景。如果只是院内留档、人工查阅，Non-XML Body 嵌入 PDF 就够了。如果要做数据上报、互认、统计分析，必须做 Structured Body。平台通常会在对接文档里写明要求，按对方文档来最稳妥。

2.3 两条实现路线：XML 模板替换 vs 对象树构建

生成 CDA 的主流做法有两种。一是用模板引擎，比如 Jinja2 或 FreeMarker，把 XML 写成模板，用变量替换数据。二是用编程语言直接构建对象树，比如 Python 的 lxml 或 Java 的 JAXB，先构造元素节点再序列化成 XML。

模板路线的优点是上手快，结构固定的场景下代码量少；缺点是列表循环、条件分支一多，模板里全是 if 和 for，改起来容易出错。对象树路线的优点是命名空间、属性都通过 API 设置，不容易漏，数据结构复杂时更好维护；缺点是最开始写的代码多一点。

我最开始做生成器时直接上了模板引擎，结果模板里命名空间写错一个前缀，排查了大半天。后来改成用 lxml 构建对象树，虽然代码多了几十行，但每个节点都清清楚楚。如果你的项目只需要固定一两个模板，用模板替换够用；如果要做多文档类型、多院区多模板适配，建议直接走对象树路线。

表：两种实现路线对比

3. 从零生成一份可校验的 CDA：最小可运行代码逐段拆解

选定了 lxml 对象树路线，这章直接写代码。先构造 Header，再往 Structured Body 里填诊断信息，最后讲批量生成时命名空间和版本的坑。代码都按可运行的标准写，复制到本地改一改就能用。

3.1 Python + lxml 生成 CDA Header 的最小实现

下面的代码生成一份最简 CDA Header，包含 typeId、templateId、id、code、effectiveTime、recordTarget 等关键元素。

from lxml import etree from uuid import uuid4 from datetime import datetime NSMAP = {None: "urn:hl7-org:v3"} # 默认命名空间 def build_header(): doc = etree.Element("ClinicalDocument", nsmap=NSMAP) # typeId 固定，用于识别 CDAR2 type_id = etree.SubElement(doc, "typeId") type_id.set("root", "2.16.840.1.113883.1.3") type_id.set("extension", "POCD_HD000040") # templateId：接入平台给定，必须一字不差 tpl = etree.SubElement(doc, "templateId") tpl.set("root", "2.16.840.1.113883.10.20.22.1.1") # 文档实例 ID：每次生成都用 UUID，保证唯一 doc_id = etree.SubElement(doc, "id") doc_id.set("root", str(uuid4())) # 文档类型 code，出院小结对应 LOINC 18842-5 code = etree.SubElement(doc, "code") code.set("code", "18842-5") code.set("codeSystem", "2.16.840.1.113883.6.1") code.set("codeSystemName", "LOINC") code.set("displayName", "Discharge summary") title = etree.SubElement(doc, "title") title.text = "出院小结" # 文档生成时间，必须带时区偏移 eff = etree.SubElement(doc, "effectiveTime") eff.set("value", datetime.now().strftime("%Y%m%d%H%M%S+0800")) conf = etree.SubElement(doc, "confidentialityCode") conf.set("code", "N") conf.set("codeSystem", "2.16.840.1.113883.5.25") # recordTarget：患者信息 rt = etree.SubElement(doc, "recordTarget") pr = etree.SubElement(rt, "patientRole") pid = etree.SubElement(pr, "id") pid.set("root", "2.16.840.1.113883.19.5") pid.set("extension", "P123456") pn = etree.SubElement(pr, "patient") name = etree.SubElement(pn, "name") name.text = "张三" gender = etree.SubElement(pn, "administrativeGenderCode") gender.set("code", "M") gender.set("codeSystem", "2.16.840.1.113883.5.1") birth = etree.SubElement(pn, "birthTime") birth.set("value", "19800215") return doc

代码里最需要注意的是 nsmap 的设置，{None: "urn:hl7-org:v3"}让默认命名空间带上 HL7 V3 的 URI，子元素不需要加前缀，生成出来的 XML 是干净的。typeId 的 root 和 extension 是固定值，解析器靠这个识别文档标准。id 用 UUID 字符串是为了保证每份文档实例唯一，同样内容的文档重新生成也该换一个新 id。

effectiveTime 格式是 HL7 时间戳，%Y%m%d%H%M%S+0800生成的结果类似 20240308153000+0800。这里强烈建议把时区写死为 +0800，不要依赖服务器默认时区，后面避坑章节会展开说。administrativeGenderCode 的代码系统 2.16.840.1.113883.5.1 是 HL7 维护的性别编码，M 代表男，F 代表女，不能直接填中文。

主程序输出 XML 到文件时，要按二进制写：

xml_bytes = etree.tostring( build_header(), xml_declaration=True, encoding="UTF-8", pretty_print=True ) with open("sample_cda.xml", "wb") as f: f.write(xml_bytes)

这里用wb二进制模式而不是文本模式，是因为 Windows 下文本模式会把 UTF-8 编码重新转成 GBK，导致声明和实际字节不一致，平台解析时直接乱码。这个写法对跨平台部署尤其重要，服务跑在 Linux 上问题不大，但本地 Windows 调试时就能避免很多无用功。

3.2 往 Structured Body 里写诊断：section 与 observation 的层级

Header 完成后，继续往文档里加 Structured Body。下面代码演示了一个带诊断 section 的结构化 Body。

def build_body(doc): sbody = etree.SubElement(doc, "structuredBody") component = etree.SubElement(sbody, "component") section = etree.SubElement(component, "section") # section.code 在对接模板里通常会指定 LOINC sec_code = etree.SubElement(section, "code") sec_code.set("nullFlavor", "NI") # 先用占位，接入时换成模板要求值 sec_code.set("codeSystem", "2.16.840.1.113883.6.1") sec_title = etree.SubElement(section, "title") sec_title.text = "诊断" sec_text = etree.SubElement(section, "text") sec_text.text = "社区获得性肺炎，左肺下叶" # entry 是机器可读部分，observation 表示一条诊断观察 entry = etree.SubElement(section, "entry") obs = etree.SubElement(entry, "observation") obs_code = etree.SubElement(obs, "code") obs_code.set("code", "282825002") obs_code.set("codeSystem", "2.16.840.1.113883.6.96") obs_code.set("displayName", "Diagnosis") value = etree.SubElement(obs, "value") # xsi:type 必须用完整命名空间写法，不能用 "xsi:type" value.set("{http://www.w3.org/2001/XMLSchema-instance}type", "CD") value.set("code", "J18.9") value.set("codeSystem", "2.16.840.1.113883.6.3") value.set("displayName", "肺炎，未特指")

section 里的 code 我用了 nullFlavor="NI" 占位，这是有意为之。CDA 规范允许 section.code 为空，但实际对接模板通常会指定具体 LOINC，比如出院诊断可能要求某个固定值，接入时把nullFlavor删掉换成code和displayName即可。这里的占位写法保证 XML 合法，同时提醒你这里需要按模板参数补全。

observation 的 value 元素用了{http://www.w3.org/2001/XMLSchema-instance}type属性来指定值类型为 CD，这是 CDA 里很常见也最容易写错的地方。如果写成value.set("xsi:type", "CD")，lxml 不会自动补命名空间，生成出来的 XML 会缺少 xsi 前缀声明，Schema 校验直接报 unbound prefix。

诊断值用 ICD-10 编码 J18.9，代码系统是 2.16.840.1.113883.6.3。医院 HIS 里存的中文诊断和 ICD 编码经常对不上，这部分映射工作要在数据进生成器之前完成，不要指望 CD 类型里只填 displayName 就能通过校验，平台抽数据看的还是 code。

3.3 批量生成几十份文档时，命名空间前缀与版本号怎么处理

lxml 在默认情况下会给无前缀命名空间生成 ns0 前缀，比如<ns0:ClinicalDocument>。语义上没有错，Schema 校验也能过，但有的平台解析器写得不严谨，只认固定的元素名，看到 ns0 前缀直接解析失败。解决方式是在创建根元素时指定 nsmap，如前面的代码所示，把 None 映射到 urn:hl7-org:v3，序列化出来就没有前缀。

另一个批量生成容易忽略的是版本管理。同一份患者的多份修订文档，不应该每次都用新 id，而应该用 setId 标识同一文档族，versionNumber 递增。做法如下：

set_id = etree.SubElement(doc, "setId") set_id.set("root", "2.16.840.1.113883.19.5.8888.123") set_id.set("extension", "20240308") ver = etree.SubElement(doc, "versionNumber") ver.set("value", "2") # 从业务系统读取上一次版本号 +1

这样平台能区分修订记录，而不是把新文档当成独立文档存两份。 setId 的 root 可以是产品线固定的 OID，extension 可以用日期或者业务主键。versionNumber 是字符串类型，直接填数字字符串即可。

4. 真实临床数据映射：从 HIS 字段到 XML 节点的转换参数

代码骨架搭好后，真正花时间的是把门诊、住院、检验系统的字段映射到 CDA 节点上。这章给出一份常用映射表和三个最常返工的参数处理方式。

4.1 常用 HIS 字段到 CDA 节点的映射表

不同医院的 HIS 表结构差异很大，但映射关系有共性。我一般会先做一张映射表发给对接方确认，确认后再写转换代码。

表：常见 HIS 字段与 CDA 节点映射

映射表落地时注意两点。一是就诊科室的位置在不同模板里有差异，有的放在 componentOf/encompassingEncounter 里，有的放在 custodian 相关的组织结构里，需要按对接方模板确认。二是医生为空时不要直接跳过 author 元素，CDA 规范要求至少有一个 author，可以用系统账号或 default value 兜底。

4.2 代码系统归一：性别、诊断、检验结果三个重灾区

CDA 对取值的要求是“代码 + 代码系统”，不接受中文原始值。性别在 HIS 里存的是“男”“女”，到 CDA 里要映射成 HL7 的 M、F、U（未知）。诊断在 HIS 里可能存的是带标点的 ICD-10 描述，生成前要清洗成标准编码。检验项目是重灾区，LIS 里几乎全是本地码，极少有 LOINC。

处理检验项目的常见做法是本地码 + translation 指向 LOINC。也就是说，原始 code 保留 LIS 本地编码，codeSystem 用本机构申请的 OID，然后加一个 translation 元素，表示“这个本地码等价于某个 LOINC 编码”。

code.set("code", "LIS-BG-001") code.set("codeSystem", "2.16.840.1.113883.19.5.998") code.set("displayName", "白细胞计数") trans = etree.SubElement(code, "translation") trans.set("code", "58410-2") trans.set("codeSystem", "2.16.840.1.113883.6.1") trans.set("displayName", "WBC")

这样既保留了原始数据的可追溯性，又给平台提供了标准编码入口。如果本地码确实没有对应 LOINC，不要硬编一个上去，宁可只带本地码，让平台那边知道这个项目还没映射完成。编造 LOINC 映射比不映射更糟，因为解析方会按 LOINC 去匹配规则，匹配错了影响临床决策。

4.3 中文 PDF 报告嵌入：Non-XML Body 的 Base64 写法

有些平台要求原始报告全文嵌入 CDA，一般是 PDF。这时候用 nonXMLBody：

import base64 with open("report.pdf", "rb") as fp: b64 = base64.b64encode(fp.read()).decode("ascii") nxml = etree.SubElement(doc, "nonXMLBody") text = etree.SubElement(nxml, "text") text.set("mediaType", "application/pdf") text.set("representation", "B64") text.text = b64

mediaType 要用 IANA 注册的标准类型，application/pdf、image/jpeg 最常见。representation 固定写 B64，说明内容是 Base64 编码。这里有个隐藏问题：部分生成器把 Base64 字符串按每 76 个字符插入换行，CDA 规范允许换行，但有的平台解析时没做换行处理，导致解码失败。Python 的 base64.b64encode 默认不换行，这是最安全的。

嵌入前要先确认平台有没有文件大小限制。常见限制在 10MB 到 20MB 之间，如果报告扫描件很大，我一般会先用 PDF 压缩工具处理到 2MB 以内再嵌入。还有一点，Base64 只能嵌“文件”不能嵌“路径”，不要图省事把文件路径塞进去，平台不可能从你的服务器路径去读文件。

5. CDA 生成中的五个典型翻车现象：现象、原因、解决

这章写的是生成 CDA 文件时最常见的五类故障，每一条都是真实对接过程中被平台打回来的典型案例。按“现象 → 原因 → 解决”的顺序写，排错时可以直接对照。

5.1 平台反馈 templateId 不匹配或模板缺失

现象：生成的 XML 用 Schema 校验完全通过，但上传到区域平台后被退回，报错信息是 templateId 不存在或者与预期模板不匹配。

原因：CDA 规范本身只要求 templateId 存在，但具体值必须由对接平台指定。很多开发者在写生成器时随手填了一个模板 ID，或者在网上复制的示例值，平台按自己的模板库比对时自然找不到。

解决：找对接方要“电子病历共享文档模板”或“CDA 模板清单”，把 templateId 的 root 和 extension 一字不差填进代码。注意平台可能要求多个 templateId，比如一个标识文档总体类型，一个标识具体业务的约束模板，两个都写上且顺序不能乱。拿到模板后，把 templateId 从配置读取，不要硬编码在代码里，后续平台升级模板时不用改代码。

5.2 effectiveTime 与就诊时间相差八小时

现象：文档里 effectiveTime 写的是 20140308120000，平台解析后变成 20140308040000，恰好差八小时。

原因：生成时没有带时区偏移，或者写的是 +0000，平台按 UTC 解析后换算到北京时间就少了八小时。服务器时区和数据库时区如果不一致，还会出现生成时间和入库时间两个结果。

解决：统一在程序入口用固定时区生成时间。

from datetime import datetime, timezone, timedelta cst = timezone(timedelta(hours=8)) now = datetime.now(cst).strftime("%Y%m%d%H%M%S+0800")

这段代码把时区固定为东八区，无论服务器实际时区是什么，生成的时间字符串都带 +0800。不要用datetime.now()直接格式化，因为它是服务器本地时间，部署到 UTC 的机器上就会出问题。CDA 里凡是时间字段，都建议用这个模式处理。

5.3 中文内容乱码或解析中断

现象：XML 声明写的是 UTF-8，平台也按 UTF-8 解析，但中文显示乱码，严重的直接报 parse error。

原因：文件写入时用了文本模式，Windows 环境下 Python 会按 GBK 编码写入，虽然 XML 声明写的是 UTF-8，实际字节是 GBK，解析器按 UTF-8 解码自然出错。另一种情况是 etree.tostring 时没指定 encoding，默认生成的是不带 XML 声明的字符串，别人拿到手不知道按什么编码读。

解决：序列化和写文件统一按前面的写法来，encoding="UTF-8"加wb二进制模式。写完文件后随手检查第一行，确保是<?xml version="1.0" encoding="UTF-8"?>，再检查字节里有没有乱码。一个小习惯：用file sample_cda.xml看一眼编码，能避免很多不必要的来回。

5.4 CDA 里嵌了 PDF 但平台打不开

现象：平台能解析 XML，但点击预览报告时提示文件损坏或空白。

原因：最常见的是 Base64 内容中间被插入了换行符，解析方解码时没有忽略换行。另一个原因是 mediaType 声明和实际内容不符，比如嵌的是 JPEG 扫描件但声明成 application/pdf。

解决：代码里用base64.b64encode(...).decode("ascii")，默认不换行。如果数据经过了别的环节，生成前检查一下字符串里有没有\n，有就替换掉。嵌入前本地先解码验证一次：

echo "这里是base64内容" | base64 -d > /tmp/check.pdf file /tmp/check.pdf

file命令能看出解码后的文件类型是否和 mediaType 一致。不一致就去检查源文件路径是不是拿错了。

5.5 文档 id 重复导致平台覆盖历史记录

现象：同一患者的第二次上报成功后，平台里查不到第一次的记录，只剩最新一条。

原因：document id 用了固定值，比如用患者 ID 或某个业务单号直接作为 id 的 extension，平台按 id 做唯一性判断，新文档覆盖旧文档。

解决：id 每次生成都用 UUID，保证全局唯一。setId 用于表示“这是同一业务文档的不同版本”，versionNumber 递增。三者配合：

doc_id.set("root", str(uuid4())) set_id.set("root", "2.16.840.1.113883.19.5.8888.123") set_id.set("extension", "20240308") ver.set("value", "3")

这样平台能知道这两份文档是同一份出院小结的第 2 版和第 3 版，而不是两份完全独立的文档。

6. 生成之后如何验证与批量自检：一条命令跑完全部样例

CDA 生成器写完，验证环节不能省。这章讲我用什么命令做 Schema 校验、怎么批量跑历史样例、以及上线前我必查的三个习惯。

6.1 用 xmllint 做 Schema 校验的最小命令

本机有 CDA R2 的 schema 文件时，校验一条命令：

xmllint --noout --schema POCD_MT000040.xsd sample_cda.xml

POCD_MT000040.xsd 是 CDA R2 的根 schema，同一目录下要有 datatypes.xsd、vocab.xsd、NarrativeBlock.xsd 等依赖文件，缺一不可。报错时看前三条就够了，后面的错误大多是前面错误的连锁反应。

没有本地 schema 也可以用 Python 的 lxml 做同样校验，但 xmllint 的优势是批量快、输出清楚。提一句：Schema 校验通过的文档未必能过平台的 Schematron 校验，平台还会查 recordTarget 是否存在、时间字段是否带时区等约束，这部分靠后续自检脚本兜底。

6.2 批量自检脚本：一次跑完所有样例

项目里通常有几十份或几百份历史样例，不可能手动逐份校验。我习惯写一个简单的 bash 脚本批量跑：

#!/bin/bash for f in samples/*.xml; do if xmllint --noout --schema POCD_MT000040.xsd "$f" 2>/tmp/err; then echo "OK $f" else echo "FAIL $f" head -n 5 /tmp/err fi done

这个脚本配合定时任务或 CI，每次代码改动后自动跑一遍全部样例，能防止修改一个参数导致其他文档集体翻车。另外再查一下文档 id 是否重复：

grep -o '<id root="[^"]*"' samples/*.xml | sort | uniq -d

有输出就说明两份文档用了同一个 id，按上一章的规则改成 UUID 就好。

6.3 上线前我必查的三个习惯

第一，每换一次模板就用校验脚本重新跑一遍全部历史样例。平台模板升级是常态，旧文档可能还是合法的，但新文档必须按新模板来。

第二，把 templateId、codeSystem、OID 这些参数从代码里抽出来，放到配置文件里。生成器写死这些值的后果是平台一改模板，你得改代码重新部署；放配置里的话，改一行配置就能适配新模板。

第三，保留一份“被平台打回”的文档样本。某公司项目里有一份专门存放退回文档的目录，每次退回后对着错误信息修正生成器，修完再跑一次完整校验。我第一次做 CDA 生成器时，因为少了一个 templateId，整批报告被退回，重新生成后才意识到前置自检的重要性。后来我在生成器里加了一个--check参数，先输出校验报告再决定是否提交。希望帮到你。

本文还有配套的精品资源，点击获取