代码能跑,但读起来费劲时使用。简化 Java / Spring Boot 代码,理清分支、命名与重复,保留原有行为;先弄清为什么这样写,再决定怎么改。
Java 代码简化
灵感来自 Addy Osmani。
概述
减少复杂度,同时精确保留行为。目标不是更少的行数,而是更容易阅读、理解、修改和调试的代码。
每次简化都应回答:新加入项目的同事,能否比以前更快理解这段代码?
何时使用
- 功能已经正常工作,测试通过,但实现比实际需要更复杂。
- 代码审查指出可读性或复杂度问题。
- 出现深层嵌套、冗长方法或含义不清的命名。
- 清理时间压力下完成的代码。
- 整理分散在多处、属于同一职责的逻辑。
- 合并改动后出现重复或风格不一致。
以下情况不适用:
- 代码已经清晰,不要为了简化而改动。
- 尚未理解代码行为,先补充上下文。
- 更简单的实现会造成已知且不可接受的性能退化。
- 模块即将整体重写,没有必要清理即将删除的代码。
五项原则
1. 精确保留行为
只改变表达方式,不改变代码做什么。
保持输入、输出、副作用、错误行为和边界情况。 调用方依赖的顺序、可变性、序列化与框架行为也属于契约。
每次改动前检查:
- 相同输入是否得到相同结果?
- 是否保持相同的错误行为?
- 是否保持副作用及必要的执行顺序?
- 现有行为测试是否仍然通过?
不能确认等价时,不做该项简化。 发现缺陷可以指出,但不要把行为修复混入重构。
2. 遵循项目约定
简化应让代码更符合项目,而不是引入外部偏好。
改动前:
- 阅读适用的 AGENTS.md、CLAUDE.md 和项目约定。
- 研究相邻代码如何处理类似问题。
- 确认实际 Java release 和 Spring Boot 版本。
- 遵循项目的包结构、命名、异常处理、空值约定、 Bean 装配及检查工具。
不为统一个人风格制造差异,也不借简化升级依赖或启用预览特性。
3. 清晰胜于巧妙
紧凑代码需要停下来推演时,优先采用更明确的表达。
清晰不等于展开更多语句。对已有的互斥状态, 穷尽 switch 可以比嵌套三元表达式更清楚。
沿用已有类型,保持 null、分支优先级、兜底和异常行为。 数据模型变化应单独评估。
4. 保持平衡
简化也可能走得过头:
- 过度内联: 删除表达业务概念的辅助方法,反而让调用处难读。
- 合并无关逻辑: 两个简单方法合成一个复杂方法,不是简化。
- 删除有用抽象: 某些边界承担替换、测试或框架职责。
- 追求更少行数: 压缩表达可能增加理解负担。
提取或删除结构时,先确认职责。 外观重复不一定代表同一业务规则。
保留真实的 seam:能够替换依赖而不必重写使用方的位置。 已有注入点可能已经足够,不为分层增加 Java interface。
保留深度模块:通过简单契约封装复杂实现。 删除模块后,若内部细节散到多个调用方,封装仍有价值。
这些判断只辅助当前简化,不扩展为架构重设计。
5. 限定改动范围
优先处理用户指定的代码;未指定时,默认处理近期改动。
不要顺手重构无关代码。 无边界的清理会增加审阅噪声和回归风险。
简化流程
第一步:理解后再动手
删除结构之前,先理解它为什么存在。
回答:
- 代码承担什么职责?
- 谁调用它?它调用谁?
- 边界情况和错误路径是什么?
- 哪些测试定义了预期行为?
- 是否存在性能、框架或历史兼容原因?
- 必要时,git blame 和提交记录能否解释原因?
无法回答时,先读取更多相关上下文。
只有代码片段时,说明能确认的范围, 不要虚构项目约定、调用方或验证结果。
第二步:识别简化机会
以下是检查线索,不是必须修改的阈值。
结构复杂度
| 模式 | 信号 | 可考虑的简化 |
|---|---|---|
| 深层嵌套 | 控制流难以追踪 | 卫语句或具名辅助方法 |
| 长方法 | 包含多个独立意图 | 按职责拆分,不按行数切碎 |
| 嵌套三元表达式 | 分支优先级难以辨认 | if/else 或适合的 switch |
| 布尔参数串 | 调用意图不明确 | 考虑具名方法或已有枚举,先检查调用契约 |
| 重复条件 | 同一判断散落多处 | 提取属于同一职责的具名谓词 |
命名与可读性
| 模式 | 信号 | 可考虑的简化 |
|---|---|---|
| 泛化命名 | 名字无法解释内容 | 使用具体领域名称 |
| 不必要的缩写 | 阅读时需要解码 | 使用完整单词,保留通用缩写 |
| 误导命名 | 名称隐藏副作用 | 让名字反映实际行为 |
| 解释“做什么”的注释 | 重复已经清楚的代码 | 删除冗余注释 |
| 解释“为什么”的注释 | 记录约束与取舍 | 保留 |
冗余
| 模式 | 信号 | 可考虑的简化 |
|---|---|---|
| 重复逻辑 | 同一规则有多个实现 | 确认职责相同后提取 |
| 死代码 | 不可达分支、未用变量、旧注释代码 | 确认确实无用后删除 |
| 无价值包装 | 仅转发,没有契约或运行时职责 | 内联或直接调用 |
| 过度设计 | 多层工厂、没有实际用途的策略结构 | 替换为满足当前需求的直接表达 |
| 冗余类型转换 | 转换看似可以省略 | 确认重载选择和运行时检查不变后删除 |
第三步:逐步修改
一次完成一个可独立理解和验证的简化。
- 运行相关测试,建立基线。
- 做最小改动。
- 运行对应测试和检查。
- 通过后继续;失败时撤回本次改动或重新判断原因。
证据不足时,先补充刻画现有行为的测试, 确认原实现和修改后实现满足同一行为预期。
测试装配可以随内部结构调整; 不能修改预期、降低断言或跳过失败用例来让重构通过。
将简化与功能新增、缺陷修复分开。 大量机械修改可使用 IDE 重构或 AST 工具, 但仍需审查差异和验证结果。
第四步:验证整体结果
比较修改前后:
- 是否更容易理解?
- 是否引入了不符合项目习惯的模式?
- 是否把复杂度转给了调用方?
- 差异是否集中、清晰、可审阅?
如果结果更难理解或维护,撤回简化。 不是每次尝试都值得保留。
语言与框架指导
Java 21
使用项目实际版本支持的稳定特性,不追求语法更新。
- 模式匹配与 switch: 可以减少重复判断和转换, 但要保持 null、分支优先级、守卫、兜底和异常行为。
- Record Patterns: 可以减少解构样板, 但要检查嵌套 null、访问器调用及异常行为。
- record: 不是普通类的机械替代品。 转换前检查公开访问、相等性、可变性、构造与框架契约。
- 集合: 保留顺序、空集合行为、可变性和别名关系。 reversed() 视图不等于独立副本。
- Stream 与 Optional: 不机械替换循环或条件。 保留求值时机、短路、副作用和返回集合语义; orElse 与 orElseGet 不自动等价。
虚拟线程、并行化和异步化可能改变容量、时序与一致性, 不作为默认简化手段。
Spring Boot 3 / 4
先确认项目的具体版本与依赖,再判断哪些写法适用。 不要把一个版本的默认配置、包名或装配方式直接套到另一个版本;升级另行处理。 方法体一样,框架执行的行为也未必一样。
- 代理: 移动或内联方法前,检查事务、回滚、鉴权、 校验、缓存和异步拦截。代理调用与类内自调用不同。
- 装配: 删除 Bean、依赖或配置前,检查条件装配、 自动配置和运行时用途。没有显式引用不代表没有用途。
- 外部契约: 保留 HTTP 状态、异常映射、序列化、 客户端配置和持久化行为。确认实际使用的 mapper 与客户端。
- 校验: 非空注解不能单独证明运行时检查冗余。 不用默认值掩盖非法输入,也不套用“全面禁止 null”。
触及这些边界时,使用覆盖实际装配行为的测试; 只测试方法体可能漏掉回归。
高风险改动
涉及资金、敏感数据、共享状态或跨系统操作时,成功一次还不够。 只看本次改动可能影响的保证:
- 含义变了吗? 保留业务规则,以及金额、时间、数据和状态的含义。
- 边界还在吗? 保留身份、权限和数据隔离;不能让细节或敏感信息越过原有边界。
- 失败后会怎样? 并发、重试、中断和结果未知时,原有一致性、幂等与恢复保证仍须成立。
- 压力下撑得住吗? 保留容量、资源生命周期和降级约束,不把局部简化变成系统性风险。
- 上线后能共存、能追查吗? 考虑旧数据、外部消费者和新旧版本,保留审计与监控;代码回退不能撤销已经发生的业务效果。
说清原来靠什么保证、改动可能破坏什么,再选择能检验它的场景。 保证若依赖配置或外部系统,就沿调用链查清;没有把握,保留原实现。
常见借口
| 借口 | 判断 |
|---|---|
| 能运行就不用改 | 难读代码值得改善,清晰代码不必动 |
| 行数越少越简单 | 简单取决于理解成本 |
| 顺手清理旁边的代码 | 无关改动增加噪声与风险 |
| 类型已经说明一切 | 类型不能完整表达意图和副作用 |
| 这个抽象以后可能有用 | 用当前用途证明价值,不为假想需求保留复杂度 |
| 原作者一定有理由 | 先查原因,再判断原因是否仍然成立 |
| 加功能时一起重构更省事 | 分开变更,更容易验证和回退 |
危险信号
- 改动需要改变行为预期才能通过测试。
- 代码更短,但需要更多跳转或框架知识。
- 为整洁删除错误处理、安全控制或必要校验。
- 未理解用途就删除抽象、配置或依赖。
- 将功能、迁移或执行模型变化包装成简化。
- 多项改动合在一起,没有独立验证。
- 未经要求扩大修改范围。
验证
完成后确认:
- 行为预期保持一致,相关测试实际执行并通过。
- 构建和项目已有检查通过,无新增问题。
- 差异可审阅,没有无关改动。
- 错误处理及受影响的框架、数据和外部契约保持完整。
- 可理解性有具体改善,没有转移复杂度或增加无价值抽象。
- 未执行的检查和无法确认的行为已明确报告。
涉及安全边界时,按主题查阅相关章节, 确认简化没有削弱适用控制:
说明适用条款与代码事实,不以链接代替核对。 来源无法访问时,说明未核对;不扩展为全面安全审计。
涉及性能敏感路径时,检查复杂度、查询或远程调用次数、 分配及资源使用。必要时在代表性负载下比较, 以项目目标判断是否可接受。 普通局部修改不强制基准测试,也不凭代码更短声称更快。
最终简要报告改动、简化理由、验证结果和限制。 没有值得保留的改动,也可以是正确结果。
Related skills
- Downloads
- Security audit
- Pass
- Last updated
- 4d ago
- Current version
- v0.2.1
- License
- MIT-0
