API和SDK在医疗软件中的区别,头一周最容易把两层职责装反

接入与开发

用医疗软件的注册、报告回写、影像调阅几个真实场景,把 API 和 SDK 各自管哪一层讲清楚,给一套能照着做的分工判断和验证顺序。

医疗项目里接 AI,最容易出的岔子不是模型选错,是把该写在接口里的东西塞进 SDK,或者反过来。前者一换供应商就要重编,后者每次改一个字段都得发版。这篇按「谁管契约、谁管习惯」这条线掰开,配上几张对照表和第一次接入要走的顺序,帮你在动手之前把两层摆对位置。

接 AI 进医疗系统,头一周最容易踩的坑不是模型效果差,而是把两层的活儿装反了。该写在接口层的东西塞进 SDK,换个供应商就得重编译一遍;该封在 SDK 里的细节又散在每个调用处,改一个字段全组发版。这事儿麻烦在它不会当场报错,等到要换供应商或者过院内评审才露出来。

这篇按「谁管契约、谁管习惯」这条线拆。契约指请求长什么样、返回哪些字段、错误码怎么定义;习惯指你怎么少写样板代码、怎么省心处理重试和流式读。先分清这两件事归谁管,再谈用哪个。

先把「谁管契约、谁管手感」分清楚

接口这一层的价值在于稳定:今天用 Python 调,明年换成 Java 写,请求体和返回结构还是那一套。跨团队、跨语言、跨年份还能对得上,这是接口该守住的底线。SDK 管的是另一回事——把你反复写的那几行封装成一个函数,顺带处理鉴权刷新、超时重试、流式分块读取,让你本组少写点样板代码。

判断口诀很朴素:要跨团队、跨语言、跨年份还能用,就落在接口上;只是让本组少敲几行,才轮到 SDK。不过这套分法有前提。如果团队只有一种语言、项目生命周期就几个月,那分那么细意义不大,挑个顺手的包能用就行,别为了架构正确给自己加活。

医疗软件里那几个具体岔口

影像调阅、检验报告回写这类对接,对方给的多半是接口文档加鉴权方式,SDK 往往没人持续维护。你以为拿到的是一份现成的客户端库,翻到最后发现只有半页说明和一个过期的示例,这种情况不在少数。指望它省事,最后是自己在填坑。

  • 院内系统每改一次要过评审排期,「不发版就能调整」比「写得爽」重要得多,这时接口优先
  • SDK 生成的依赖锁死在某几个运行时版本上,医院老服务器跑不动,硬上就是给自己挖坑
  • 反过来,流式返回、断点重试、分块校验这些细节自己写容易漏,一层薄封装省下来的时间是实打实的
  • 报告回写接口的字段校验规则会随院内规范变,这类变动落在配置里比落在代码里好改

实际用下来,误判最多的是把 SDK 当成「省事」的代名词。它省的是调用处的字数,不是理解成本;封装层内部做了几次重试、缓存了什么、超时怎么算,这些你照样得搞清楚,不然出问题时连从哪查都不知道。

一张对照表,按这几个格子勾

别急着选边,先按下面这几个维度给自己项目打勾。哪边占得多,就往那边靠,但同一件事别两边都做——重复封装最容易埋下不一致的坑,接口改了封装层没跟上,问题只在某个科室的环境里复现。

维度接口更适合SDK 更适合
变更频率多方协调、改一次要评审只改本组调用处,点头就动
可替换性换供应商改配置和映射换供应商往往要重写调用处
排错成本看请求和返回就能定位还得先判断是封装层还是远端惹的
合规审计调用留痕清楚,好复述内部重试和缓存要额外确认
团队语言多语言并存、长期维护单一技术栈、迭代快

这张表不是让你二选一,而是帮你确认哪一层该放什么。表里没列「性能」和「安全」两栏,因为这两件事两层都得管,不属于取舍项。

第一周按这个顺序走,别倒过来

  1. 先用最笨的方式打通一次照文档手动发一次请求,把返回结构、字段含义、错误码截图存下来。这份记录是后面所有封装的基准,别跳过去直接装包,装错了包排查半天才发现文档里早写了。
  2. 再决定要不要包一层只有当同一段请求要写三遍以上,才值得抽成封装。写两遍就抽,往往抽早了,字段一变又要拆。
  3. 封装时把可调项留出来超时、重试次数、日志开关都做成初始化参数,填在创建客户端那一格,别散落在每个调用处。写死在函数里,后面调一次得改源码。
  4. 补一条最小回归用例接口或封装任一改动后跑一遍,尤其是报告回写和影像调阅这两条链路,避免只在某个院内环境下才炸。

什么情况下这套分工不适用

这套分法不是万能药。单体内部的小工具,调用方和提供方是同一个人,分那么细纯属自找麻烦,怎么顺手怎么来。还有一种情况是供应商只提供 SDK 不提供文档化接口,那没得选,但要把版本升级当成一次正式发布来排期,别在周五下午顺手升。

第三种是已经有一层统一网关收口的情况。契约在网关那层已经稳住了,客户端里用什么封装都行,这时候再纠结接口还是 SDK 意义不大,重点该放在网关的鉴权和日志上。至于各家模型的调用方式和价格差异,到 /sites 和 /price-watch 看当时的数字,别凭印象记。

下一步看完还拿不准自己项目该往哪边靠?先把当前接入方案的调用链画出来,再到站内指南中心对照排查顺序过一遍,比闷头装包省事。

常见问题

医疗项目里只给 SDK 不给接口文档,能接吗?

能接,但要把它当成一个会变的外部依赖来管。先把 SDK 版本锁住,升级当成一次正式发布来排期;在它外面再包一层薄接口,让自己的业务代码只认你这层,这样将来供应商换 SDK 大版本时,改动面能压到最小。

接口和 SDK 同时用,会不会重复?

常见也确实合理,关键看各自管什么。接口管契约和数据形状,SDK 管重试、流式读取这类手感。只要不在两边都做参数校验和缓存,就不算重复。怕的是同一份逻辑在两个地方各写一遍,出问题时不知道是哪边在起作用。

怎么判断现在的封装该不该拆掉?

看它有没有挡住你变更。如果每次调个新字段都要改封装、发版本、走一遍评审,那这层就该瘦身或者拆掉,把可变的部分挪回配置。反过来,如果它一直很稳、只是让调用处少写几行,那就留着,别为了架构好看去动它。

本文依据各平台公开文档与官方公告整理,只做中文归纳;具体做法、参数与限制以官方文档为准。