前端手记（二）：接口联调与 API 封装

2401_89116968

361人浏览 · 2026-04-19 16:32:29

2401_89116968 · 2026-04-19 16:32:29 发布

所属项目： 面向全场景用药安全的医师助手 Agent
团队： ColdX · 山东大学软件学院 2026年春季项目实训
个人分工： 前端开发 & 界面设计

目录

一、本阶段进展

二、API 封装思路

三、联调重点

四、联调中遇到的问题

五、AI交互过程

六、本阶段产出

相关链接

一、本阶段进展

完成前端任务拆分后，我这一阶段主要推进接口联调。本项目后端能力比较多，如果页面里到处直接写请求路径，后面维护会很麻烦，所以前端需要先把 API 层整理出来。

当前前端把接口统一封装在：

frontend/src/api/medsafe.ts

这一阶段我的重点是把各页面要用到的接口和后端路径对应起来，确认主流程能从前端发起请求，并且能拿到结构化结果。

二、API 封装思路

项目中使用原生 fetch 做轻量封装。统一请求函数负责处理基础路径、请求头、错误信息和返回类型。

我这边关注的不是 fetch 本身，而是接口封装后页面开发会变得更稳定：

首页只需要调用 medsafeApi.health()；
会诊页只需要调用 medsafeApi.multiConsult()；
规则审查页调用 medsafeApi.ruleReview()；
影像页调用 segment/report 相关接口；
Case 页面调用 list/get case 接口。

这样页面代码就不会和 HTTP 细节混在一起。

三、联调重点

本阶段优先联调了几个关键接口：

GET  /health
GET  /api/v1/agents
POST /api/v1/multi-consult
POST /api/v1/review
GET  /api/v1/cases
GET  /api/v1/case/{id}

其中最重要的是 /api/v1/multi-consult。这个接口返回的不只是一段回答，而是完整会诊结果，包括规则审查、专家意见、辩论、安全面板、主席仲裁、Clarify 和最终建议。

这也让我意识到，前端页面必须按结构展示结果，不能把返回内容简单拼成一段文本。

四、联调中遇到的问题

接口联调时主要遇到两个问题。

第一，返回结构比较复杂，字段层级多。比如最终风险等级在 arbitration 中，规则证据在 rule_output.evidence 中，信息澄清在 clarify_output 中。如果不提前整理类型，页面很容易写乱。

第二，有些字段不是每次都会出现。例如并不是所有会诊结果都有 Clarify，也不是所有辩论过程都有明显分歧。因此页面需要做条件渲染，不能假设所有字段一定存在。

为了解决这个问题，我把接口联调和 types/index.ts 的类型定义一起对照，后续页面根据类型来取值。

五、AI交互过程

这一阶段我主要让 AI辅助做接口联调检查。提示词大致是：

请根据 frontend/src/api/medsafe.ts 和 src/types/index.ts，帮我整理前端已经封装了哪些后端接口。
重点关注 /consult、/rule-review、/chat、/imaging、/cases 页面分别依赖哪些 API。
输出联调检查清单，不要重新写接口代码。

AI 帮我把接口按页面分组，并提醒我重点检查 MultiConsultResponse 的字段是否和结果组件对应。根据这个检查清单，我后续把 /consult 页面拆成最终建议、规则证据、辩论过程、专家意见和 Clarify 几个区域。