Medplum v4.0.0 重大版本更新解析

Medplum 是一个开源的医疗健康数据平台，基于 FHIR（Fast Healthcare Interoperability Resources）标准构建，为开发者提供了处理医疗健康数据的完整解决方案。该平台包含前端组件、后端服务和开发者工具，帮助医疗健康应用快速实现数据互操作性。

类型系统全面升级

本次 v4.0.0 版本对 TypeScript SDK 进行了重大改进，移除了所有在 v3 版本中标记为废弃的 API 和方法。这一变化体现了 Medplum 团队对类型安全和代码质量的重视。开发者需要注意：

1. 所有废弃的 MedplumClient 方法已被移除，必须使用新的替代方案
2. 类型系统更加严格，特别是在资源引用处理方面
3. 接口定义更加精确，减少了运行时错误的可能性

这些改变虽然需要开发者进行一定的代码迁移，但将显著提高应用的稳定性和可维护性。

API 规范性与安全性增强

v4.0.0 版本对 API 进行了多项重要改进，使其更加符合 FHIR R4 规范：

1. 精确匹配运算符：eq 操作符现在执行严格的精确匹配，不再进行模糊匹配，这使查询结果更加可预测
2. 字符串验证强化：按照 FHIR R4 规范，现在禁止在字符串中使用控制字符，提高了数据安全性
3. 引用处理改进：getReferenceString 方法现在要求更严格的参数类型，要么提供完整的 reference 字符串，要么同时提供 resourceType 和 id

这些变化使 Medplum 更加符合医疗健康数据处理的行业标准，同时也提高了平台的安全性。

自托管部署重要变更

对于自托管 Medplum 的用户，v4.0.0 版本带来了必须注意的基础设施要求变更：

1. 运行环境要求提升：

   • Node.js 最低版本要求提高到 20
   • PostgreSQL 最低版本要求提高到 13

2. 强制数据迁移：

   • 必须先在 v3.3.0 版本上运行数据迁移脚本
   • 直接升级到 v4.0.0 而不执行迁移将导致服务启动失败

这些变更反映了 Medplum 对现代基础设施的支持，同时也确保了平台的稳定性和性能。自托管用户需要特别注意迁移顺序，避免服务中断。

开发者体验优化

除了上述重大变更外，v4.0.0 还对开发者体验进行了多项优化：

1. API 表面清理，移除冗余接口，使 SDK 更加简洁
2. 错误处理更加一致和可预测
3. 文档和类型提示更加完善

这些改进虽然不涉及功能变化，但将显著提高开发效率和代码质量。

升级建议

对于计划升级到 v4.0.0 的团队，建议：

1. 仔细阅读变更日志，了解所有破坏性变更
2. 先在测试环境验证所有关键功能
3. 对于自托管部署，严格遵循迁移步骤
4. 利用类型系统改进重构现有代码

Medplum v4.0.0 代表了该平台的一个重要里程碑，通过强化类型安全、规范符合性和基础设施支持，为构建可靠的医疗健康应用提供了更加强大的基础。虽然升级需要一定的工作量，但带来的长期收益将远超短期成本。