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 约束，而非具体类型；自定义错误由 `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
服务	src/modules/[feature]/services.rs
仓储	src/modules/[feature]/repository.rs
Trait	src/modules/[feature]/traits.rs
模型	src/modules/[feature]/models.rs
共享代码	src/core/{services,traits,models}/

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

---

关键规则（强制）

规则	值
文件行数限制	FUSE_SOLID_MAX_LINES
处理器	保持精简，将工作委托给服务
Trait	仅限 traits.rs 或 src/core/traits/
Rustdoc	每个公开项都必须有 /// 注释
错误处理	使用 thiserror 处理自定义错误
泛型	使用 trait 约束，而非具体类型

---

参考指南

概念

主题	参考文档	查阅时机
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	单元测试 + 集成测试

---

禁止事项

反模式	修正方法
文件超过 FUSE_SOLID_MAX_LINES	按职责拆分
在 impl 文件中定义 Trait	移至 traits.rs
Box<dyn Any>	使用恰当的 trait 约束
扁平的 src/ 结构	使用 src/modules/[feature]/
在库代码中使用 Unwrap	使用 Result<T, E>