应用程序设置开发

本文档为贡献者提供了向 GitLab 添加应用程序设置的指南。

应用程序设置存储在 application_settings 表中。每个设置都有自己的列，且应该只有一行。

Duo 相关的应用程序设置存储在不同的表中。

添加新的应用程序设置

首先，您需要决定是否有必要添加应用程序设置。 添加新设置时，请考虑我们的配置原则。

我们倾向于将相关的应用程序设置保存在单个 JSONB 列中，以避免使 application_settings 表变得更宽。此外，向现有列添加新设置不需要数据库审查，因此可以节省时间。

要添加新设置，您需要：

• 检查是否有现有的 JSONB 列可用于存储新设置。
• 如果存在现有的 JSON 列，则：
  • 在 ApplicationSetting 模型中，像 rate_limits 一样向 JSONB 列添加新设置。
  • 更新列的 JSON 架构验证器，如 rate_limits 验证器。
• 如果没有可用的现有 JSON 列，则：
  • 向 application_settings 表添加新的 JSON 列以存储，参考此合并请求。
  • 添加约束以确保列始终存储哈希值，参考此合并请求。
  • 创建后续问题，将现有的相关列移动到这个新创建的 JSONB 列。遵循将数据库列迁移到 JSONB 列的流程。
• 将新设置添加到可见属性列表中。
• 如果设置有默认值，将其添加到 ApplicationSettingImplementation#defaults 中。
• 如果设置有默认值，添加默认值测试。
• 为新字段添加验证到 ApplicationSetting 模型。
• 为验证和默认值添加模型测试
• 找到正确的视图文件或创建一个新文件，并向新设置添加表单字段。
• 更新API 文档。应用程序设置会自动在 REST API 上提供。
• 运行 scripts/cells/application-settings-analysis.rb 脚本，根据 db/structure.sql 和 API 文档，在 config/application_setting_columns/*.yml 生成定义 YAML 文件，并更新 cells/application_settings_analysis 文档文件。创建定义文件后，确保在其中将 clusterwide 键设置为 true 或 false。设置 clusterwide: true 意味着属性值从 leader cell 复制到其他 cell 在 Cells 架构的上下文中。在大多数情况下，clusterwide: false 更可取。

数据库迁移示例

class AddNewSetting < Gitlab::Database::Migration[2.1]
  disable_ddl_transaction!

  def up
    with_lock_retries do
      add_column :application_settings, :new_setting, :text, if_not_exists: true
    end

    add_text_limit :application_settings, :new_setting, 255
  end

  def down
    with_lock_retries do
      remove_column :application_settings, :new_setting, if_exists: true
    end
  end
end

模型验证示例

validates :new_setting,
          length: { maximum: 255, message: N_('is too long (maximum is %{count} characters)') },
          allow_blank: true

将数据库列迁移到 JSONB 列

要将列迁移到 JSONB，请在 JSONB 访问器下添加新设置。

添加 JSONB 设置

• 遵循添加新应用程序设置的流程。
• 使用与现有列相同的名称以保持一致性。
• 在过渡期间，Rails 将相同的信息写入现有的数据库列和新 JSONB 列下的字段。这确保了数据一致性并防止了停机时间。

必需的清理步骤

您必须遵循删除列的流程来删除原始列。这是一个必需的多里程碑过程，涉及：

1. 忽略该列。
2. 删除该列。
3. 删除忽略规则。

默认值

当使用 jsonb_accessor 默认值将设置迁移到 JSONB 列时，请从 ApplicationSettingImplementation.defaults 中删除它们，因为 JSONB 访问器优先于 defaults 方法。

添加 Duo 相关设置

我们在 application_settings 表中有几个实例范围的 GitLab Duo 设置。这些包括 duo_features_enabled（布尔值）、duo_workflow（jsonb）和 duo_chat（jsonb）。

在某个时候，我们意识到将新的实例范围设置添加到不同的表中更简单。从现在开始，任何新的 Duo 相关的实例范围设置都应该添加到 ai_settings 表中。

对于组或项目级别的 Duo 设置，还有一个 namespace_ai_settings 表。

级联设置框架 假设实例范围的设置在 application_settings 表上，组设置和项目设置分别在 namespace_settings 和 project_settings 上。如果您正在考虑为 Duo 添加级联设置，这可能是一个使用 application_settings 而不是 ai_settings 的好理由。