Skip to content

<doc>[docs]: <description #4116

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ZStack-Robot wants to merge 1 commit into
base: zsv_5.1.0
Choose a base branch
from
Open

<doc>[docs]: <description #4116

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 4 additions & 0 deletions sdk/src/main/java/org/zstack/sdk/PrimaryStorageMigrateVmAction.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ public Result throwExceptionIfError() {
@Param(required = true, nonempty = false, nullElements = false, emptyString = true, noTrim = false)
public java.lang.String vmInstanceUuid;

@Deprecated
@Param(required = true, nonempty = false, nullElements = false, emptyString = true, noTrim = false)
public java.lang.String dstPrimaryStorageUuid;
Comment on lines +31 to 33
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

@Deprecated 字段缺少 Javadoc 注释

根据编码规范第 3 条，接口和公开方法必须配有有效的 Javadoc 注释。当标记字段为 @Deprecated 时，应添加 Javadoc 注释说明：

  1. 废弃的原因
  2. 建议使用的替代方案（根据 PR 描述，应该是新增的 volumeMigrationSpecs 字段）
  3. 预计移除的版本（如适用）
📝 建议添加 Javadoc 注释 
+    /**
+     * `@deprecated` 使用 {`@link` `#volumeMigrationSpecs`} 替代，以支持卷级别的迁移目标指定
+     */
     `@Deprecated`
     `@Param`(required = true, nonempty = false, nullElements = false, emptyString = true, noTrim = false)
     public java.lang.String dstPrimaryStorageUuid;

As per coding guidelines: 代码应尽量做到自解释，对于较长的注释，需要仔细校对并随代码更新，确保内容正确。接口方法必须配有有效的 Javadoc 注释。

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@sdk/src/main/java/org/zstack/sdk/PrimaryStorageMigrateVmAction.java` around
lines 31 - 33, Add a Javadoc block to the deprecated field dstPrimaryStorageUuid
describing why it was deprecated, the recommended replacement
(volumeMigrationSpecs), and the planned removal version (if known); update the
comment above the field dstPrimaryStorageUuid to state the deprecation reason,
point callers to use volumeMigrationSpecs instead, and include an estimated
removal version or "TBD" if unknown.


Expand All @@ -49,6 +50,9 @@ public Result throwExceptionIfError() {
@Param(required = false, nonempty = false, nullElements = false, emptyString = true, noTrim = false)
public long bandwidth = 0L;

@Param(required = false, nonempty = false, nullElements = false, emptyString = true, noTrim = false)
public java.util.List volumeMigrationSpecs;
Comment on lines +53 to +54
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot May 28, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

使用原始 List 类型降低了类型安全性

字段 volumeMigrationSpecs 声明为原始类型 java.util.List，没有指定泛型参数。这会导致：

  1. 编译器无法进行类型检查，可能在运行时抛出 ClassCastException
  2. 代码可读性降低，开发者无法从签名了解列表元素的具体类型
  3. 产生编译器警告（unchecked warnings）

根据 PR 描述，该字段用于 "指定卷级迁移目标"，应该有明确的元素类型定义。请指定具体的泛型参数（例如 java.util.List<VolumeMigrationSpec> 或其他适当的类型）。

♻️ 建议指定泛型类型 
     `@Param`(required = false, nonempty = false, nullElements = false, emptyString = true, noTrim = false)
-    public java.util.List volumeMigrationSpecs;
+    public java.util.List<VolumeMigrationSpec> volumeMigrationSpecs;

注：请根据实际的卷迁移规范类名调整泛型参数。

As per coding guidelines: 命名应尽量用完整的单词组合表达意图，并在名称中体现数据类型或用途。

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@sdk/src/main/java/org/zstack/sdk/PrimaryStorageMigrateVmAction.java` around
lines 53 - 54, The field volumeMigrationSpecs in class
PrimaryStorageMigrateVmAction is declared as a raw java.util.List; change it to
a parameterized type (e.g. java.util.List<VolumeMigrationSpec> or the actual
spec class used for "卷级迁移目标") to restore type safety and remove unchecked
warnings, update the import or fully-qualify the generic type as needed, and
ensure any usages (constructors, getters/setters, serializers) referencing
volumeMigrationSpecs are updated to the new generic type to match the change.


@Param(required = false)
public java.util.List systemTags;

Expand Down