更新时间： 2026年10月24日
接口原型要解决的是“接口返回不同结果时，用户看到什么、还能做什么”。只画成功页面会让研发在联调时补写大量规则。更稳妥的做法是先整理请求参数和响应字段，再为成功、空数据、校验失败、鉴权失败、超时建立页面状态。用墨刀原型把状态连起来，评审可以直接复现接口与界面的关系。
一、接口原型先写清“输入—处理—输出”
以订单列表为例，输入包括关键词、状态、分页页码和每页数量；处理包括权限校验、筛选和排序；输出包括订单数组、总数、分页信息和错误对象。页面原型要把这些字段落到控件或反馈位置，而不是只写一个“调用接口”。
| 接口信息 | 原型对应位置 | 需要确认的问题 |
|---|---|---|
| 请求参数 | 筛选输入框、下拉框、分页器 | 空值、默认值和格式限制是什么？ |
| 成功响应 | 列表、总数、更新时间 | 无数据和部分字段缺失如何显示？ |
| 错误对象 | 提示、字段错误、重试按钮 | 哪些错误可由用户修正？ |
| 权限状态 | 登录提示、无权页面 | 是否保留原请求地址？ |
二、按状态建立页面与交互
- 先画默认态：筛选条件、分页位置、列表骨架和主操作。
- 复制页面建立加载态，明确骨架屏或进度提示，避免按钮重复提交。
- 建立成功态、空数据态和部分数据态，写清返回列表或调整筛选的入口。
- 建立校验失败、401/403、404、429和500等结果，不必把所有状态都写成同一句错误提示。
错误码要按用户是否能修复来分组。字段格式错误应定位到具体输入；权限错误要说明如何获得权限；服务暂时不可用才提供重试。若接口会返回业务码，原型中记录业务码与用户文案的对应关系，避免研发自行猜测。
三、把字段说明写成可交付标注
每个关键字段至少标注名称、类型、是否必填、示例值、显示规则和异常处理。例如“收货地址”是必填字符串，超过长度时在字段下方提示；“订单金额”由服务端计算，前端只展示，不能作为输入提交。标注还应写出金额单位、时间时区和枚举值。
| 字段 | 类型/示例 | 页面规则 | 异常处理 |
|---|---|---|---|
| orderId | 字符串 / OD20261024088 | 详情页展示，禁止编辑 | 找不到时返回列表 |
| status | 枚举 / pending | 映射中文状态标签 | 未知值显示“状态更新中” |
| amount | 数字 / 128.00 | 保留两位小数并显示币种 | 缺失时显示“待确认” |
四、用一条真实任务走完联调前验收
选一个可复现任务，例如“按待支付筛选订单，打开详情并提交收货地址”。先在原型中按主路径操作，再故意输入空值、错误格式、过期登录和重复点击，记录页面、字段、状态和下一步。开发拿到的不是一张静态图，而是一组可对照的状态与数据约束。
在墨刀中可用交互连线表达跳转，用标注承接字段和接口说明，用评论记录待确认项。接口文档仍应由研发维护，原型负责把接口结果翻译成用户可见状态。
五、避免把接口原型当成接口实现
原型不能证明接口性能、鉴权安全、幂等和数据一致性。需要压测、自动化测试或真实权限验证时，应在研发环境完成。原型阶段只要把输入、输出、状态和可恢复路径说清，就已经显著减少了联调中的猜测。
