solid-rust

SOLID Rust 为 Rust 2024 版强制执行模块化架构：每项功能都位于 `src/modules/[feature]/` 下（handlers.rs、services.rs、repository.rs、traits.rs、models.rs），共享代码放在 `src/core/` 中；trait 只能放在 `traits.rs` 或 `src/core/traits/` 中；泛型使用 trait bound，而不是具体类型；自定义错误由 `thiserror` 处理；每个公开项都必须带有 rustdoc `///` 注释。

编写任何新代码之前，必须先对照 src/core/services 和 src/core/traits 检查是否符合 DRY 原则。概览请参阅 solid-principles.md；SRP/OCP/LSP/ISP/DIP 的详细信息请参阅各原则的参考文档；模块、服务、trait、处理器、错误和测试脚手架请参阅模板。

SOLID Rust - 模块化架构

Agent 工作流（必须遵循）

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

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

---

DRY - 先复用，再创建（必须遵循）

编写任何新代码之前：

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

---

架构（必须采用模块化结构）

层	位置	最大行数
处理器	src/modules/[feature]/handlers.rs	50
服务	src/modules/[feature]/services.rs	100
仓库	src/modules/[feature]/repository.rs	100
Trait	src/modules/[feature]/traits.rs	30
模型	src/modules/[feature]/models.rs	50
共享代码	src/core/{services,traits,models}/	-

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

---

关键规则（必须遵循）

规则	要求
文件行数限制	100 行（达到 90 行时拆分）
处理器	少于 50 行，将工作委托给服务
Trait	只能放在 traits.rs 或 src/core/traits/ 中
Rustdoc	每个公开项都必须有 /// 注释
错误处理	使用 thiserror 处理自定义错误
泛型	使用 trait bound，而不是具体类型

---

参考指南

概念

主题	参考文档	查阅时机
SOLID 概览	solid-principles.md	快速参考
SRP	single-responsibility.md	结构体臃肿时
OCP	open-closed.md	添加实现时
LSP	liskov-substitution.md	trait 契约
ISP	interface-segregation.md	trait 臃肿时
DIP	dependency-inversion.md	泛型/依赖注入
架构	architecture-patterns.md	模块化 crate

模板

模板	使用时机
module.md	功能模块结构
service.md	业务逻辑服务
trait-def.md	Trait 定义
handler.md	HTTP 处理器（Axum）
error.md	自定义错误（thiserror）
test.md	单元测试和集成测试

---

禁止事项

反模式	修正方法
文件超过 100 行	达到 90 行时拆分
在 impl 文件中定义 trait	移至 traits.rs
Box<dyn Any>	使用适当的 trait bound
扁平的 src/ 结构	使用 src/modules/[feature]/
在库代码中使用 Unwrap	使用 Result<T, E>