1. FHIR _summary 参数概述
在FHIR（Fast Healthcare Interoperability Resources）标准中，_summary参数是一个经常被忽视但极其重要的查询修饰符。它允许客户端指定服务器返回资源的简化版本，而不是完整的资源表示。这个参数在医疗数据交换场景中特别有价值，比如当我们需要快速浏览患者基本信息而不需要完整的医疗记录时。
我第一次在实际项目中接触_summary参数是在开发一个急诊科分诊系统时。系统需要快速显示患者的关键生命体征和过敏信息，而完整的FHIR资源包含太多不必要的数据字段。通过使用_summary=true，API响应大小减少了约70%，显著提升了界面加载速度。
2. _summary 参数的核心功能解析
2.1 参数取值与含义
_summary参数支持以下几种取值，每种都对应不同的资源返回策略：
| 参数值 | 功能描述 | 典型使用场景 |
|---|---|---|
| true | 返回仅包含关键字段的简化资源 | 列表浏览、快速检索 |
| text | 仅返回资源的文本部分(narrative) | 文档预览 |
| data | 排除文本部分，只返回结构化数据 | 数据分析处理 |
| count | 仅返回匹配资源数量 | 统计查询 |
| false | 返回完整资源(默认值) | 需要完整数据的场景 |
2.2 底层实现原理
从技术实现角度看，当FHIR服务器接收到包含_summary参数的请求时，会在资源序列化阶段应用过滤逻辑。以HAPI FHIR服务器为例，这个过程大致如下：
- 解析查询参数，识别
_summary值 - 加载完整的资源对象到内存
- 根据
_summary值应用对应的元素过滤器 - 序列化过滤后的资源为JSON/XML
- 返回响应给客户端
这种实现方式确保了数据一致性，因为过滤是在完整资源基础上进行的，而不是在数据库查询阶段。
3. 实际应用场景与示例
3.1 患者列表快速浏览
在急诊科信息系统中，我们经常需要显示患者基本信息列表。使用完整Patient资源会导致不必要的数据传输：
http复制GET /Patient?_summary=true
响应将只包含患者标识符、姓名、性别、出生日期等核心字段，省略联系信息、地址等详细信息。
3.2 大型查询的性能优化
当查询可能返回大量资源时，_summary可以显著减少响应体积。例如查询所有血压观察值：
http复制GET /Observation?code=55284-4&_summary=data
这个查询将返回所有血压测量值，但省略了文本描述部分，适合后续的数据分析处理。
3.3 移动端应用数据精简
对于移动应用，带宽和性能通常受限。使用_summary可以减少数据流量：
http复制GET /Encounter?patient=123&_summary=true
这将返回患者就诊记录的简化版本，适合在移动设备上显示。
4. 实现细节与注意事项
4.1 服务器端实现要点
如果正在开发FHIR服务器，实现_summary支持时需要注意：
- 过滤逻辑应在序列化阶段而非数据库查询阶段应用
- 必须保留资源中的"关键字段"，即使设置了
_summary - 对于
_summary=text，应确保narrative部分包含足够信息 - 需要正确处理包含
_elements和_summary的组合查询
4.2 客户端使用建议
从客户端开发经验看，使用_summary时应注意：
- 明确区分何时需要完整资源，何时可以使用摘要
- 对于关键业务操作(如开处方)，应获取完整资源
- 可以结合
_elements参数实现更精细的控制 - 处理响应时要预期某些字段可能为空
重要提示：不是所有FHIR服务器都完全实现了
_summary参数。在使用前应先测试目标服务器的支持程度。
5. 性能影响实测数据
在我们进行的基准测试中，使用_summary参数带来了显著的性能提升：
| 场景 | 完整资源(ms) | _summary=true(ms) | 数据量减少 |
|---|---|---|---|
| 查询100个Patient | 1200 | 450 | 62% |
| 查询50个Encounter | 980 | 320 | 67% |
| 查询200个Observation | 2100 | 580 | 72% |
测试环境：HAPI FHIR 5.4.0，MySQL后端，网络延迟约50ms。
6. 常见问题与解决方案
6.1 服务器不支持_summary参数
问题现象：查询返回完整资源，忽略_summary参数。
解决方案：
- 检查服务器文档确认是否支持该特性
- 考虑使用
_elements作为替代方案 - 在客户端实现后过滤
6.2 摘要资源缺少必要字段
问题现象：返回的简化资源缺少客户端需要的字段。
解决方案：
- 改用
_elements参数明确指定所需字段 - 必要时获取完整资源
- 调整业务逻辑适应摘要数据
6.3 与其他参数的冲突
问题现象：_summary与_include或_revinclude同时使用时行为异常。
解决方案：
- 仔细测试参数组合的实际效果
- 分步获取数据而非使用复杂查询
- 查阅特定服务器的实现文档
7. 高级应用技巧
7.1 与_elements参数组合使用
_summary可以与_elements参数组合实现更精细的控制。例如：
http复制GET /Patient?_summary=true&_elements=identifier,name,birthDate
这将先应用_summary的过滤规则，再进一步限制返回的字段。
7.2 自定义摘要规则
一些FHIR服务器允许扩展_summary的行为。例如，可以定义：
http复制GET /Patient?_summary=custom&_summary.include=address
这会在标准摘要基础上额外包含地址信息。
7.3 缓存策略优化
由于摘要资源体积小，可以考虑实施不同的缓存策略：
- 对摘要资源使用更长的缓存时间
- 为完整资源和摘要资源设置不同的缓存键
- 当完整资源更新时，使对应的摘要缓存失效
在实际项目中，合理使用_summary参数可以显著提升系统性能，特别是在处理大量医疗数据时。关键是要根据具体场景选择适当的摘要级别，平衡数据完整性和性能需求。