Question

接口，特别是软件系统外部的，是任何软件系统中风险最高的部分之一，因此总结有哪些接口以及它们如何工作是非常有用的。

意图

这个部分的目的是回答下面几类问题。

关键的外部接口是哪些？

o 比如，你的系统和其他系统之间的（不管它们在你的环境内部还是外部）。

o 比如，暴露出来用于消费的API。

o 比如，从你的系统导出的文件。

每个接口都从技术角度考虑过了吗？

o 接口的技术定义是什么？

o 如果使用了消息，哪些队列（点对点）和话题（发布-订阅）是用于通信的组件？

o 消息的格式是什么（比如，纯文本或DTD/Schema定义的XML）？

o 同步还是异步？

o 异步消息的连接有保障吗？

o 如果必要，人们会长期订阅吗？

o 消息能否打乱顺序接收，这是一个问题吗？

o 接口是否幂等？

o 接口是否总是可用，或者比如说你是否需要在本地缓存数据？

o 性能/可伸缩性/安全性/其他是如何满足的？

每个接口都从非技术角度考虑过了吗？

o 接口所有权属谁？

o 接口多久会有变化，版本怎么处理？

o 是否有服务级别的协议？

结构

我倾向于简单地（以“从X到Y”的形式）列出接口，附上一小段描述接口特征的叙述。为了在语境中理解这些接口，我会包含一个强调接口的简化版容器或组件图。

动机

写这个部分的动机是为了确保已经考虑和理解过接口，因为它们往往有风险却容易被忽视。如果没有得到接口的细节，这个部分可以作为一个检查清单，成为团队要承担的工作项目来源。

受众

主要是软件开发团队中的技术人员。

是否必须

不是，只有当构建的东西有一个或更多复杂接口时，我才会包含这个部分。举个例子，在标准的“Web服务器→数据库”式软件系统中我不包含它，但如果Web应用程序需要跟一个通过API消费信息的外部系统通信，我就会包含这个部分。