简介：面向医疗信息化开发者与HL7初学者的实用工具包，围绕HL7 CDA临床文档架构标准，提供生成符合规范的CDA XML文件的小程序及配套资料，帮助读者在无需深入掌握XML细节的情况下完成结构化临床文档的创建与验证，适用于病历摘要、检查报告等场景的互操作性实践。压缩包共5个文件，约443KB，包含可执行程序、示例XML文件、XSL样式表、LOINC文档CSV数据以及一份PDF用户手册，覆盖从运行、模板参考到字段对照的完整使用链路。目前已有547人学习下载。读者可借助示例文件快速理解CDA文档结构，通过样式表查看渲染效果，结合手册与术语表完成数据录入、模板自定义与标准验证，为电子健康记录系统对接和科研数据整理提供可复用的参考方案。
1. 从一份“没人愿意手写”的CDA文档说起
医院信息科最怕接到的需求之一，是“把这份病历导成标准CDA文档”。HL7 CDA 这套规范本身不难理解，难的是它那棵又深又长的 XML 树：ClinicalDocument下面挂recordTarget、component、structuredBody，每一层还有templateId、code、effectiveTime这些必须填对的节点。手写一份能过校验的 CDA，熟练的人也要对着规范抠半天，稍不留神就是命名空间写错、templateId漏填、时间格式不合规。这个“生成CDA文件的小程序”就是冲着这个痛点来的——它把 CDA 文档的骨架和常用段落封装成可复用的生成逻辑，开发者传入病历数据，程序吐出结构合规的 XML 文件。适合正在做院内系统对接、电子病历归档、区域医疗数据交换的开发者，尤其是那些被 CDA 校验工具反复打回、想找个能跑起来的起点的人。
2. 项目定位与技术选型：为什么用脚本而不是重型框架
2.1 它到底解决什么问题
CDA（Clinical Document Architecture）是 HL7 组织定义的临床文档标准，本质是一份带约束的 XML。一份出院小结的 CDA 文档，通常包含文档头（患者信息、作者、 custodian、文档类型编码）和文档体（若干section，每个 section 里放叙述性文本和结构化条目）。规范里templateId决定了这份文档属于哪种类型，比如护理记录、检验报告、出院小结各有各的模板约束。
这个项目的定位很明确：不做完整的 CDA 编辑器，也不做 HL7 消息引擎，只做“给定数据 → 生成合规 XML”这一段。它把文档头里那些固定结构（realmCode、typeId、templateId列表）和常用 section 的骨架预先写好，业务侧只需要填患者姓名、性别、出生日期、就诊时间、诊断结论这些字段。对于只需要“导出标准文档”的场景，这比引入一整套集成引擎轻得多。
2.2 技术栈与目录结构
从项目形态看，这是一个脚本型小程序，核心依赖是 XML 构建库和模板渲染。常见做法是用 Python 的lxml或xml.etree.ElementTree来拼树，前者对命名空间和属性顺序控制更细，生成出来的文档更接近规范示例。目录结构大致如下：
cda-generator/ ├── main.py # 入口，读取输入数据并调用生成器 ├── generator/ │ ├── __init__.py │ ├── document.py # ClinicalDocument 文档头构建 │ ├── sections.py # 各类 section 的构建函数 │ └── templates.py # templateId、code 等常量表 ├── data/ │ └── sample_patient.json # 示例输入数据 ├── output/ # 生成的 CDA XML 落盘目录 └── requirements.txttemplates.py里放的是 OID 常量，比如文档类型的templateId、章节编码的code值。这些值在规范里是固定的，集中管理比散落在各处好维护。document.py负责文档头，sections.py按章节拆分，main.py只做编排。这种分层的好处是：新增一种文档类型时，只需要在templates.py加常量、在sections.py加一个构建函数，入口逻辑不用动。
提示：CDA 的
templateId是 OID 字符串，写错一位校验就过不了。建议把用到的 OID 全部登记在常量表里，代码里只引用常量名，不要直接写字符串字面量。
2.3 输入数据的约定
项目用 JSON 作为输入格式，字段命名贴近业务语义而不是 XML 节点名。示例数据大致长这样：
{ "patient": { "name": "张三", "gender": "M", "birthTime": "19850312", "id": "P000123" }, "author": { "name": "李医生", "orgName": "某医院内科", "time": "20240115103000" }, "document": { "title": "出院小结", "effectiveTime": "20240115103000", "templateKey": "discharge_summary" }, "sections": [ {"key": "chief_complaint", "text": "反复咳嗽两周"}, {"key": "diagnosis", "text": "社区获得性肺炎"} ] }时间统一用YYYYMMDDHHmmss的紧凑格式，这是 HL7 的TS类型惯用写法，省去在生成阶段再做格式转换。templateKey是内部约定的键名，映射到templates.py里的 OID，这样业务侧不需要知道 OID 长什么样。sections数组里每个元素的key对应一个章节构建函数，text是叙述性内容。
3. 核心模块拆解：从 JSON 到合规 XML 的完整链路
3.1 文档头构建：命名空间与固定结构
CDA 文档的根节点必须带xmlns命名空间，且ClinicalDocument下有几个固定子节点顺序不能乱。document.py里的构建函数大致是这样：
from lxml import etree NS = "urn:hl7-org:v3" def build_header(data, template_oid): # 根节点带命名空间，lxml 用 nsmap 声明 root = etree.Element("{%s}ClinicalDocument" % NS, nsmap={None: NS}) # realmCode 固定为 CN，表示中国区域 realm = etree.SubElement(root, "{%s}realmCode" % NS) realm.set("code", "CN") # typeId 固定指向 CDA R2 的 POCD_MT000040 type_id = etree.SubElement(root, "{%s}typeId" % NS) type_id.set("root", "2.16.840.1.113883.1.3") type_id.set("extension", "POCD_MT000040") # 文档类型 templateId，由调用方传入 tpl = etree.SubElement(root, "{%s}templateId" % NS) tpl.set("root", template_oid) # 文档 id：每次生成唯一，常见做法是 OID + 时间戳 + 随机数 doc_id = etree.SubElement(root, "{%s}id" % NS) doc_id.set("root", "2.16.156.10011.1.1") doc_id.set("extension", data["document"]["effectiveTime"]) # 文档标题与生效时间 title = etree.SubElement(root, "{%s}title" % NS) title.text = data["document"]["title"] eff = etree.SubElement(root, "{%s}effectiveTime" % NS) eff.set("value", data["document"]["effectiveTime"]) return root这段代码的关键点有三个。第一，nsmap={None: NS}让所有子节点默认落在 CDA 命名空间下，避免每个节点都手写{urn:hl7-org:v3}前缀，生成出来的 XML 也更干净。第二，typeId的root和extension是 CDA R2 的固定值，写死没问题，但templateId必须按文档类型区分，所以从参数传入。第三，id节点的extension用时间戳，实际项目里更稳妥的做法是加一段随机后缀，防止同一秒内生成两份文档导致 ID 冲突。
参数说明：data是完整输入字典，template_oid是从templates.py查出来的文档类型 OID。函数只负责文档头，recordTarget（患者信息）和author（作者信息）在后续函数里追加，保持职责单一。
3.2 患者与作者节点：把业务字段映射到 XML 结构
recordTarget的结构是recordTarget > patientRole > patient > name/gender/birthTime，中间还夹着id。映射逻辑不复杂，但节点层级容易写错：
def build_record_target(root, patient): rt = etree.SubElement(root, "{%s}recordTarget" % NS) role = etree.SubElement(rt, "{%s}patientRole" % NS) # 患者 ID，root 用机构 OID，extension 放业务主键 pid = etree.SubElement(role, "{%s}id" % NS) pid.set("root", "2.16.156.10011.1.2") pid.set("extension", patient["id"]) patient_el = etree.SubElement(role, "{%s}patient" % NS) name = etree.SubElement(patient_el, "{%s}name" % NS) name.text = patient["name"] gender = etree.SubElement(patient_el, "{%s}administrativeGenderCode" % NS) gender.set("code", patient["gender"]) gender.set("codeSystem", "2.16.840.1.113883.5.1") birth = etree.SubElement(patient_el, "{%s}birthTime" % NS) birth.set("value", patient["birthTime"])这里有个容易翻车的点：administrativeGenderCode的codeSystem必须指向 HL7 的行政性别编码系统，M/F是标准值，如果业务系统里存的是“男/女”中文，需要在入口处先做一次映射。作者节点author的结构类似，author > assignedAuthor > assignedPerson/name加representedOrganization，时间放在author/time。两个函数都只依赖传入的字典，不读全局状态，方便单测。
3.3 章节构建：用字典分发代替 if-else 堆叠
structuredBody下每个component包一个section，section 里至少要有templateId、code、title、text。项目用一张分发表把key映射到构建函数：
SECTION_BUILDERS = { "chief_complaint": build_chief_complaint, "diagnosis": build_diagnosis, "medication": build_medication, } def build_sections(root, sections): body = etree.SubElement(root, "{%s}component" % NS) structured = etree.SubElement(body, "{%s}structuredBody" % NS) for item in sections: builder = SECTION_BUILDERS.get(item["key"]) if builder is None: # 未知章节直接跳过，避免生成半截文档 continue comp = etree.SubElement(structured, "{%s}component" % NS) builder(comp, item["text"])每个build_xxx函数内部负责写自己那套templateId和code。以主诉为例，section 的code用 LOINC 编码，text节点里放叙述内容。这种字典分发的写法比一长串if key == ...好扩展，新增章节只要注册进SECTION_BUILDERS。未知key选择跳过而不是抛异常，是为了让部分数据缺失时仍能产出文档，但实际项目里更稳妥的做法是记录一条警告日志，方便排查为什么某章节没出现。
3.4 序列化与落盘：编码和缩进别踩坑
最后一步是把lxml的树写成文件：
def save(root, path): tree = etree.ElementTree(root) tree.write( path, encoding="UTF-8", xml_declaration=True, pretty_print=True, )encoding="UTF-8"和xml_declaration=True保证文件头有<?xml version='1.0' encoding='UTF-8'?>，很多校验工具对声明缺失很敏感。pretty_print=True让输出带缩进，人眼可读，但要注意它不会改变节点顺序，规范要求的顺序仍由构建阶段的追加顺序决定。落盘路径建议按output/{患者ID}_{时间戳}.xml命名，避免覆盖。
4. 跑起来：环境、命令与验证方式
4.1 环境准备与依赖安装
项目是纯 Python 脚本，Python 3.8 以上即可。依赖只有lxml，安装命令：
python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install -r requirements.txtrequirements.txt里通常就一行lxml>=4.9。如果机器上没有编译环境，lxml的 wheel 包一般能直接装上；装不上时再考虑系统包管理器补libxml2开发头文件，这是常见做法。
4.2 用示例数据跑通第一份文档
入口命令设计得很直接：
python main.py --input data/sample_patient.json --output output/main.py的逻辑是读 JSON、查模板 OID、依次调用build_header、build_record_target、build_author、build_sections、save。跑完后output/下会多出一个 XML 文件。打开看一眼，根节点应该是ClinicalDocument带xmlns="urn:hl7-org:v3"，往下能找到recordTarget和structuredBody，说明主链路通了。
4.3 怎么确认生成结果“合规”
最直接的办法是用 XML 解析器做一次结构检查：
python -c "from lxml import etree; etree.parse('output/P000123_20240115103000.xml'); print('well-formed')"能解析只说明格式合法，不代表符合 CDA 约束。进一步验证需要 XSD 或 Schematron 规则文件，项目本身不一定附带，常见做法是拿院内集成平台或第三方校验工具跑一遍。手工检查时重点看三处：templateId的 OID 是否和文档类型匹配、effectiveTime是否是 14 位紧凑格式、每个section是否都有code和text。这三处是校验工具最常报错的地方。
注意：不同文档类型的
templateId不一样，拿出院小结的 OID 去生成检验报告，结构上可能不报错，但语义校验一定过不了。生成前先确认templateKey选对了。
5. 避坑与排查：那些校验工具不会告诉你的细节
5.1 现象：文件能打开，但校验工具报“命名空间错误”
原因通常是根节点声明了xmlns，但子节点是用不带命名空间的方式创建的，或者反过来，根节点没声明、子节点却带了前缀。lxml里用etree.SubElement(root, "tag")创建的子节点不会自动继承父节点的默认命名空间，必须写成"{%s}tag" % NS。解决方式是统一封装一个sub(parent, tag)辅助函数，内部固定拼命名空间，杜绝手写遗漏。
5.2 现象：effectiveTime被校验工具判为格式非法
原因多半是传了2024-01-15 10:30:00这种带分隔符的格式。HL7 的TS类型要求YYYYMMDDHHmmss紧凑写法，带时区时再加+0800。解决方式是在入口处做一次格式归一化，把业务系统常见的几种时间格式统一转成紧凑串，转换失败直接报错而不是静默生成，否则错误会一路带到校验环节才暴露。
5.3 现象：生成的文档里 section 顺序和预期不一致
原因是对structuredBody下component的追加顺序没有控制，或者用了字典遍历导致顺序随机。CDA 对 section 顺序本身约束不严，但某些模板会要求特定章节在前。解决方式是在sections输入数组里显式排好序，构建时严格按数组顺序追加，不要依赖字典的遍历顺序。
5.4 现象：中文内容在部分系统里显示乱码
原因是序列化时编码没指定或指定成了 ASCII。tree.write必须显式传encoding="UTF-8"，同时xml_declaration=True让声明和实际编码一致。如果下游系统仍乱码，检查它读取时是否按声明编码解析，而不是硬编码成 GBK。
5.5 现象：同一患者短时间内生成两份文档，ID 冲突
原因是id的extension只用了秒级时间戳。解决方式是在时间戳后拼一段随机串或自增序号，保证root + extension组合唯一。这个细节在单机调试时几乎不会触发，一上批量导出就暴露，属于典型的“测试环境没事、生产环境翻车”。
6. 二次开发：把单文档生成器改成可配置的模板引擎
这个项目最值得动手改的地方，是把写死在代码里的 section 结构抽成配置。现在的SECTION_BUILDERS字典里，每个函数都硬编码了自己的templateId和code，新增一种文档类型要改代码。更灵活的做法是把章节定义放到 YAML 或 JSON 配置里，字段包括key、templateOid、code、codeSystem、title、textPath，生成器读配置动态拼节点。这样业务侧换文档类型时只改配置，不用碰 Python。
改造时有个验证习惯值得保留：每改完一种文档类型，先拿最小数据集跑一遍，再用解析器确认节点路径存在，最后才上校验工具。最小数据集就是只填患者姓名、性别、出生时间和一个 section，能生成、能解析、关键节点齐全，再逐步加字段。这样出问题时能快速定位是新加的哪个字段导致的。
另一个改造方向是加一层输出适配。现在只写 XML 文件，实际对接时可能需要直接返回字符串给接口、或者推送到消息队列。把save拆成to_string和to_file两个函数，上层按需调用，比在save里加分支干净。
| 改造点 | 现状 | 建议做法 |
|---|---|---|
| 章节定义 | 硬编码在函数里 | 抽到 YAML 配置，动态构建 |
| 输出方式 | 只写文件 | 拆to_string/to_file |
| 未知章节 | 静默跳过 | 记警告日志，便于排查 |
| 文档 ID | 秒级时间戳 | 时间戳加随机后缀 |
我自己的习惯是，每次动生成逻辑之前，先把当前版本的输出存一份基线文件，改完后 diff 一下，确认只有预期内的节点变化。CDA 这种层级深的 XML，肉眼很难看出少了一个component或者属性顺序变了，diff 是最省事的后悔药。从那以后我每次改模板相关代码，都强制走一遍“基线 diff + 最小数据集 + 解析校验”三步，希望帮到你。
本文还有配套的精品资源，点击获取
