接口说明文档
技能名称: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