solid-java

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SOLID Java - Modular Architecture

SOLID Java - 模块化架构

Agent Workflow (MANDATORY)

Agent工作流（强制要求）

Before ANY implementation, use

TeamCreate

to spawn 3 agents:

fuse-ai-pilot:explore-codebase - Analyze existing architecture
fuse-ai-pilot:research-expert - Verify Java docs via Context7
fuse-ai-pilot:sniper - Post-implementation validation

在进行任何实现之前，使用

TeamCreate

生成3个Agent：

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

DRY - Reuse Before Creating (MANDATORY)

DRY - 优先复用再创建（强制要求）

Before writing ANY new code:

Grep the codebase for similar interfaces, services, or logic

Check shared locations:

modules/core/services/

modules/core/interfaces/

If similar code exists -> extend/reuse instead of duplicate
If code will be used by 2+ features -> create it in
```
modules/core/
```

在编写任何新代码之前：

在代码库中Grep搜索类似的接口、服务或逻辑

检查共享位置：

modules/core/services/

、

modules/core/interfaces/

如果存在类似代码 -> 扩展/复用而非重复编写
如果代码将被2个及以上功能使用 -> 在
```
modules/core/
```
中创建

Architecture (Modules MANDATORY)

架构（模块为强制要求）

Layer	Location	Max Lines
Controllers	`modules/[feature]/controllers/`	50
Services	`modules/[feature]/services/`	100
Repositories	`modules/[feature]/repositories/`	100
Interfaces	`modules/[feature]/interfaces/`	30
Models/DTOs	`modules/[feature]/models/`	50
Shared	`modules/core/{services,interfaces,models}/`	-

NEVER use flat
src/
structure - always
modules/[feature]/

层级	位置	最大行数
控制器	`modules/[feature]/controllers/`	50
服务	`modules/[feature]/services/`	100
仓库	`modules/[feature]/repositories/`	100
接口	`modules/[feature]/interfaces/`	30
模型/DTO	`modules/[feature]/models/`	50
共享代码	`modules/core/{services,interfaces,models}/`	-

绝对不要使用扁平的
src/
结构 - 务必使用
modules/[feature]/

Critical Rules (MANDATORY)

关键规则（强制要求）

Rule	Value
File limit	100 lines (split at 90)
Controllers	< 50 lines, delegate to services
Interfaces	`modules/[feature]/interfaces/` ONLY
Javadoc	Every public method documented
Records	Use for DTOs (Java 16+)
Sealed	Use for restricted hierarchies (Java 17+)

规则	要求
文件行数限制	100行（90行时拆分）
控制器	<50行，委托给服务处理
接口	仅允许放在 `modules/[feature]/interfaces/`
Javadoc	每个公共方法都必须编写文档
Records	用于DTO（Java 16+）
Sealed	用于受限层级结构（Java 17+）

Reference Guide

参考指南

Concepts

概念

Topic	Reference	When to consult
SOLID Overview	solid-principles.md	Quick reference
SRP	single-responsibility.md	Fat classes
OCP	open-closed.md	Adding providers
LSP	liskov-substitution.md	Contracts
ISP	interface-segregation.md	Fat interfaces
DIP	dependency-inversion.md	Injection
Architecture	architecture-patterns.md	Modular patterns

主题	参考文档	查阅时机
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	处理模块化模式时

Templates

模板

Template	When to use
module.md	Feature module structure
service.md	Business logic service
interface.md	Contract definition
repository.md	Data access layer
error.md	Custom exceptions
test.md	Unit tests with mocks

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

Forbidden

禁止事项

Anti-Pattern	Fix
Files > 100 lines	Split at 90
Interfaces in impl files	Move to `interfaces/` directory
`new ConcreteClass()` in services	Use dependency injection
Flat `src/` structure	Use `modules/[feature]/`
God classes	Split by responsibility

反模式	修复方案
文件行数>100行	在90行时拆分
接口放在实现文件中	移至 `interfaces/` 目录
服务中使用 `new ConcreteClass()`	使用依赖注入
扁平的 `src/` 结构	使用 `modules/[feature]/`
上帝类	按职责拆分