前言

在构建基于 HL7 FHIR（Fast Healthcare Interoperability Resources）标准的医疗信息系统时，开发者和架构师常常面临一个关键问题：如何在保证数据完整性的同时，优化网络传输效率与客户端处理性能？

FHIR 规范为此提供了一套标准化的机制——通过_summary搜索参数，允许客户端在发起读取（Read）或搜索（Search）请求时，明确指定所需资源的“详细程度”。这一机制不仅提升了系统整体性能，也增强了 API 的灵活性与可扩展性。

一、什么是_summary？

_summary是 FHIR 规范中定义的一个通用搜索参数（Common Search Parameter），适用于所有 FHIR 资源类型（如Patient、Observation、Encounter等）。它不属于某个特定资源的业务字段，而是由 FHIR 基础层（Base Layer）提供的元控制参数，用于指导服务器在构造响应时对资源内容进行裁剪或摘要。

根据 HL7 FHIR R4 官方文档，_summary的核心目标是：

“Allow the client to request that the server return a subset of the resource, typically to improve performance or reduce bandwidth.”

即：允许客户端请求服务器返回资源的一个子集，通常用于提升性能或减少带宽消耗。

二、_summary的合法取值及其语义

FHIR 规范明确定义了_summary参数的五种标准取值。每种取值对应一种预定义的资源视图（View），服务器必须按照规范要求返回相应结构的数据。

✅规范依据：FHIR R4 §3.1.1.2 “_summary”；FHIR R5 保持相同语义。

三、各取值的行为分析

3.1_summary=false（默认）

• 行为：服务器返回未经修改的完整资源。
• 用途：详情页、数据同步、审计等需要完整信息的场景。
• 示例请求：

  GET [base]/Patient/pat-123

  等价于：

  GET [base]/Patient/pat-123?_summary=false

3.2_summary=true

• 行为：返回“摘要视图”。该视图由 FHIR 规范为每种资源类型明确定义，通常包括：
  • id
  • meta
  • implicitRules
  • language
  • 标识性字段（如identifier）
  • 状态字段（如status）
  • 主体引用（如subject）
  • 时间戳（如date,effectiveDateTime）
  • 编码字段（如code,category）
• 省略内容：大型附件、嵌套列表（如Observation.component）、扩展（除非标记为 summary）、Narrative（text）等。
• 典型用途：患者列表、检查结果概览、下拉选择器等 UI 场景。
• 示例请求：

  GET [base]/Observation?patient=Patient/123&_summary=true

🔍注意：摘要视图的具体字段由 FHIR 资源定义中的isSummary元素标记决定。例如，在Patient资源中，name、gender、birthDate通常被标记为摘要字段。

3.3_summary=text

• 行为：仅返回id、meta和text.div。
• text.div是什么？
  它是 FHIR 资源中的Narrative（叙述性文本），通常由服务器在资源创建时生成，是一段符合 CDA 样式的 XHTML，用于人类阅读。例如，一个 Encounter 的text.div可能是：“2025年12月1日，张三因发热就诊于内科门诊。”
• 用途：快速预览、打印摘要、无障碍访问等。
• 示例请求：

  GET [base]/Encounter/enc-456?_summary=text

3.4_summary=data

• 行为：返回除text字段外的所有结构化数据。
• 用途：极少见。可能用于某些自动化处理流程，希望避免解析 HTML 内容。
• 风险提示：由于text字段常包含重要临床摘要，省略后可能导致信息缺失。一般不推荐使用。

3.5_summary=count

• 行为：执行查询但不返回资源，仅在 Bundle 中设置total字段。
• 响应结构示例：

  {"resourceType":"Bundle","type":"searchset","total":142,"entry":[]}

• 用途：
  • 分页前获取总记录数；
  • 统计类查询（如“某患者有多少条检验结果？”）；
  • 性能监控（评估查询复杂度）。
• 性能警告：对于大数据集，_summary=count仍需服务器执行完整查询以计算总数，可能耗时。部分 FHIR 服务器（如 HAPI FHIR）支持通过数据库索引优化此操作。

四、使用场景与最佳实践

4.1 列表展示（List Views）

• 场景：在 UI 中显示患者列表、医嘱列表、检验结果列表。
• 推荐参数：_summary=true
• 优势：减少 50%~80% 的响应体积，加快页面加载速度。
• 示例：

  GET [base]/Patient?_count=20&_summary=true

4.2 详情跳转（Detail Navigation）

• 场景：用户点击列表项后查看完整信息。
• 操作：先用_summary=true获取列表，再对选中项发起无_summary的完整请求。
• 模式：按需加载（Lazy Loading），平衡性能与功能。

4.3 数据统计与分页

• 场景：实现分页控件（如“共 142 条，当前第 1 页”）。
• 操作：
  1. 先请求_summary=count获取总数；
  2. 再请求_summary=true&_count=20&page=1获取第一页数据。
• 注意：若总数变化频繁（如实时数据），可考虑前端估算或省略总数显示。

4.4 快速预览（Quick Preview）

• 场景：鼠标悬停显示资源摘要、移动端卡片预览。
• 推荐参数：_summary=text
• 优势：直接渲染 HTML，无需客户端拼接字段。

五、与其他机制的对比

5.1_summaryvs_elements

✅建议：优先使用_summary=true；若其摘要字段不满足业务需求，再考虑_elements。

5.2_summary=countvstotalin Bundle

• 所有 FHIR 搜索响应 Bundle 默认包含total字段（若服务器支持）。
• 但某些服务器为性能考虑，默认不计算total（设为0或省略）。
• _summary=count是显式强制服务器返回准确总数的标准方式。

六、服务器实现注意事项

FHIR 服务器（如 HAPI FHIR、IBM FHIR Server、Microsoft FHIR Server）在实现_summary时应遵循以下原则：

1. 一致性：对同一资源类型，_summary=true的返回字段应在不同请求间保持一致。
2. 完整性：摘要视图必须包含所有标记为isSummary=true的元素（依据 FHIR StructureDefinition）。
3. 安全性：_summary不是访问控制机制！即使使用摘要，仍需通过授权策略（如 SMART on FHIR）限制数据可见性。
4. 性能：_summary=count应尽可能利用数据库 COUNT 优化，避免全表扫描。
5. 兼容性：对不支持的_summary值（如_summary=xyz），应返回400 Bad Request。

七、常见误区与澄清