Help us learn about your current experience with the documentation. Take the survey.

Duo Workflow 应用编码风格的使用案例

  • Tier: Ultimate with GitLab Duo Workflow
  • Offering: GitLab.com
  • Status: Experiment

入门指南

下载解决方案组件

  1. 从您的客户团队获取邀请码。
  2. 使用邀请码从 解决方案组件商店 下载解决方案组件。

Duo Workflow 使用案例：通过风格指南改进 Java 应用

本文档介绍使用提示词和上下文库的 GitLab Duo Workflow 解决方案。该解决方案的目的是根据定义的风格改进应用程序编码。

此解决方案提供 GitLab issue 作为提示词，风格指南作为上下文，旨在使用 GitLab Duo Workflow 自动化 Java 风格指南到代码库。提示词和上下文库使 Duo Workflow 能够：

  1. 访问存储在 GitLab 仓库中的集中式风格指南内容，
  2. 理解特定领域的编码标准，以及
  3. 在保持功能的同时，对 Java 代码应用一致的格式。

有关 GitLab Duo Workflow 的详细信息，请查看 此文档。

主要优势

  • 在所有 Java 代码库中强制执行一致的风格
  • 无需人工干预即可自动应用风格
  • 在提高可读性的同时保持代码功能
  • 与 GitLab Workflow 集成以实现无缝实施
  • 减少在解决风格问题上花费的代码审查时间
  • 作为开发人员理解风格指南的学习工具

示例结果

正确配置后，提示词会将您的代码转换为符合企业标准，类似于此差异中显示的转换：

Duo Workflow 输出

风格指南应用

配置解决方案提示词和上下文库

基本设置

要运行代理工作流程来审查和将风格应用到您的应用程序，您需要设置此使用案例提示词和上下文库。

  1. 通过克隆 Enterprise Code Quality Standards 项目来设置提示词和上下文库
  2. 创建一个 GitLab issue Review and Apply Style，使用库文件 .gitlab/workflows/java-style-workflow.md 中的提示词内容
  3. 在 issue Review and Apply Style 中，按照 配置部分 详细配置工作流变量
  4. 在您的 VS Code 中，使用项目 Enterprise Code Quality Standards，通过简单的 工作流提示词 启动 Duo Workflow
  5. 与 Duo Workflow 协作，审查建议的计划和自动化任务，如需要可向工作流添加进一步输入
  6. 审查并提交 样式化的代码更改到您的仓库

示例 Duo Workflow 提示词

遵循 issue <issue_reference_id> 中对文件 <path/file_name.java> 的说明。确保访问 issue 中提到的任何 issues 或 GitLab 项目以获取所有必要信息。

这个简单的提示词很强大，因为它指示 Duo Workflow：

  1. 读取特定 issue ID 中的详细要求
  2. 访问引用的风格指南仓库
  3. 将指南应用到指定文件
  4. 遵循 issue 中的所有说明

配置指南

提示词在解决方案包中的 .gitlab/workflows/java-style-workflow.md 文件中定义。此文件作为创建 GitLab issues 的模板，用于指导工作流代理制定自动化风格指南审查并应用更改的计划。

在 .gitlab/workflows/java-style-workflow.md 的第一部分，定义了您需要为提示词配置的变量。

变量定义

变量直接在 .gitlab/workflows/java-style-workflow.md 文件中定义。此文件作为创建 GitLab issues 的模板，用于指导 AI 助手。您将在创建新 issue 之前修改此文件中的变量。

1. 风格指南仓库作为上下文

提示词必须配置为指向您组织的风格指南仓库。在 java-style-prompt.md 文件中，替换以下变量：

  • {{GITLAB_INSTANCE}}: 您的 GitLab 实例 URL（例如 https://gitlab.example.com）
  • {{STYLE_GUIDE_PROJECT_ID}}: 包含您的 Java 风格指南的 GitLab 项目 ID
  • {{STYLE_GUIDE_PROJECT_NAME}}: 您风格指南项目的显示名称
  • {{STYLE_GUIDE_BRANCH}}: 包含最新风格指南的分支（默认：main）
  • {{STYLE_GUIDE_PATH}}: 风格指南文档在仓库中的路径

示例：

GITLAB_INSTANCE=https://gitlab.example.com
STYLE_GUIDE_PROJECT_ID=gl-demo-ultimate-zhenderson/sandbox/enterprise-java-standards
STYLE_GUIDE_PROJECT_NAME=Enterprise Java Standards
STYLE_GUIDE_BRANCH=main
STYLE_GUIDE_PATH=coding-style/java/guidelines/java-coding-standards.md

2. 应用风格改进的目标仓库

在同一个 java-style-prompt.md 文件中，配置将风格指南应用到哪些文件：

  • {{TARGET_PROJECT_ID}}: 您 Java 项目的 GitLab ID
  • {{TARGET_FILES}}: 要定位的特定文件或模式（例如 “src/main/java/**/*.java”）

示例：

TARGET_PROJECT_ID=royal-reserve-bank
TARGET_FILES=asset-management-api/src/main/java/com/royal/reserve/bank/asset/management/api/service/AssetManagementService.java

关于 AI 生成代码的重要说明

⚠️ 重要免责声明：

GitLab Workflow 使用代理式 AI，这是非确定性的，意味着：

  • 即使输入相同，运行结果也可能有所不同
  • AI 助手对风格指南的理解和应用每次可能略有不同
  • 本文档中提供的示例仅供参考，您的实际结果可能有所不同

使用 AI 生成代码更改的最佳实践：

  1. 始终审查生成的代码：在彻底的人工审查之前，不要合并 AI 生成的更改
  2. 遵循正确的合并请求流程：使用您标准的代码审查程序
  3. 运行所有测试：确保在合并前所有单元和集成测试都通过
  4. 验证风格合规性：确认更改符合您的风格指南期望
  5. 增量应用：考虑最初将风格更改应用到较小的文件集

请记住，此工具旨在帮助开发人员，而不是在代码审查过程中取代人工判断。

分步实施

  1. 创建风格指南 Issue

    • 在您的项目中创建一个新的 issue（例如 Issue #3）

    • 包含要应用的风格指南的详细信息

    • 如适用，引用外部风格指南仓库

    • 指定要求，例如：

      任务：代码风格更新
描述：将企业标准 Java 风格指南应用到代码库。
参考风格指南：Enterprise Java Style Guidelines (https://gitlab.com/gl-demo-ultimate-zhenderson/sandbox/enterprise-java-standards/-/blob/main/coding-style/java/guidelines/java-coding-standards.md)
约束条件：
- 遵循企业标准 Java 风格指南
- 保持功能不变
- 实现自动化风格检查

  2. 配置提示词

    • 从 java-style-prompt.md 复制模板
    • 填写所有配置变量
    • 添加任何项目特定的例外或要求

  3. 通过 GitLab Workflow 执行

    • 将配置好的提示词提交给 Duo Workflow

    • Duo Workflow 将运行一个多步骤过程，如示例工作流执行所示：

      • 使用特定工具（run_read_only_git_command、read_file、find_files、edit_file）规划任务
      • 访问引用的 issue
      • 检索企业 Java 风格指南
      • 分析当前代码结构
      • 将风格指南应用到指定文件
      • 验证更改保持功能
      • 提供所做的更改的详细报告

  4. 审查和实施

    • 审查建议的更改
    • 在您的代码库中实施更改
    • 运行测试以确保功能保持不变
    • 通过 GitLab Workflow 界面监控任务进展

示例工作流执行

正确配置后，GitLab Workflow 将执行应用风格指南的详细计划。以下是工作流执行的示例：

示例工作流计划

AI 助手首先使用特定工具创建执行计划：

  1. 通过使用 run_read_only_git_command 在 https://gitlab.com/gl-demo-ultimate-zhenderson/sandbox/enterprise-java-standards.git 上检索文件 coding-style/java/guidelines/java-coding-standards.md 的内容来访问 Java 风格指南，支持工具：run_read_only_git_command

  2. 使用 read_file 工具读取并分析 AssetManagementService.java 的当前内容，了解其结构并识别需要风格更新的区域，支持工具：read_file

  3. 使用 find_files 搜索项目中的任何相似文件，以确保在相关服务类中一致应用风格，支持工具：find_files

  4. 使用 edit_file 工具编辑 AssetManagementService.java 以应用风格指南，重点关注：

    • 包和导入组织
    • 类和方法文档
    • 代码缩进和间距
    • 注解放置
    • 方法参数格式化，支持工具：edit_file

  5. 使用 grep_files 检查整个代码库中的注解模式，确保所有 Lombok 注解（@Service、@RequiredArgsConstructor、@Slf4j）都根据风格指南正确格式化，支持工具：grep_files

示例分析输出

然后助手分析文件和要求：

我分析了 issue #3 和 AssetManagementService.java 文件。以下是发现的内容：

  1. Issue #3 是关于将企业标准 Java 风格指南应用到 Royal Banking 代码库。

  2. AssetManagementService.java 文件位于 asset-management-api 模块中。

  3. 风格指南存储在单独的 GitLab 项目中，位于 gl-demo-ultimate-zhenderson/sandbox/enterprise-java-standards。

  4. 当前的 AssetManagementService.java 文件包含：

    1. 包和导入语句
    2. 带有 Spring 注解的服务类
    3. 一个用于检查资产可用性的公共方法
    4. Lombok 注解
    5. Javadoc 注释

该问题要求：

  1. 根据企业标准 Java 风格指南进行格式化
  2. 实现自动化风格检查
  3. 保持现有功能
  4. 确保所有测试在风格更新后通过

要继续实施，您需要：

  1. 从 Enterprise Java Standards 项目访问 Java 风格指南
  2. 将风格指南应用到 AssetManagementService.java
  3. 验证更改不影响功能
  4. 确保所有更新后测试通过

示例实施结果

执行后，助手提供转换后的代码并解释所做的更改，包括：

  1. 应用的风格指南摘要
  2. 具有正确格式的转换后代码
  3. 关键风格更改的解释
  4. 对自动化风格执行的建议

更改通常包括：

  • 标准化的导入排序
  • 运算符周围的一致间距
  • 正确的 Javadoc 格式化
  • 标准化的方法参数对齐
  • 一致的大括号放置

同时确保代码保持其原始功能。

示例教程使用案例：Royal Reserve Bank Java 项目

此仓库包含一个银行教程示例，演示风格指南在实际场景中的应用。Royal Reserve Bank 项目遵循微服务架构，包含多个 Java 服务：

  • Account API
  • Asset Management API
  • Transaction API
  • Notification API
  • API Gateway
  • Config Server
  • Discovery Server

示例示例将企业风格指南应用到 AssetManagementService.java 类，演示正确的格式化：

  1. 导入组织
  2. Javadoc 标准
  3. 方法参数对齐
  4. 变量命名约定
  5. 异常处理模式

为您的组织定制

要为您的组织需求调整此提示词：

  1. 风格指南替换

    • 指向您组织的风格指南仓库
    • 引用您的特定风格指南文档

  2. 目标文件选择

    • 选择要应用风格指南的特定文件或模式
    • 优先考虑高可见性代码文件进行初始实施

  3. 额外验证

    • 添加自定义验证要求
    • 指定标准风格规则的任何例外

  4. 与 CI/CD 集成

    • 配置提示词作为 CI/CD 管道的一部分运行
    • 设置自动化风格检查以确保持续合规

故障排除

常见问题及其解决方案：

  • 访问被拒绝：确保 AI 代理有权限访问两个仓库
  • 缺少风格指南：验证风格指南路径和分支是否正确
  • 功能更改：应用风格更改后运行所有测试以验证功能

贡献

欢迎通过以下方式增强此提示词：

  • 添加更多风格规则解释
  • 为不同 Java 项目类型创建示例
  • 改进验证工作流
  • 添加与更多静态分析工具的集成