仪表板的代码质量改进和测试基础设施

https://blueprints.launchpad.net/watcher/+spec/dashboard-code-quality-testing

通过消除阻碍静态分析的模式、采用集中式配置管理以及重构测试以支持可重用的 fixture（遵循主 Watcher 项目中建立的模式），改进 Watcher 仪表板的代码质量和测试基础设施。

这项工作解决了 Watcher 仪表板代码库中的技术债务，这些债务阻碍了可维护性和开发人员的生产力。这些更改将改进 IDE 支持，实现更好的静态分析，并为未来的开发创建一个更易于维护的代码库。

问题描述

Watcher 仪表板当前使用会创建鲁棒性问题并降低代码质量的代码模式

  • 直接符号导入（from X import Y）会创建在重构期间可能中断的脆弱依赖关系，并使理解模块关系变得困难

  • 用于静态属性的反射辅助函数（getattr/hasattr/setattr）隐藏了潜在的 AttributeError 错误，并使代码行为不可预测

  • Django 设置通过 getattr() 在整个代码库中直接访问，散布着默认值且没有验证，从而导致静默失败和配置漂移

  • 测试基础设施缺乏可重用的 fixture 模式，导致测试设置不一致和潜在的测试污染

  • 没有测试结构来适应未来使用 playwright 的功能测试

  • 不一致的代码模式使代码库更难审查和维护

这些模式通过隐藏错误、创建脆弱的依赖关系以及使代码库更难理解和维护来降低代码的鲁棒性。

用例

  • 作为 Watcher 仪表板开发者，我希望能够放心地重构代码，相信错误会在早期被捕获，而不是被反射辅助函数隐藏，以便我可以在不引入微妙错误的风险下进行更改。

  • 作为 Watcher 核心审查员，我希望能够高效地审查代码更改，而不会被不一致的模式或调试测试问题分散注意力，以便我能够专注于正在实现的功能。

  • 作为新贡献者，我希望能够快速理解代码库并编写遵循既定模式的代码，以便我能够在无需在风格和结构方面进行大量指导的情况下有效地做出贡献。

提议的变更

消除阻碍静态分析的代码模式，并使测试基础设施现代化，以符合既定的 OpenStack 实践。这些更改将改进 IDE 支持，实现更好的静态分析，并创建一个更易于维护的代码库。

主要重点是将直接符号导入转换为整个代码库中的模块级导入，将静态反射辅助函数替换为直接属性访问，并通过一个带类型的配置模块集中化 Django 设置访问。测试基础设施将被重构以支持可重用的 fixture，遵循主 Watcher 项目中使用的模式，测试将组织在 watcher_dashboard/test/unit/ 和新的 local_fixtures/ 和 playwright/ 目录中，以满足未来的测试需求。

一个集中式配置模块（watcher_dashboard/config.py）将提供带类型、经过验证的 Django 设置访问，消除整个代码库中散布的 getattr(settings, ...) 用法。该模块将受到 manila-ui 的 features.py 模式的启发，但会通过类型提示和全面的验证进行增强。将添加 CI 强制执行以防止这些模式的回归，并创建全面的贡献者文档来指导未来的开发实践。

备选方案

现状： 继续使用当前模式。被拒绝 - 随着新代码遵循现有的反模式，技术债务不断累积。

跳过测试重构： 保留扁平的测试结构。被拒绝 - 错失了与主 Watcher 项目模式保持一致并为未来使用 playwright 进行功能测试做准备的机会。

数据模型影响

无。

REST API 影响

无。

安全影响

积极影响：带有验证的集中式配置降低了配置错误的风险。显式导入提高了代码可审计性。没有引入新的安全问题。

通知影响

无。

其他最终用户影响

无。这些是对于仪表板用户透明的内部改进。

性能影响

微小的积极影响：@memoized.memoized 装饰器用于 config 函数，可以对设置查找进行有效的缓存。模块级导入只解析一次，而不是每次使用时都解析。

其他部署者影响

无。

开发人员影响

显著的积极影响

  • 改进的 IDE 支持：模块级导入可以在所有现代 Python IDE 中实现准确的自动完成、转到定义和重构

  • 静态分析：带类型提示的 config 模块和减少的反射可以启用 mypy 检查并在运行时之前捕获错误

  • 更轻松的测试：fixture 模式减少了样板代码；config 模块函数比设置访问更容易模拟

  • 更好的文档：集中式 config 模块充当可用设置的实时文档，并带有文档字符串

实现

负责人

主要负责人

sean-k-mooney

其他贡献者

无

工作项

  • 重构导入模式，在整个代码库中使用模块级导入

  • 将静态反射辅助函数替换为直接属性访问

  • 为 Django 设置访问创建集中式配置模块

  • 重构测试目录以支持可重用的 fixture 和未来的测试

  • 添加 CI 强制执行导入和反射策略

  • 创建全面的贡献者文档，以制定代码质量标准

  • 实施可选的类型提示和 mypy 配置

请参阅详细的实施计划：https://gist.github.com/SeanMooney/f56c7fd6f55ac48958a5c549e1701b6c

依赖项

没有新的运行时依赖项。

测试依赖项使用在 OpenStack 中经过验证的现有库进行扩展

  • fixtures>=3.0.0 - 可重用的测试 fixture 模式（已在 Nova、Placement 和主 Watcher 项目中使用）

所有其他依赖项已在使用中

  • horizon.utils.memoized - 配置缓存（正在使用中）

  • django.conf.settings - Django 设置（正在使用中）

  • unittest.mock - 测试模拟（正在使用中）

测试

集中式配置模块需要全面的单元测试覆盖率，以确保适当的验证和错误处理。文档将通过 Sphinx 构建和 RST 语法检查进行验证。

重构测试结构将能够添加使用 playwright 的功能测试，最终将使用新的 zuul 作业进行测试。这超出了本规范的范围。

文档影响

将创建全面的贡献者文档，以建立和维护新的代码质量标准。将添加两个新的文档文件：doc/source/contributor/code_quality.rst 包含有关导入模式、配置访问、反射使用和测试实践的策略和标准，以及 doc/source/contributor/code_patterns.rst 提供具体的示例和要避免的常见反模式。

参考资料

历史

修订版

发布名称

描述

2026.1

引入