为 oslo 库提供一组示例¶
https://blueprints.launchpad.net/oslo.messaging/+spec/oslo-examples
为每个 oslo 库提供一组示例，以说明特定库 API 的用例。
问题描述¶
目前，我们没有任何示例（除了测试）来展示如何使用每个 oslo 库。功能测试接近完成，但它们更抽象，用于检查功能，而不是说明如何在应用程序中使用它。
希望能够提供一些具有表现力的示例，这些示例可以作为代码的文档。
提议的变更¶
在每个 oslo 库仓库中创建一个 examples 文件夹，并将一些库 API 的示例放在其中。
示例最好像一个小型应用程序，并且基于某个应用程序领域构建，而不是像“客户端 A 调用服务器 B 并发送请求 1”那样。
我们可以像 taskflow 中那样为 oslo.messaging 实现一组示例
https://github.com/openstack/taskflow/tree/master/taskflow/examples 这些示例都在单元测试运行期间进行测试，以确保它们按预期工作。
它们也应该作为文档的一部分，并构建为文档。文档文件夹中将有一个单独的文件，其中包含 examples 文件夹中的代码。
https://raw.githubusercontent.com/openstack/taskflow/master/doc/source/examples.rst
一个示例可能如下所示
bobMessenger = messenger.Client(cfg, 'Bob')
aliceMessenger = messenger.Client(cfg, 'Alice')
server = messenger.Server(cfg)
server.run()
bobMessenger.run()
aliceMessenger.run()
time.sleep(2) # wait for all participants discover each other
assertEqual(server.clientsList,
bobMessenger.clientsList,
aliceMessenger.clientsList)
bobMessenger.sendMessage('Alice', 'Hi, there!')
assertEqual(bobMessenger.history['Alice'],
aliceMessenger.history['Bob'])
或者对于请求-回复模式
fibServer = fibonacci.Server(cfg)
fibClient = fibonacci.Client(cfg)
fibServer.run()
value = fibClient.getFibonacci(20)
assertEqual(value, 6765)
备选方案¶
基于一些真实世界应用程序构建的功能测试，该应用程序在其实现中使用 oslo 库。这是一种间接测试，可以显示如何改进或优化库。这种测试也作为用例示例，因为我们测试的是使用库的应用程序，因此展示了如何使用 API。
https://blueprints.launchpad.net/oslo.messaging/+spec/oslo-functional-testing-apps
Impact on Existing APIs¶
无
安全影响¶
无
性能影响¶
无
Configuration Impact¶
无
开发人员影响¶
oslo.* API 的任何未来更改都应反映在示例中。
Testing Impact¶
所有示例都应通过单元测试运行。
实现¶
负责人¶
- 主要负责人
- 其他贡献者
里程碑¶
完成目标里程碑： * liberty-3
工作项¶
为每个 oslo 库开发示例
taskflow - 作为模式
我们将从 oslo.messaging 和 oslo.concurrency 开始，并在完成工作后继续到其他库。
孵化¶
N/A
文档影响¶
示例应用程序应在文档中发布。
请参阅 taskflow 中的实现方式
https://raw.githubusercontent.com/openstack/taskflow/master/doc/source/examples.rst
这将被转换为
https://docs.openstack.org/developer/taskflow/examples.html
依赖项¶
oslo.*
参考资料¶
无
