<fix>[sdk]: support data volume live storage migration sdk

[zstack-robot-1]

Resolves: ZSTAC-73538
Resolves: ZSV-10831

Change-Id: I61777962787a77777478776f6574616663776a6d

sync from gitlab !8956

[coderabbitai]

高层概览

在 PrimaryStorageMigrateVmAction 中新增了一个 dataVolumeUuids 公共字段，类型为 java.util.List，并附加了 Param 注解。该字段用于支持虚拟机数据卷迁移操作的输入参数。

变更清单

类别 / 文件	变更摘要
虚拟机迁移参数扩展 sdk/src/main/java/org/zstack/sdk/PrimaryStorageMigrateVmAction.java	新增 dataVolumeUuids 字段（List 类型），用于指定待迁移的数据卷 UUID 集合，扩展了虚拟机存储迁移的功能参数

代码审查工作量评估

🎯 1 (微小) | ⏱️ ~3 分钟

诗歌

🐰 一片新绿添枝头，
数据卷列入迁移秀，
字段简洁功能优，
存储流转不用愁，
参数扩展乐悠悠！

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	标题准确描述了主要变更，即为SDK添加数据卷实时存储迁移支持。
Description check	✅ Passed	描述内容虽然简洁，但与变更相关联，提供了问题追踪号和来源信息。
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch sync/tao.gan/ZSV-10831@@2

---

📜 Recent review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 91cdd37 and 55ac76a.

📒 Files selected for processing (1)

• sdk/src/main/java/org/zstack/sdk/PrimaryStorageMigrateVmAction.java

🧰 Additional context used

📓 Path-based instructions (1)

**/*.java

⚙️ CodeRabbit configuration file

**/*.java: ## 1. API 设计要求

• API 命名：
  • API 名称必须唯一，不能重复。
  • API 消息类需要继承 APIMessage；其返回类必须继承 APIReply 或 APIEvent，并在注释中用 @RestResponse 进行标注。
  • API 消息上必须添加注解 @RestRequest，并满足如下规范：
    • path:
      • 针对资源使用复数形式。
      • 当 path 中引用消息类变量时，使用 {variableName} 格式。
    • HTTP 方法对应：
      • 查询操作 → HttpMethod.GET
      • 更新操作 → HttpMethod.PUT
      • 创建操作 → HttpMethod.POST
      • 删除操作 → HttpMethod.DELETE
  • API 类需要实现 __example__ 方法以便生成 API 文档，并确保生成对应的 Groovy API Template 与 API Markdown 文件。

---

2. 命名与格式规范

• 类名：

  • 使用 UpperCamelCase 风格。
  • 特殊情况：
    • VO/AO/EO 类型类除外。
    • 抽象类采用 Abstract 或 Base 前缀/后缀。
    • 异常类应以 Exception 结尾。
    • 测试类需要以 Test 或 Case 结尾。

• 方法名、参数名、成员变量和局部变量：

  • 使用 lowerCamelCase 风格。

• 常量命名：

  • 全部大写，使用下划线分隔单词。
  • 要求表达清楚，避免使用含糊或不准确的名称。

• 包名：

  • 统一使用小写，使用点分隔符，每个部分应是一个具有自然语义的英文单词（参考 Spring 框架的结构）。

• 命名细节：

  • 避免在父子类或同一代码块中出现相同名字的成员或局部变量，防止混淆。
  • 命名缩写：
    • 不允许使用不必要的缩写，如：AbsSchedulerJob、condi、Fu 等。应使用完整单词提升可读性。

---

3. 编写自解释代码

• 意图表达：

  • 避免使用布尔型参数造成含义不明确。例如：
    • 对于 stopAgent(boolean ignoreError)，建议拆分为不同函数（如 stopAgentIgnoreError()），或使用枚举表达操作类型。
  • 命名应尽量用完整的单词组合表达意图，并在名称中体现数据类型或用途（例如在常量与变量名称中，将类型词放在末尾）。

• 注释：

  • 代码应尽量做到自解释，对少于两行的说明可以直接写在代码中。
  • 对于较长的注释，需要仔细校对并随代码更新，确保内容正确。
  • 接口方法不应有多余的修饰符（例如 public），且必须配有有效的 Javadoc 注释。

---

4. 流程控制和结构优化

• if...else 的使用：

  • 应尽量减少 if...else 结构的使用，建议：
    • 限制嵌套层级最多为两层，且内层不应再出现 else 分支。
    • 尽早返回（Early Return），将条件判断中的处理逻辑提前结束或抽成独立方法。
    • 使用 Java Stream 或 Lambda 表达式代替冗长的循环与条件判断。

• 条件判断：

  • if 条件表达不宜过长或过于复杂，必要时可以将条件抽成 boolean 变量描述。

• 代码块长度：

  • 单个 if 代码块不宜超过一屏显示，以提高可读性和后续维护性。

---

5. 异常处理与日志

• 捕获异常的原则：
  • 对于可以通过预检查避免的 RuntimeException（如 NullPointerException、IndexOutOfBoundsException 等），不建议使用 try-catch 来进行处理。
  • 捕获异常应仅用于处理真正的意外情况，不应将异常逻辑当作正常流程控制。
  • 在必要时，应继续抛出异常，使上层业务处理者可以转换为用户友好的错误提示。
  • 使用 try-with-resources 语法管理资源，确保在 finally 块中正确关闭资源，并避免在 finally 中返回值。
    ...

Files:

• sdk/src/main/java/org/zstack/sdk/PrimaryStorageMigrateVmAction.java

🧠 Learnings (1)

📚 Learning: 2025-10-20T11:27:25.928Z

Learnt from: MatheMatrix
Repo: MatheMatrix/zstack PR: 2763
File: sdk/src/main/java/org/zstack/sdk/UpdateHostKernelInterfaceAction.java:31-31
Timestamp: 2025-10-20T11:27:25.928Z
Learning: UpdateHostKernelInterface API (`sdk/src/main/java/org/zstack/sdk/UpdateHostKernelInterfaceAction.java`) 在 PR #2763 时尚未被实际使用,因此对其参数约束的变更(如 name 字段从必需改为可选)不会造成破坏性影响。

Applied to files:

• sdk/src/main/java/org/zstack/sdk/PrimaryStorageMigrateVmAction.java

🔇 Additional comments (1)

sdk/src/main/java/org/zstack/sdk/PrimaryStorageMigrateVmAction.java (1)

40-41: dataVolumeUuids 字段符合 SDK 设计规范，无需修改。

该字段的设计经核实无问题：

1. 原始类型 List 符合 SDK 设计：SDK 中的所有 List 字段（如 tagUuids、systemTags、userTags、vmNicUuids 等）都统一使用原始类型 java.util.List 而不带泛型参数。这是该 SDK 代码库的一致设计模式，而非缺陷。后端业务代码使用泛型是另一代码库的做法，两者之间的差异是合理的分层设计。

2. 参数交互逻辑无法验证：关于 withDataVolumes 和 dataVolumeUuids 的交互约束无法在现有代码中找到对应的处理实现，可能该功能尚在开发或实现在其他位置。

3. 缺少文档注释是 SDK 通用设计：SDK 中的字段普遍不包含 Javadoc 注释，这与该代码库的整体风格一致。

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}