简介面向医院信息系统集成平台建设的一份接口需求说明书旨在通过统一接口标准提升HIS、LIS、PACS、手术、费用等子系统间的集成性与互操作性尤其适合医院信息科人员、集成平台实施工程师及医疗信息化架构师将其作为需求评审与设计蓝本。资源以单个PDF文档交付大小约1.61MB内容完整、层级清晰按章节涵盖标识、系统概述、引用文档、需求定义与接口图。文档系统梳理了包括获取病区新病人、发送住院医嘱、查询住院病人费用、办理手术申请、办理出院手续、发送LIS/PACS申请、查询LIS/PACS报告、合理用药、查询区域健康档案、发送门诊处方、发送报病信息、院内病历查询、电子病历模块外部调用、门诊处方划价、候诊病人信息获取、分诊呼叫、查询注射通知单、电子病历数据获取等近20个典型集成场景并引用HL7、DICOM、IHE等标准为接口开发与实施提供具体参考。目前已有474人学习下载利用此文档可快速搭建医院集成平台的需求分析框架减少前期调研与返工成本适合医疗信息化项目立项、设计与验收各阶段使用。1. 医院信息系统集成平台的接口需求说明书先厘清边界再写文档一家三级医院上线集成平台时最容易出问题的往往不是中间件本身而是接口需求说明书里一条不起眼的字段定义。某次 HIS 与 LIS 对接沟通单上写着“患者姓名必填”却没说清楚患者姓名变更后历史记录由谁负责修正结果退费核对时出现大量姓名不一致的差错。这类事故的根源不在编码而在接口需求说明书把“系统间传递什么”和“业务上由谁负责兜底”混在了一起。集成平台的接口需求说明书本质是给不同系统立一个可以验证的契约。它要回答四类问题信息按什么格式传、在什么事件下触发、失败后怎么重试、数据字典不一致时听谁的。它服务于三方人群信息科要拿它做验收依据集成商要拿它定开发边界临床科室要拿它确认业务闭环。把这份文档写清楚比选一个昂贵的集成引擎更能决定项目成败。2. 接口需求说明书的技术骨架消息模型、接口清单与五要素2.1 集成平台与接口需求说明书的边界集成平台本身只解决传输、路由和协议转换至于传输的内容是否合理、字段是否完整平台并不关心。这正是接口需求说明书存在的理由它定义了平台两侧系统的语义约定。用常见的技术语言表述集成平台是发布-订阅模式的消息中间件而接口需求说明书是双方共同遵守的 Schema 契约。接口需求说明书要独立于具体产品。不能因为中间件选了 Ensemble 就写“在集成引擎中配置一个 TCP 端口”也不能因为平台支持 FHIR 就把所有交换都定义成 FHIR 资源。更稳妥的做法是先定义一个平台无关的消息结构再在实现层做协议适配。这样即使医院从商业集成引擎迁移到开源方案接口契约仍然成立。2.2 接口清单设计从业务域倒推接口边界接口清单不需要一开始就追求全量覆盖而是按业务紧迫度排序。我会从三个业务域入手梳理患者主索引域EMPI/PDQ、临床数据域医嘱、报告、文书、运营管理域费用、科室、字典。每个域内的接口要明确三件事消息类型、实时性要求、耦合边界。业务域典型接口消息类型实时性耦合方向患者主索引患者建档/更新/合并ADT_A01/A40实时各系统 → EMPI临床数据医嘱下达/停嘱ORM_O01实时HIS → 执行系统临床数据检验报告完成ORU_R01准实时LIS → 各订阅方运营管理科室字典同步MDM/自定义定时主数据 → 各系统运营管理费用确认DFT_P03实时计费系统 → 财务设计接口清单时一个容易踩的坑是把每个 HIS 页面操作都映射成一个接口。实际上接口是按“业务事件”划分的不是按“界面动作”划分。比如患者基本信息修改在界面上可能拆成姓名修改、证件号修改、手机号修改三个动作但在接口层应该合并为一个患者信息更新事件由接收方按业务规则处理。接口清单过细会导致平台的通道数量膨胀运维和监控成本随之上升。2.3 消息模型选型HL7 v2、FHIR 还是自定义 JSON选型没有绝对标准取决于两端系统的现存结构。国内医院 H I S 系统大多已有 HL7 v2 的 ADT、ORM、ORU 消息积累而新建设的互联网医院或微服务网关更倾向 REST JSON。接口需求说明书要能同时容纳两种风格建议的做法是定义统一的逻辑消息模型在传输层分别提供 HL7 v2 和 JSON 两种绑定。HL7 v2 的 Segment 字段位置是强约定比如 PID-3 是患者标识PID-5 是患者姓名字段顺序不能随意调整。JSON 绑定则是一对一的字段映射。实际项目中我一般在说明书中加一张映射表注明 JSON 字段名与 HL7 段的对应关系。这样既可以向上兼容传统 HIS 的接口也能让新系统只对接 JSON 而不用理解 HL7 的分隔符规则。2.4 说明书核心五要素交互、触发、消息、字典、异常一份可执行的接口需求说明书只写消息格式是不够的。我一般会在每个接口条目下固定五个小节交互方式、触发条件、消息结构、数据字典、异常处理。交互方式描述的是传输通道形态比如同步请求-响应、异步通知、文件批量导入。触发条件定义的是什么时候发这条消息比如“门诊医生保存医嘱后”“检验报告审核完成后”。消息结构给出字段级定义包括类型、长度、必填性。数据字典说明代码取值从哪里来比如性别码表是采用 GB/T 2261.1 还是医院自定义。异常处理写清超时、重试、失败通知的规则。五个小节缺一不可否则接口上线后遇到数据不一致时双方会互相推诿。接口编号INT-ORD-001 接口名称门诊医嘱下达通知 交互方式异步消息 MQ 队列 触发条件门诊医生保存新医嘱并通过预审核 消息方向HIS - 集成平台 - 执行系统这个目录结构是接口需求说明书的原子单元。后续的测试用例、监控规则、验收清单都基于这五要素展开所以说这个结构是整份文档的骨架。3. 从需求到接口定义字段、触发、异常与字典的落地细节3.1 字段定义与必填约束的表达方式字段定义是接口需求说明书里最容易被钻空子的部分。描述为“患者姓名”太模糊要明确是“当前就诊卡对应的患者法定姓名”还是“挂号时录入的姓名”甚至要说明是否包含少数民族姓名中的分隔符。我在字段说明表中固定采用六列结构字段名、类型、长度、必填、取值说明、示例。字段名类型长度必填取值说明示例patientIdString32是院内患者主索引 ID全局唯一P00012345visitIdString32是本次就诊序号V202400123orderIdString32是医嘱流水号ORD2024005678orderTextString200是医嘱内容描述血常规doseQtyDecimal10,2否单次剂量不适用于检查类医嘱2.00freqCodeString10否频次代码取值见字典 DIC-FREQBIDrouteCodeString10否给药途径代码取值见字典 DIC-ROUTEPOstatusCodeString2是10-已保存20-已审核30-已作废20代码后面的说明很重要。必填字段不代表业务上一定有值而是说这条消息里必须携带该节点哪怕值为空字符串。取值说明里的“全局唯一”这四个字使得系统间可以依据 patientId 做幂等判断。如果不写取值说明接收方实现者大概率会自己定义一个键后续查问题时无法对齐。3.2 触发条件定义事件、轮询与订阅模式的选择触发条件不能写“实时同步”这种话要精确到业务状态变更点。常见做法是三种模式事件触发、定时轮询、订阅发布。事件触发适合状态突变场景比如医嘱作废、报告发布。定时轮询适合数据量大且不要求秒级响应的场景比如夜间批量同步基础字典。订阅发布适合一对多分发比如一个检验报告要同时通知电子病历、危急值管理系统、护理看板。事件触发要定义事件源和事件编号。事件编号建议全局唯一编码用接口域缩写加序号比如 ORD_STATE_CHANGED。轮询要定义轮询间隔、增量依据字段是更新时间戳还是自增序号。订阅发布要定义主题名称和消费者列表。接口需求说明书里写出这些内容实现阶段才不需要反复确认。3.3 超时、重试与死信参数的实践值超时和重试参数是接口需求说明书里最容易被忽略但上线后最能省事的配置。同步接口要区分连接超时和读超时连接超时通常设 3 到 5 秒读超时按接口业务复杂度设 10 到 30 秒。异步接口则要定义消息确认机制和失败重投次数。参数推荐值说明连接超时3000 ms超过即判定通道不可达读超时10000 ms同步返回类接口建议不超过 30 秒重试次数3超出后进入死信队列重试间隔指数退避 1s/2s/4s避免风暴式重试消息有效期24 小时超过有效期的积压消息直接丢弃幂等键接口编号 业务主键用于接收方去重重试间隔用指数退避而不是固定间隔。如果 100 条消息失败接收方恢复后瞬时全部重投可能导致下游数据库连接被打满。用指数退避配合消息有效期能让系统在故障恢复后以渐进方式消化积压。3.4 数据字典归一化接口层的编码地图数据字典不一致是集成平台最主要的脏数据来源。同一个科室HIS 里叫“心内科”LIS 里叫“心血管内科”办公系统里叫“内一科”。接口需求说明书要提供一张字典映射表明确主数据源和映射关系。字典归一化的落地方式是每个共享字典给定一个编码比如 DIC-DEPT 表示科室字典DIC-DOCTOR 表示医生字典。接口消息里传递主数据源的标准编码接收方通过本地映射表转换。如果接收方收到未映射的代码必须走异常处理流程不能默认存原文。-- 字典映射表示例 CREATE TABLE dim_dict_mapping ( dict_code VARCHAR(20) NOT NULL COMMENT 字典编号, source_code VARCHAR(50) NOT NULL COMMENT 源系统编码, target_code VARCHAR(50) NOT NULL COMMENT 目标系统编码, source_sys VARCHAR(20) NOT NULL COMMENT 源系统标识, target_sys VARCHAR(20) NOT NULL COMMENT 目标系统标识, status TINYINT DEFAULT 1 COMMENT 1有效 0停用, PRIMARY KEY (dict_code, source_code, source_sys, target_sys) );这张表要由集成平台统一维护不能由各业务系统各自维护。说明书中写清字典的维护责任人、发布频率和生效方式新接入的系统才能按统一规则实施映射。3.5 最小可用的接口需求说明书模板理论的最终落点是模板。给一个医嘱查询接口的最小需求说明书片段它具备了可以直接开发的完整信息实现人员拿去做设计、测试人员拿去做用例。{ interfaceId: INT-ORD-QUERY-001, interfaceName: 医嘱信息查询, interaction: SYNC_REQUEST_RESPONSE, trigger: 临床系统按需调用, request: { method: POST, path: /api/v1/orders/query, headers: { X-Request-ID: UUID, X-Timestamp: ISO8601 }, body: { patientId: P00012345, startDate: 2024-01-01, endDate: 2024-01-31, status: 20 } }, response: { code: 0, message: SUCCESS, data: [ { orderId: ORD2024005678, orderText: 血常规, statusCode: 20, createTime: 2024-01-15 09:30:00 } ] }, errorCodes: { 10001: patientId不存在, 10002: 日期范围超过90天, 10003: 无权限访问该患者数据 } }这个 JSON 片段可以直接被后端开发用作接口 mock 的返回值结构。errorCodes 单独列出来比在正文里描述更直观。发送方可以根据返回的 code 决定是否重试业务错误不能重试网络超时可以重试。很多接口需求说明书忽略错误码分级导致调用方把所有失败都当成可重试异常进而造成数据重复插入。4. 接口需求说明书的验证方法模拟器、压力测试与幂等性检查4.1 用模拟器先跑通最小消息集接口需求说明书写得再细致不经过验证都会有歧义。验证的第一层是消息格式验证即在没有真实业务系统的情况下模拟发送方和接收方之间的消息交互。常见做法是搭建一个本地模拟器投入成本低收效最快。发送方模拟器读取说明书中的消息示例按约定频率发送到集成平台队列接收方模拟器消费消息并校验必填字段、枚举值、关联数据是否存在结果记录将校验失败的字段和原始消息落库生成差异报告模拟器不追求真实业务逻辑只验证消息是否符合契约。一个典型的校验脚本用 Python 编写可以直接复用接口字段定义表格生成的 JSON Schema。import json import jsonschema schema { type: object, properties: { patientId: {type: string, minLength: 1}, visitId: {type: string, minLength: 1}, orderId: {type: string, minLength: 1}, statusCode: {enum: [10, 20, 30]} }, required: [patientId, visitId, orderId, statusCode] } with open(sample_message.json, r) as f: message json.load(f) try: jsonschema.validate(message, schema) print(消息格式校验通过) except jsonschema.ValidationError as e: print(f校验失败: {e.message}路径: {list(e.path)})这段脚本的核心价值在于把说明书中的必填约束和枚举取值转化为机器可执行的规则。一旦消息格式在未来版本中变更只需更新 Schema 重新运行脚本就能快速定位所有违反新契约的接口调用方。4.2 接口压力测试怎么测指标设计与执行参数接口需求说明书里写明确性能指标是避免项目验收时扯皮的关键。需要区分最大并发数、吞吐量、响应时间三个概念。指标建议参考值验证方式最大并发连接数200压测工具逐步加压至错误率超 1%吞吐量TPS根据高峰业务量估算高峰日消息总数除以高峰小时数平均响应时间≤ 500 ms同步查询类接口错误率≤ 0.1%失败消息数除以总消息数压测开始前要构造三组数据正常消息、边界数据超长字符串、空必填字段、非法枚举值、故障注入断连、慢响应。正常数据用于测吞吐边界数据用于测容错故障注入用于测超时和重试机制的健壮性。只拿正常数据压测往往发现不了问题。4.3 幂等性验证重复消息不产生重复业务接口幂等性验证是医疗集成平台的硬要求。网络超时后发送方重试同一份医嘱可能被推送两次。接收方必须基于业务主键做去重否则会出现一条医嘱在电子病历中显示两次。CREATE TABLE msg_consume_log ( msg_id VARCHAR(64) NOT NULL COMMENT 消息唯一ID, interface_id VARCHAR(32) NOT NULL COMMENT 接口编号, biz_key VARCHAR(64) NOT NULL COMMENT 业务主键如医嘱号, receive_time DATETIME NOT NULL, consume_status VARCHAR(10) NOT NULL COMMENT SUCCESS / DUPLICATE, PRIMARY KEY (msg_id), UNIQUE KEY uk_biz (interface_id, biz_key) );验证步骤很简单向平台重复投递同一条医嘱消息 10 次检查接收方业务表中医嘱记录只有一条消费日志中 9 条标记为 DUPLICATE。这个测试必须在联调阶段完成而不是上线后凭运气。5. 接口需求说明书的高阶技巧用线索 ID 串联全链路联调阶段最后一个实用技巧是在所有接口消息中强制携带线索 IDTrace ID/CD贯通发送方、集成平台、接收方三层。线索 ID 不参与业务语义只用于日志追踪。每条消息从发送方生成线索 ID 后在集成平台的网关处透传接收方记录到本地日志。出问题时按这个 ID 捞出三个系统的日志比对时间线问题基本能定位到具体环节。线索 ID 的生成规则建议采用“日期 随机数”或 UUID但要保证长度一致、索引友好。集成平台侧要记录消息的到达时间、路由目标、转发时间接收方记录消费开始时间和业务处理结束时间。这三个时间点就能判断瓶颈在网络、平台还是业务处理。监控层面可以基于线索 ID 做三件事统计每条消息的端到端延迟、统计每个接口的日成功率、按失败消息的线索 ID 生成排障报告。这样接口需求说明书不再是纸面文档而是运维体系的一部分。给接口模板追加一行字段即可MessageHeader.TraceID 2024011510300012345678发布新版本接口需求说明书时保留旧版本的线索 ID 规则半年以上因为长尾系统可能迟迟不升级。接口需求说明书的价值就是在医院复杂的系统生态中始终提供一份可对照、可验证、可追责的契约。本文还有配套的精品资源点击获取