答案。

历史上，系统之间接口的描述一直是架构师和集成商的专属，通常仅通过电子邮件交换数据结构。在SOA时代以及更甚的微服务架构下，系统分析师在整合合同的正式化和维护中的角色急剧上升。

问题

错误、不完整或过时的API接口描述会导致：服务不兼容、错误数量增加、无法进行更改而不造成整个系统的级联故障。在多服务项目中，集成点的数量达到几十甚至几百个。

解决方案

系统分析师采用现代实践：

• 通过OpenAPI/Swagger等工具来形式化合同用于REST，gRPC协议，WSDL/XSD用于SOAP；
• 描述典型的调用场景和错误情况；
• 开发事件驱动模型（event-driven model）以实现实时交换；
• 维护最新文档和自动生成合同；
• 与所有涉及服务的拥有者协调变更。

一个重要元素是维护正确的版本控制和变更追踪合同，以及集成测试用例以验证交互。

关键特征：

• 使用机器可读标准（OpenAPI/YAML）。
• 考虑所有使用场景和错误。
• 不同服务团队之间的规范化沟通。

带陷阱的问题。

分析师是否只应与客户和内部开发人员收集API需求？

不，重要的是要涉及所有集成团队，考虑外部合作伙伴的需求，以避免漏洞或不兼容。

在系统交付阶段可以仅记录API吗？

不，API规范在实现之前就应形成和协商，否则在每个阶段都可能会破坏向后兼容性。

OpenAPI规范是否足够作为所有交换情况的文档？

不，OpenAPI描述结构，但交互场景（例如，调用顺序、事件顺序、业务错误）需要分析师在用户文档中详细列出。

常见错误和反模式

• 发布过时的文档或“人类”描述，而不是规范。
• 不记录错误处理和隐性场景。
• 缺乏版本控制和变更追踪。

实际案例

负面案例：物流系统与外部承运商集成。合同仅用“语言”描述。变更发布后，出现了大规模集成故障和延迟。

优点：

• 启动时的最低劳动力投入。

缺点：

• 大规模故障
• 紧急改进
• 负面声誉

正面案例：分析师创建了带有错误/成功场景示例的OpenAPI，协调版本控制，收集所有团队的反馈。

优点：

• 无缝集成新合作伙伴
• 减少入职时间
• 透明的改进

缺点：

• 协商的时间成本
• 需要对技术栈的深入了解