FHIR 中 _summary 参数

前言

在构建基于 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），服务器必须按照规范要求返回相应结构的数据。

取值	类型	语义说明	返回内容特点
`false`	布尔/字符串	默认行为。返回完整资源。	包含所有元素，包括 `text`、嵌套复杂对象、扩展等。
`true` 或 `1`	布尔/字符串	返回"摘要视图"（Summary View）。	仅包含资源的核心标识性字段和强制元素（mandatory elements）。省略大型或非关键数据（如 `Observation.value[x]`、`DiagnosticReport.presentedForm` 等）。
`text`	字符串	返回人类可读摘要。	仅包含 `Resource.id`、`Resource.meta` 和 `Resource.text.div`（即 Narrative 部分）。适用于快速渲染资源摘要文本。
`data`	字符串	返回结构化数据，但排除 Narrative。	包含除 `text` 字段外的所有数据。此选项较少使用，主要用于需要纯结构化数据而无需 HTML 渲染的场景。
`count`	字符串	仅返回匹配资源数量。	不返回任何资源实例。响应 Bundle 的 `total` 字段包含匹配总数，`entry` 数组为空。

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

三、各取值的行为分析

3.1 `_summary=false`（默认）

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

示例请求 ：

http 复制代码

GET [base]/Patient/pat-123

等价于：

http 复制代码

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 场景。

示例请求 ：

http 复制代码

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日，张三因发热就诊于内科门诊。"
用途：快速预览、打印摘要、无障碍访问等。

示例请求 ：

http 复制代码

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

3.4 `_summary=data`

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

3.5 `_summary=count`

行为：执行查询但不返回资源，仅在 Bundle 中设置 total 字段。

响应结构示例 ：

json 复制代码

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

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

四、使用场景与最佳实践

4.1 列表展示（List Views）

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

示例：

http 复制代码

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

场景：用户点击列表项后查看完整信息。
操作：先用 _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 `_summary` vs `_elements`

特性	`_summary`	`_elements`
控制粒度	预定义视图（粗粒度）	自定义字段列表（细粒度）
规范性	FHIR 强制标准，跨服务器一致	FHIR 支持，但依赖服务器实现
使用方式	`?_summary=true`	`?_elements=id,name,birthDate`
适用场景	通用摘要、性能优化	精确字段需求、最小化数据暴露
组合使用	不建议（语义冲突）	可单独使用

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

5.2 `_summary=count` vs `total` in Bundle

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

六、服务器实现注意事项

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

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

七、常见误区与澄清

误区	正确认知
"`_summary=true` 会返回我想要的所有关键字段。"	否。它只返回 FHIR 规范定义的摘要字段，可能缺少业务所需字段（如 `telecom`）。需验证实际返回。
"`_summary=count` 总是很快。"	否。在无索引的大表上，COUNT 查询可能很慢。应结合分页和缓存策略。
"使用 `_summary` 可以替代权限控制。"	严重错误！摘要仍可能包含敏感信息（如诊断代码）。必须配合 RBAC/ABAC。
"`_summary=text` 包含所有临床信息。"	否。Narrative 是生成的摘要，可能省略细节。不能用于临床决策支持。

FHIR 中 _summary 参数

前言

一、什么是 _summary？

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

三、各取值的行为分析

3.1 _summary=false（默认）

3.2 _summary=true

3.3 _summary=text

3.4 _summary=data

3.5 _summary=count

四、使用场景与最佳实践

4.1 列表展示（List Views）

4.2 详情跳转（Detail Navigation）

4.3 数据统计与分页

4.4 快速预览（Quick Preview）

五、与其他机制的对比

5.1 _summary vs _elements

5.2 _summary=count vs total in Bundle

六、服务器实现注意事项

七、常见误区与澄清

一、什么是 `_summary`？

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

3.1 `_summary=false`（默认）

3.2 `_summary=true`

3.3 `_summary=text`

3.4 `_summary=data`

3.5 `_summary=count`

5.1 `_summary` vs `_elements`

5.2 `_summary=count` vs `total` in Bundle