基于 Go 的电子病历智能助手与 HIS 对接实战：接口契约设计

5.4 接口契约：/v1/cds/suggestions

这是智能助手与医院信息系统（HIS）交互的核心入口，负责接收患者主诉及体征数据，并返回初步的临床建议。在实现时，我们采用严格的 JSON Schema 校验，确保传入数据的完整性。

请求示例

{
  "patientId": "p123",
  "chiefComplaint": "发热、咳嗽 3 天",
  "vitalSigns": {
    "temperature": 38.5,
    "heartRate": 90
  }
}

注意这里补全了 vitalSigns 对象，实际开发中需根据业务需求动态扩展字段。对于医疗场景，体温、心率等数值类型必须严格限制范围，避免异常值干扰模型推理。

Go 语言实现要点

在 Go 端定义结构体时，利用 json 标签映射后端字段，同时增加 validate 标签进行前置校验。这样不仅能保证类型安全，还能在序列化前快速拦截非法请求。

type SuggestionRequest struct {
	PatientID       string         `json:"patientId" validate:"required"`
	ChiefComplaint  string         `json:"chiefComplaint" validate:"required,min=1,max=200"`
	VitalSigns      VitalSignsData `json:"vitalSigns"`
}

type VitalSignsData struct {
	Temperature float64 `json:"temperature"`
	HeartRate   int     `json:"heartRate"`
}

这种结构不仅保证了类型安全，还能在序列化前快速拦截非法请求。对于 HIS 对接场景，建议额外增加签名验证中间件，防止数据被篡改。响应处理上，建议统一封装错误码结构，便于前端或调用方快速定位问题。