如何系统地记录API的需求？

Question

我目前正在从事一个项目，在该项目中，我必须分析两个特定IT系统的需求，这些系统使用云计算，用于cloud。换句话说，我必须分析这些系统对Cloud的需求，这样他们就能够在实现当前目标的同时切换它。

让我举一个例子，说明项目A的一些非正式要求：

1. 当通过API在云中启动虚拟机时，必须能够为根用户指定内存大小、CPU类型、操作系统和SSH密钥。
2. 必须能够监控每台虚拟机每小时的入站和出站网络流量。
3. API必须支持将公共IP分配到虚拟机和检索公共IP。
4. ..。

在该项目的稍后阶段，我将分析一些将云API标准化的云计算标准，以找出当前标准中可能存在的缺陷。调查结果可能而且很可能是，某一标准不支持监测资源使用情况，因此目前无法使用。

目前，我正试图找到一种方法，系统地记录和分类我的需求。我觉得我目前把它们写下来的方式(如上面的三点)太不正式了。

我读过几本需求工程和软件体系结构书籍，但它们都过于关注细节和实现。我确实只关心通过API/接口提供的功能，我不认为UML图等是正确的选择。我认为目前我收集到的需求可以被描述为用户故事，但是对于复杂的需求分析来说，这已经足够了吗？也许我应该“再深入一点”.

Answer 1

阅读文档化软件架构，第二版:视图和超越，第7章:文档化软件接口。

或者至少检查一些著名的API文档，比如Google (地图，GData -过时但很复杂)，亚马逊(S3 )，或者查看微软应用程序和服务的文档，这些文档聚集在MSDN上(对于现场服务，甚至对于视窗)。

通常，API文档有三个部分：

• 关于这件事是什么的概述，有人可以从中看出什么，也许是一个架构概述。
• 开发人员指南，用API解释一些常见的任务，通常使用代码示例和可下载的示例应用程序。
• 它应该如何工作的API引用

理论上--如果我们相信Brook的神秘的男人月--你可以设计文档并确保有一个匹配的实现。

现在开始练习

了

API的设计需求就像任何软件设计一样。

1. 请使用API的不同参与者(例如使用上下文图 )。
2. 使用用例详细描述每个参与者对系统的典型需求
3. 对于每个用例，您将开发一组关于如何使用想象系统的场景( 编写有效用例一书可能会在这方面帮助您)
4. 您可以创建鲁棒性图、序列图或活动图，但是您可以根据场景设计行为，以确定需要传递哪些消息。
5. 通过查看每条消息成功传递所需的参数，从消息中推断出底层数据体系结构。

很多人会从底层的数据结构开始，但我认为这很愚蠢:计算机(和对象)是关于交互的。为了运行成功的交互，您需要了解任何一方都需要进行哪些交流。数据只是这些交互的参数。

我通常做活动图或简单的流程图，将传递的参数显示为对象或类。也就是说，有一个控制流，但是我们看到其中一方传递给另一方的信息。

在您完成所有这些之后，您将再次抓取您的场景，并开始进行验收测试。这是因为API将由计算机客户端使用，因此，您的第一个代码应该是一个计算机客户端，它作为测试进行自动检索。

验收测试要么以“提供的输入”-“预期输出”形式编写，要么作为代码编写。您可以找到许多关于BDD和TDD的书籍，这将向您解释如何编写好的测试。

此外，在这里，您将开始编写关于REST接口和类似内容的书籍，以防您正在构建web，因为您的测试必须从第一天起就可执行。

在这些场景中，您还构建了示例代码和开发人员指南。

从序列图和数据体系结构图中，您可以开发API引用。

添加一些HTML，确保所有的测试都通过，并且您的应用程序是快速、安全和健壮的，让我们开始使用它吧！

(我知道，这是瀑布式的:敏捷是一样的，除了你总是只做其中的一小部分，例如，几个场景每冲刺)