simplify-java-cn
Skill14 starsChanged 22 days agoApache-2.0View on GitHub
代码能跑,但读起来费劲时使用。简化 Java / Spring Boot 代码,理清分支、命名与重复,保留原有行为;先弄清为什么这样写,再决定怎么改。
1 other project uses a version of this.
Adopted by
Most recently taken up by
- ontology-of-everything/concept-skillsword for word, first seen Nov 15, 2026
Other versions1 project uses a version of this.
Word for word · 1
- ontology-of-everything/concept-skills★ 14100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository22 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- agent-dx-cliSkill
- architect-4cSkill
- architect-4rSkill
- architect-frontend-feature-firstSkill
- architect-frontend-fsdSkill
- concept-designSkill
- concept-modelSkill
- data-knowledge-architectSkill
- personal-knowledge-architectSkill
- read-it-reframe-it-own-itSkill
- simplify-javaSkill
- agent-dx-cli-cnSkill
- architect-4c-cnSkill
- architect-4r-cnSkill
- architect-frontend-feature-first-cnSkill
- architect-frontend-fsd-cnSkill
- concept-design-cnSkill
- concept-model-cnSkill
- data-knowledge-architect-cnSkill
- personal-knowledge-architect-cnSkill
- read-it-reframe-it-own-it-cnSkill
The file
Files
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”。
触及这些边界时,使用覆盖实际装配行为的测试; 只测试方法体可能漏掉回归。
高风险改动
涉及资金、敏感数据、共享状态或跨系统操作时,成功一次还不够。 只看本次改动可能影响的保证:
- 含义变了吗? 保留业务规则,以及金额、时间、数据和状态的含义。
- 边界还在吗? 保留身份、权限和数据隔离;不能让细节或敏感信息越过原有边界。
- 失败后会怎样? 并发、重试、中断和结果未知时,原有一致性、幂等与恢复保证仍须成立。
- 压力下撑得住吗? 保留容量、资源生命周期和降级约束,不把局部简化变成系统性风险。
- 上线后能共存、能追查吗? 考虑旧数据、外部消费者和新旧版本,保留审计与监控;代码回退不能撤销已经发生的业务效果。
说清原来靠什么保证、改动可能破坏什么,再选择能检验它的场景。 保证若依赖配置或外部系统,就沿调用链查清;没有把握,保留原实现。
常见借口
| 借口 | 判断 |
| 能运行就不用改 | 难读代码值得改善,清晰代码不必动 |
| 行数越少越简单 | 简单取决于理解成本 |
| 顺手清理旁边的代码 | 无关改动增加噪声与风险 |
| 类型已经说明一切 | 类型不能完整表达意图和副作用 |
| 这个抽象以后可能有用 | 用当前用途证明价值,不为假想需求保留复杂度 |
| 原作者一定有理由 | 先查原因,再判断原因是否仍然成立 |
| 加功能时一起重构更省事 | 分开变更,更容易验证和回退 |
危险信号
- 改动需要改变行为预期才能通过测试。
- 代码更短,但需要更多跳转或框架知识。
- 为整洁删除错误处理、安全控制或必要校验。
- 未理解用途就删除抽象、配置或依赖。
- 将功能、迁移或执行模型变化包装成简化。
- 多项改动合在一起,没有独立验证。
- 未经要求扩大修改范围。
验证
完成后确认:
- 行为预期保持一致,相关测试实际执行并通过。
- 构建和项目已有检查通过,无新增问题。
- 差异可审阅,没有无关改动。
- 错误处理及受影响的框架、数据和外部契约保持完整。
- 可理解性有具体改善,没有转移复杂度或增加无价值抽象。
- 未执行的检查和无法确认的行为已明确报告。
涉及安全边界时,按主题查阅相关章节, 确认简化没有削弱适用控制:
说明适用条款与代码事实,不以链接代替核对。 来源无法访问时,说明未核对;不扩展为全面安全审计。
涉及性能敏感路径时,检查复杂度、查询或远程调用次数、 分配及资源使用。必要时在代表性负载下比较, 以项目目标判断是否可接受。 普通局部修改不强制基准测试,也不凭代码更短声称更快。
最终简要报告改动、简化理由、验证结果和限制。 没有值得保留的改动,也可以是正确结果。
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

