HL7中国批量数据导出服务实施指南 - Local Development build (v2026.01.23) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions
最佳实践
概述
以下是使用批量数据导出服务进行大规模数据交换的一套核心最佳实践，旨在确保流程高效、安全、可靠且符合规范。
核心原则：设计、协商与遵循
- 明确导出范围：在请求前，清晰定义所需的数据组、资源类型和时间范围，避免导出不必要的数据。
- 与服务提供方充分沟通：在实施前，与数据提供方（如EHR厂商）确认其批量数据导出服务端点的具体实现细节、支持参数、速率限制和认证方式。
- 严格遵循规范：确保你的客户端实现严格遵循最新的批量数据导出服务实施指南，并与服务器使用的FHIR版本兼容。
高效数据请求与处理
- 使用
_since和_type参数精确定位：
- 增量导出：利用 _since 参数仅请求自上次成功导出后创建或修改的资源，大幅减少数据量。务必记录每次导出的时间戳。
- 选择资源类型：使用 _type 参数明确指定需要的资源类型（如 Patient,Observation,Encounter），避免导出无关数据。
- 正确处理异步流程：
- 状态轮询：提交
$export请求后，使用返回的Content-LocationURL轮询状态。轮询间隔应遵循服务器返回的Retry-After头部字段，若不存在，建议从5-10秒开始并采用指数退避策略。
- 处理分块输出：准备好处理服务器可能返回的多个NDJSON文件（按资源类型分块）。按文件清单逐个下载。
- 结果确认与清理：成功下载所有数据文件后，应向服务器提供的导出文件删除URL发送
DELETE请求，主动清理服务器端的临时文件。
- 预期并处理空结果：为导出的患者组可能没有匹配数据的情况做好准备，设计客户端以优雅地处理空的导出结果。
安全、合规与数据管理
- 使用安全的认证授权：必须使用SMART Backend Services等适合服务器间通信的授权流程。确保系统能安全地管理和轮换客户端密钥。
- 传输与存储加密：确保所有数据传输都通过 HTTPS (TLS 1.2+) 进行。对下载的NDJSON文件在静态存储时进行加密。
- 实施完整的错误与重试机制：
- 为网络故障、服务器错误（5xx）、速率限制（429）和临时不可用（503）等情况设计健壮的重试逻辑。
- 记录详细的日志，包括请求ID、错误响应和重试历史，便于故障排查。
- 验证数据完整性与质量：
- 检查NDJSON文件是否符合格式规范，确保没有截断。
- 验证关键字段，如
Patient资源的ID在所有相关资源中的引用一致性。
- 核对导出的记录数与预期是否基本相符（例如，通过计数行数进行初步校验）。
实施与监控建议
- 将批量数据客户端作为独立服务：将批量导出逻辑与核心应用解耦，设计成独立的、可调度运行的服务或任务。
- 建立端到端监控：
- 监控导出作业的成功率、耗时、数据量趋势。
- 为关键故障（如连续失败、作业挂起）设置警报。
- 进行充分测试：
- 在非生产环境中，使用测试数据或沙箱环境进行全面测试。
- 模拟网络中断、服务器错误等场景，验证客户端的恢复能力。
这些实践构成了一个完整的技术与管理框架。
