优化 Java 代码
在保持现有业务行为、公共 API 和异常语义不变的前提下优化代码。先理解调用链和项目惯例，再修改并验证。
执行顺序
- 阅读目标代码、相关调用方、测试和同模块实现，确认输入输出、边界条件及项目已有依赖。完成标准：能够说明现有行为，并确认下列项目工具类在当前代码库中的实际用法。
- 优先评估设计模式是否能消除重复、分支膨胀或职责混杂。仅在模式能明确提高可维护性和可读性时引入，并沿用代码库已有模式；简单逻辑直接重构。完成标准：已作出有依据的“引入或不引入”判断。
- 在原有结构内实施最小范围优化，依次应用工具类复用、空值规范、卫语句、简单 Lambda/Stream、方法数量约束、代码布局、类与方法中文注释和日志规范。完成标准：每项规则均已检查，所有修改均服务于清晰度或维护性。
- 运行与改动范围匹配的编译、静态检查和测试；无法运行时明确说明未验证项。完成标准：验证通过，或准确报告失败原因和影响。
项目工具约定
使用代码库已有依赖和调用风格；不要为这些判断重复手写条件或另造工具方法。
处理可复用逻辑时，优先搜索并使用项目已有工具类及工具方法。确实没有合适方法时，将具有通用价值的逻辑添加为职责最匹配的已有工具类中的公共方法；遵循该工具类现有的命名、静态调用、参数校验和返回语义，并补充或更新相应测试。仅供当前业务使用的逻辑保留在业务代码中。
| 场景 | 必须使用 |
|---|---|
| 字符串为空 | org.apache.commons.lang3.StringUtils.isBlank(...) |
| 字符串非空 | org.apache.commons.lang3.StringUtils.isNotBlank(...) |
| 对象为空 | java.util.Objects.isNull(...) |
| 对象非空 | java.util.Objects.nonNull(...) |
| Map 为空 | org.apache.commons.collections4.MapUtils.isEmpty(...) |
| Map 非空 | org.apache.commons.collections4.MapUtils.isNotEmpty(...) |
| 集合为空 | org.apache.commons.collections4.CollectionUtils.isEmpty(...) |
| 集合非空 | org.apache.commons.collections4.CollectionUtils.isNotEmpty(...) |
| JSON 解析与序列化 | com.alibaba.fastjson.JSON |
先检查目标模块是否已有对应 import 和依赖；复用现有版本，不擅自更换 JSON 库或引入同类依赖。
重构规则
- 优先使用卫语句处理非法输入、空结果和提前结束，保持主流程扁平，减少深层
if/else。 - 对简单的映射、过滤、匹配、分组和聚合使用清晰的 Lambda 与 Stream 链；链条应短且易读。复杂控制流、异常处理或有副作用的逻辑保留普通循环。
- 优先在现有方法内完成局部重构。只有在重复逻辑、独立职责或可测试性收益明确时提取子方法，并将新增子方法数量控制在完成目标所需的最小值；按上述规则补充已有工具类公共方法属于明确的复用场景。
- 保留对外方法签名、返回约定、事务边界、异常类型、执行顺序和可观察副作用，除非用户明确要求改变行为。
代码布局与注释规范
- 按业务含义组织代码，相同含义的代码组成一个代码块，不同代码块之间使用一个空行分隔；同一代码块内部保持紧凑，不添加无意义空行。
- 新建的类、接口、枚举和记录上方使用 JavaDoc 注释
/** ... */，优先用一句中文说明其职责，不使用普通块注释或行注释替代。 - 目标文件中的方法上方使用 JavaDoc 注释
/** ... */，用一句中文说明方法职责；包括private方法及重写方法，不使用普通块注释替代。 - 方法内部按业务含义分组，在每组相同含义代码的上方使用
// ...添加一句中文注释，说明该组代码的业务意图；不逐行注释，不复述代码语法。 - 当
// ...注释用于开启新的语义代码组，且前面已有代码时，优先在注释前保留一个空行；注释位于方法、分支、循环、try或catch代码块开头时，不额外添加空行；不得连续添加多个空行。 - 所有类注释、方法注释和方法内注释优先使用一句话表达，保持简洁准确，结尾不添加句号、分号、逗号、冒号等标点符号。
- 注释必须与代码行为一致；重构后同步更新失效注释，不保留误导性、重复性或无实际信息的注释。
日志规范
- 使用项目中的日志框架类，并沿用代码库中该类的实际调用签名。
- 日志消息固定为
{当前类名简版}-{当前方法名}-{备注}，三个部分以半角连字符连接，中间不含空格。 - 备注使用简洁中文，包含排障所需上下文；敏感信息不得写入日志。
- 示例：
"HiagentDisasterInfoSyncJob-sync-未查询到国内省市数据"。
交付检查
交付前逐项确认：设计模式判断有依据；已优先搜索并复用项目工具类，无合适方法时已判断是否应补充到已有工具类；指定工具类已用于全部对应场景；嵌套可用卫语句化简；Stream 保持简单；新增方法数量最小；代码已按业务含义分组并用空行分隔；新建的类、接口、枚举和记录上方均有 /** ... */ 中文职责注释；方法上方均有 /** ... */ 中文职责注释；方法内部的语义代码组上方均有 // ... 中文意图注释；开启新语义代码组的 // ... 注释前已在适用位置保留一个空行；注释均优先使用一句话且结尾无标点；新增或修改日志全部符合格式；验证结果已报告。
