一致的服务方法名称

https://blueprints.launchpad.net/tempest/+spec/consistent-service-method-names

使服务方法名称保持一致

问题描述

服务客户端是 Tempest 自有的 REST 客户端，用于操作每个 OpenStack 项目的 API。我们计划将服务客户端的方法迁移到 tempest-lib。然而，这些方法名称不一致，从库用户的角度来看，使用这些方法会比较困难。因此，在迁移之前，我们需要使这些名称保持一致，并建立保持一致的方法。

提议的变更

基本上，所有方法名称都应为“<动词>_<资源/对象名称>”，而不是“<资源/对象名称>_<动词>”。以下是我们需要考虑 REST API 方法名称时需要遵循的模式。

  • POST /resources (创建资源)

  • PUT /resources/<id> (更新资源)

  • DELETE /resources/<id> (删除资源)

  • GET /resources (获取资源列表)

  • GET /resources/<id> (获取资源的详细信息)

https://etherpad.openstack.org/p/tempest-consistent-service-method-names 是当前方法名称的调查。基于调查结果，本规范提出了每种模式下一致的方法名称。此外，本规范还提出了用于保持一致方法名称的 hacking 检查。补丁 https://review.openstack.org/168762 是这些 hacking 检查的原型。详细信息如下。

POST /resources

命名规则：“create_<资源名称>”

所有创建方法都遵循此规则，因此我们不需要重命名创建方法。此规则的 hacking 检查是“如果一个方法调用 self.post()，则该方法名称应为 create_<资源名称>”。

PUT /resources/<id>

命名规则：“update_<资源名称>”

所有更新方法都遵循此规则，因此我们不需要重命名更新方法。此规则的 hacking 检查是“如果一个方法调用 self.put()，则该方法名称应为 update_<资源名称>”。

DELETE /resources/<id>

命名规则：“delete_<资源名称>”

删除方法有两种模式：“delete_<资源名称>”和“remove_<资源名称>”。“delete_<资源名称>”的数量为 72，另一种的数量为 11。此外，“delete_<资源名称>”是一个简单的名称，因为它与 HTTP 方法相同。此规则的 hacking 检查是“如果一个方法调用 self.delete()，则该方法名称应为 delete_<资源名称>”。

GET /resources

命名规则：“list_<资源名称>s”

列出资源有三种模式：“list_<资源名称>s”、“get_<资源名称>_list”和“<资源名称>_list”。第一个的数量为 115，第二个的数量为 3，第三个的数量为 2。

一些 Nova API 提供带有详细信息的资源列表，例如 ‘os-hypervisors/detail’ 和 ‘os-availability-zone/detail’。这些方法名称现在是 get_hypervisor_list_details 和 get_availability_zone_list_detail。本规范建议将这些方法合并到此命名规则中，例如

list_availability_zones(self, detail=False):
    url = 'os-availability-zone'
    if detail:
        url += '/detail'
    resp, body = self.get(url)
    ..

通过添加 detail 参数。“GET /resources”和“GET /resources/<id>”调用相同的方法 self.get() 来向服务器发送请求。因此，很难检查调用 self.get() 的方法应基于“GET /resources”或“GET /resources/<id>”的规则。因此，本规范建议对“GET /resources”或“GET /resources/<id>”使用相同的 hacking 检查。这意味着 hacking 检查是“如果一个方法调用 self.get()，则该方法名称应为 show_<资源名称> 或 list_<资源名称>s”。

GET /resources/<id>

命名规则：“show_<资源名称>”

获取资源的详细信息有两种模式：“show_<资源名称>”和“get_<资源名称>”。第一个的数量为 12，第二个的数量为 126。因此，第二个的数量更大。但是，本规范建议将所有“GET /resources/<id>”方法命名为“show_<资源名称>”，以明确与用于“GET /resources”的方法的区别。还有用于“GET /resources”的方法，并且一些资源名称在单数名词和复数名词之间是相同的，例如 “chassis”。因此，最好避免使用“get_<资源名称>”以明确方法行为。此规则的 hacking 检查在上面提到过。

为每个资源分离服务客户端模块

一些服务客户端在一个模块中包含多个资源的的方法。例如，server_client 模块包含“/servers”和“/server_groups”的方法。当前模块的分离是不一致的，本规范建议所有服务客户端模块都将分离为每个资源的单个模块。此外，当前服务客户端的模块名称包含“JSON”，我们需要删除它们。因为当前服务客户端仅支持 JSON，并且这些名称中的“JSON”现在没有意义。

实现

负责人

主要负责人

其他贡献者

里程碑

完成目标里程碑

Liberty

工作项

  • 根据此提案重命名服务客户端的方法。

  • 根据此提案重命名服务客户端的类。

  • 按资源分离服务客户端的模块。

  • 添加基于此提案的 hacking 规则。

参考资料