solid-java

SOLID Java 为 Java 25+（当前 LTS）强制采用模块化架构：每项功能都位于 `modules/[feature]/` 下（控制器、服务、仓库、接口、模型/DTO），共享代码放在 `modules/core/` 中，接口仅位于 `modules/[feature]/interfaces/` 中，控制器保持精简并委托给服务，文件行数不超过 `FUSE_SOLID_MAX_LINES`，DTO 使用 record，受限层级使用 sealed 类型，且每个公共方法都必须带有 Javadoc。

编写任何新代码之前，都必须先对 modules/core/services 和 modules/core/interfaces 进行 DRY 检查。概述请参阅 solid-principles.md，SRP/OCP/LSP/ISP/DIP 的详细说明请参阅各原则参考文档，模块/服务/接口/仓库/错误/测试的脚手架请参阅模板。

SOLID Java - 模块化架构

Agent 工作流（必须）

在进行任何实现之前，必须并行启动 3 个 Agent，每个 Agent 调用一次并指定 name：

1. fuse-ai-pilot:explore-codebase - 分析现有架构
2. fuse-ai-pilot:research-expert - 通过 Context7 核实 Java 文档
3. fuse-ai-pilot:sniper - 实现后的验证

---

DRY - 创建前先复用（必须）

编写任何新代码之前：

1. Grep 代码库，查找类似的接口、服务或逻辑
2. 检查共享位置：modules/core/services/、modules/core/interfaces/
3. 如果存在类似代码 -> 扩展/复用，而不是重复创建
4. 如果代码将供 2 个或更多功能使用 -> 在 modules/core/ 中创建

---

架构（模块为强制要求）

层	位置
控制器	modules/[feature]/controllers/
服务	modules/[feature]/services/
仓库	modules/[feature]/repositories/
接口	modules/[feature]/interfaces/
模型/DTO	modules/[feature]/models/
共享	modules/core/{services,interfaces,models}/

绝不可使用扁平的 src/ 结构 - 始终使用 modules/[feature]/

---

关键规则（必须）

规则	值
文件行数限制	FUSE_SOLID_MAX_LINES
控制器	保持精简，委托给服务
接口	仅限 modules/[feature]/interfaces/
Javadoc	为每个公共方法编写文档
Records	用于 DTO（Java 16+）
Sealed	用于受限层级（Java 17+）

---

参考指南

概念

主题	参考文档	何时查阅
SOLID 概述	solid-principles.md	快速参考
SRP	single-responsibility.md	臃肿的类
OCP	open-closed.md	添加提供方
LSP	liskov-substitution.md	契约
ISP	interface-segregation.md	臃肿的接口
DIP	dependency-inversion.md	注入
架构	architecture-patterns.md	模块化模式

模板

模板	使用场景
module.md	功能模块结构
service.md	业务逻辑服务
interface.md	契约定义
repository.md	数据访问层
error.md	自定义异常
test.md	使用 mock 的单元测试

---

禁止事项

反模式	修正方法
文件超过 FUSE_SOLID_MAX_LINES	按职责拆分
在实现文件中定义接口	移至 interfaces/ 目录
在服务中使用 new ConcreteClass()	使用依赖注入
扁平的 src/ 结构	使用 modules/[feature]/
上帝类	按职责拆分