接口说明文档

技能名称:sa-api-design

背景与适用场景

架构设计告诉你有哪些模块,但还需要明确模块之间怎么通信、对外暴露哪些接口、调用外部系统的接口规范是什么。这个技能把架构级的接口设计细化到API级别,让前后端和外部系统对接时有统一的协议可遵循。

输入与输出

你需要提供:架构设计说明书中的接口架构部分 + 需求规格说明书 + 数据字典(含数据流图、ER图)+ 外围系统清单和接口文档。

你将获得:系统边界接口设计文档,含:对外暴露接口定义(请求/响应格式、错误码)、外部调用接口规范、支撑上述接口的内部关键接口定义、统一的接口协议规范。

流程说明

Agent 先检索接口设计知识库,然后和你确认边界接口的范围。接着分三步设计:对外暴露的接口有哪些、调用外部系统的接口怎么对接、支撑上述接口的内部关键接口怎么定义。每一步确认后再进入下一步,最终产出统一的接口协议规范文档。

flowchart TD s0["接口设计知识库检索:从工程知识库加载集成模式、接口规范、避坑经验"] s1["边界接口范围确认:从架构 §6 提取已定义接口,确认设计范围"] s2["边界接口范围问询轮"] s3["对外暴露接口详细设计:请求/响应定义、业务规则、交互流程"] s4["外部调用接口对接设计:调用信息、请求构造、响应处理、可靠性保障"] s5["内部关键接口定义:识别关键内部调用、定义级说明"] s6["文档整合与全文梳理"] s0 --> s1 s1 --> s2 s2 --> s3 s3 --> s4 s4 --> s5 s5 --> s6