<fix>[core]: remove Platform.err methods with cause arg

[zstack-robot-2]

This patch is for zsv_4.10.28

Related: ZSV-10663

Change-Id: I6677687973686e6d727a6e677169726e6c727064

sync from gitlab !8947

[coderabbitai]

Walkthrough

删除 Platform 中若干接受 cause 的已弃用 err/operr/touterr 重载，重构 multiErr 系列以使用 .withCause(...) 链式调用；调整 toI18nString 的泛型签名；NFS 挂载超时路径改用 touterr(...).withCause(...) 保留原始错误为 cause。

Changes

Cohort / File(s)	变更摘要
核心错误 API core/src/main/java/org/zstack/core/Platform.java	移除接受 ErrorCode cause 的公开/已弃用重载（如 err(..., ErrorCode cause, ...)、operr(ErrorCode, ...)、touterr(ErrorCode, ...)）；更新 multiErr(...) 重载以改为 err(...).withCause(...)；调整 toI18nString(String, Locale, List<Object>) 的参数类型并改为通过 args.toArray(new Object[0]) 委托；若干内部泛型/集合初始化改进。
NFS 存储后端错误保留 plugin/nfsPrimaryStorage/src/main/java/org/zstack/storage/primary/nfs/NfsPrimaryStorageKVMBackend.java	在挂载超时（SocketTimeoutException）处理处，将原先把 errorCode 作为参数传入的调用改为通过 touterr(...).withCause(errorCode) 链式调用，确保原始错误被设置为 cause。

Sequence Diagram(s)

（本次变更为 API 清理与错误封装调整，控制流未引入跨多个组件的新交互，故省略序列图。）

Estimated code review effort

🎯 3 (中等) | ⏱️ ~20 分钟

Poem

兔儿窜过代码园，留下一串小脚印，
链式因果捆旧怨，错误堆栈更分明。
删除枯枝长新芽，编译花开笑盈盈，
小兔鞠躬庆一声：代码清爽真是好！ 🐰✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	PR标题清晰准确地概括了主要变更：移除Platform.err方法中的cause参数重载，与代码变更内容完全相符。
Description check	✅ Passed	PR描述虽然简洁，但与代码变更相关，提及了补丁版本、相关问题追踪和同步来源，与实际变更内容相符。

✨ 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/wenhao.zhang/c-1

---

📜 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 df55357 and 442c45c.

📒 Files selected for processing (2)

• core/src/main/java/org/zstack/core/Platform.java
• plugin/nfsPrimaryStorage/src/main/java/org/zstack/storage/primary/nfs/NfsPrimaryStorageKVMBackend.java

🚧 Files skipped from review as they are similar to previous changes (1)

• plugin/nfsPrimaryStorage/src/main/java/org/zstack/storage/primary/nfs/NfsPrimaryStorageKVMBackend.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:

• core/src/main/java/org/zstack/core/Platform.java

🧠 Learnings (2)

📓 Common learnings

Learnt from: ZStack-Robot
Repo: MatheMatrix/zstack PR: 2287
File: header/src/main/java/org/zstack/header/errorcode/ErrorCode.java:25-30
Timestamp: 2025-07-10T07:29:52.955Z
Learning: 在 ZStack 项目中，ErrorCodeList 正在进行渐进式弃用，而不是一次性完全移除。在过渡期间，ErrorCodeList 仍需要能够访问 ErrorCode 中的 causes 字段，因此 causes 字段使用 protected final 可见性是合理的设计选择，支持渐进式重构策略。

Learnt from: zstack-robot-1
Repo: MatheMatrix/zstack PR: 2360
File: network/src/main/java/org/zstack/network/l3/L3BasicNetwork.java:449-490
Timestamp: 2025-08-04T04:48:19.103Z
Learning: ZStack项目在cherry-pick操作中，即使发现了性能优化机会（如IP地址批量保存的内存优化），也严格遵循不做额外修改的政策，优先保证cherry-pick的完整性和一致性。

📚 Learning: 2025-07-10T07:29:52.955Z

Learnt from: ZStack-Robot
Repo: MatheMatrix/zstack PR: 2287
File: header/src/main/java/org/zstack/header/errorcode/ErrorCode.java:25-30
Timestamp: 2025-07-10T07:29:52.955Z
Learning: 在 ZStack 项目中，ErrorCodeList 正在进行渐进式弃用，而不是一次性完全移除。在过渡期间，ErrorCodeList 仍需要能够访问 ErrorCode 中的 causes 字段，因此 causes 字段使用 protected final 可见性是合理的设计选择，支持渐进式重构策略。

Applied to files:

• core/src/main/java/org/zstack/core/Platform.java

🔇 Additional comments (6)

core/src/main/java/org/zstack/core/Platform.java (6)

106-106: 泛型类型优化符合最佳实践。

这些更改使用了菱形操作符和通配符泛型（如 Class<?>），提高了类型安全性并减少了冗余代码，符合现代Java编码规范。

Also applies to: 120-120, 216-216, 221-221, 267-267

---

627-627: 泛型声明改进正确。

将 Enumeration 更新为 Enumeration<?>，以及使用菱形操作符初始化 HashMap，避免了原始类型使用，提升了类型安全性。

Also applies to: 629-629

---

841-842: 方法签名泛型化改进正确。

将参数从原始类型 List 更新为 List<Object>，并使用 toArray(new Object[0]) 进行转换，提高了类型安全性。实现正确且符合Java泛型最佳实践。

---

976-977: multiErr 方法重构为链式调用模式，API 设计更清晰。

将原来传递 cause 参数的方式改为使用 .withCause(causes) 链式调用，这是一个更优雅的 API 设计。重构符合 PR 目标，代码可读性更好，且保持了功能的一致性。

Also applies to: 981-982

---

986-987: ErrorCodeList 的 multiErr 重构正确，支持渐进式弃用策略。

将 ErrorCodeList 的 multiErr 方法重构为链式调用模式，与 Collection<ErrorCode> 版本保持一致。虽然 ErrorCodeList 正在渐进式弃用，但在过渡期内保留对其的支持是合理的设计选择。

基于 learnings，这种实现支持渐进式重构策略。

Also applies to: 991-992

---

307-307: 注解使用正确，无需修改。

@SuppressWarnings("unchecked") 注解是必要的。formatByMap(Map tokens) 方法的参数使用了原始 Map 类型（无泛型），而 map() 方法返回的是具有完整类型参数的 Map<K,V>。当向 formatByMap() 传递类型化的 Map 时，会触发编译器的未检查类型转换警告，因此该注解的使用是合理的。

Likely an incorrect or invalid review comment.

---

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

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between b94639f and df55357.

📒 Files selected for processing (2)

• core/src/main/java/org/zstack/core/Platform.java
• plugin/nfsPrimaryStorage/src/main/java/org/zstack/storage/primary/nfs/NfsPrimaryStorageKVMBackend.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:

• plugin/nfsPrimaryStorage/src/main/java/org/zstack/storage/primary/nfs/NfsPrimaryStorageKVMBackend.java
• core/src/main/java/org/zstack/core/Platform.java

🧠 Learnings (2)

📓 Common learnings

Learnt from: zstack-robot-1
Repo: MatheMatrix/zstack PR: 2360
File: network/src/main/java/org/zstack/network/l3/L3BasicNetwork.java:449-490
Timestamp: 2025-08-04T04:48:19.103Z
Learning: ZStack项目在cherry-pick操作中，即使发现了性能优化机会（如IP地址批量保存的内存优化），也严格遵循不做额外修改的政策，优先保证cherry-pick的完整性和一致性。

📚 Learning: 2025-07-10T07:29:52.955Z

Learnt from: ZStack-Robot
Repo: MatheMatrix/zstack PR: 2287
File: header/src/main/java/org/zstack/header/errorcode/ErrorCode.java:25-30
Timestamp: 2025-07-10T07:29:52.955Z
Learning: 在 ZStack 项目中，ErrorCodeList 正在进行渐进式弃用，而不是一次性完全移除。在过渡期间，ErrorCodeList 仍需要能够访问 ErrorCode 中的 causes 字段，因此 causes 字段使用 protected final 可见性是合理的设计选择，支持渐进式重构策略。

Applied to files:

• core/src/main/java/org/zstack/core/Platform.java

🔇 Additional comments (2)

core/src/main/java/org/zstack/core/Platform.java (1)

988-1006: LGTM! 错误处理迁移正确

这些 multiErr 方法的重构正确地将错误原因从方法参数迁移到 .withCause() 链式调用，与项目中 ErrorCode 处理的渐进式重构策略一致。所有四个重载方法的实现都遵循了统一的模式，保持了原有的功能语义。

根据学习记录，这是 ErrorCodeList 渐进式弃用过程的一部分，这些变更支持该重构策略。

plugin/nfsPrimaryStorage/src/main/java/org/zstack/storage/primary/nfs/NfsPrimaryStorageKVMBackend.java (1)

160-161: LGTM! 错误包装模式迁移正确

超时错误处理正确地从旧模式 touterr(errorCode, ...) 迁移到新模式 touterr(...).withCause(errorCode)，与 Platform.java 中移除带 cause 参数的方法变更保持一致。原始错误信息通过 .withCause() 正确地保留为错误原因链。