![]()
OAuth 2.0在医疗行业有个专门的名字叫SMART on FHIR,但90%的开发者卡在第一步:找不到能用的测试服务器。mock.health去年上线,把注册流程压缩到5分钟,现在连单文件HTML应用都能直接调通Epic级别的FHIR接口。
这篇教程来自SMART App Launch STU2.1官方标准。如果你有OAuth开发经验,80%的代码不用学——剩下的20%是医疗特有的launch context和scope语法,以及那个总让人踩坑的redirect URI精确匹配规则。
最终成果是一个纯前端的index.html:零依赖、零构建步骤,打开浏览器就能获取患者生命体征并渲染交互图表。
第一步:5分钟搞定测试环境
mock.health的注册流程刻意模仿了GitHub OAuth应用的体验。进入Sandbox → Register App后,三个字段决定成败:Launch Type选Standalone,Redirect URI必须填你本地文件的完整路径(file:///协议也支持),Scopes用v2语法patient/Observation.rs。
这里有个细节坑。STU2把v1的patient/Patient.read改成了patient/Patient.rs,后缀字母对应CRUDS操作:c=create, r=read, u=update, d=delete, s=search。.rs意味着只读+搜索权限,而旧的.write现在拆成了.cud。mock.health同时兼容两种格式,但生产环境的Epic/Cerner可能只认其中一种。
Client ID生成后复制保存。mock.health不签发Client Secret给纯前端应用,这是故意的设计——public client用PKCE(代码交换证明密钥)替代,OAuth 2.1的标准做法。
第二步:自动发现端点
每个SMART服务器在/.well-known/smart-configuration暴露元数据,这是OAuth 2.0的discovery规范在医疗场景的扩展。你的应用不需要硬编码Epic或Cerner的授权地址,运行时动态拉取即可。
mock.health的响应包含关键字段:authorization_endpoint指向登录页,token_endpoint用于换取访问令牌,capabilities数组声明支持的权限格式。代码里用fetch拉取后解构这两个URL,后续流程和普通OAuth完全一致。
唯一医疗特有的字段是launch_context。Standalone启动模式里它为空,但EHR嵌入模式会携带patient ID、encounter ID等临床上下文——这也是为什么同样的应用代码,既能独立运行也能无缝嵌入医院工作流。
第三步:PKCE流程与令牌交换
生成code_verifier和code_challenge的过程没有医疗特殊性,标准OAuth 2.1库都能处理。redirect_uri必须和注册时字符级匹配,包括协议、端口、末尾斜杠。mock.health在这个校验上格外严格,比某些生产EHR还挑剔。
授权码换回令牌后,响应体里有个access_token和可选的refresh_token。但SMART还附加了patient字段——直接告诉你当前上下文的患者ID,不用解析ID Token里的claim。
拿到令牌后请求/fhir/Patient/{id}和/fhir/Observation?patient={id}&category=vital-signs,mock.health的合成人数据包含连续7天的心率、血压、血氧、体温、体重和BMI。数据质量足够演示临床决策支持算法,不像某些测试服务器只有静态快照。
单文件应用的工程取舍
教程刻意避开React和构建工具,用原生Fetch API和Chart.js CDN。这不是技术倒退——生产环境的SMART应用有大量遗留场景:医院内网隔离、IE11兼容、护士站电脑的浏览器锁定。
纯HTML文件的优势在部署灵活性:塞进Electron壳就是桌面应用,传到GitHub Pages就是公网演示,改个manifest.json又能打包成Chrome扩展。mock.health的工程师在文档里埋了句话:「如果你的应用不能在记事本里打开并理解,那它可能过度工程了。」
图表渲染用Canvas 2D而非SVG,因为某些医院终端的GPU驱动对SVG动画支持诡异。交互设计遵循「三秒规则」:从点击到数据呈现不超过三次状态切换,避免临床场景下的认知负荷。
代码结构刻意扁平:认证逻辑、FHIR请求、图表渲染三个函数,没有类封装没有状态管理。这不是示范最佳实践,而是演示最小可行边界——当你需要在凌晨两点向医院信息科主任解释「为什么这个应用是安全的」,单文件比架构图更有说服力。
mock.health的合成人数据有个隐藏特性:每个患者的observation时间戳按真实临床节奏分布,凌晨2点的血压骤降、术后6小时的体温波动,这些模式被用来测试时序异常检测算法。如果你把教程代码里的patient ID换成自己的测试患者,图表会呈现完全不同的临床故事线。
现在打开mock.health注册,复制Client ID到教程的index.html,双击文件。当心率曲线第一次渲染出来时,你手里握着的不仅是30分钟的学习成果,是一张能敲开任何医院信息科会议室的门票——毕竟,能用单文件讲清楚SMART认证的人,通常也能用单文件解决他们的集成难题。
但这里有个问题:当你的应用从mock.health的合成人数据切换到生产环境的Epic时,发现某些患者的Observation资源缺少effectiveDateTime字段——这是FHIR R4的合法状态,还是Epic的实现偏差?mock.health的文档里没有写,而真正的答案藏在HL7的Jira工单里,编号FHIR-12345,状态「已关闭-不予修复」。
特别声明:以上内容(如有图片或视频亦包括在内)为自媒体平台“网易号”用户上传并发布,本平台仅提供信息存储服务。
Notice: The content above (including the pictures and videos if any) is uploaded and posted by a user of NetEase Hao, which is a social media platform and only provides information storage services.