solid-go

SOLID Go 为 Go 1.27+ 强制实施模块化架构：每项功能都位于 `internal/modules/[feature]/` 下（handlers、services、repositories、ports、models），共享代码放在 `internal/core/` 中；接口（ports）只能放在 `ports/` 目录中，且应保持精简（1-3 个方法，符合 Go 惯例）；函数接收接口，但返回结构体；每个导出的函数都必须带有 godoc 注释。

编写任何新代码之前，都必须对照 internal/core/services 和 internal/core/ports 执行 DRY 检查。概览请参阅 solid-principles.md；SRP/OCP/LSP/ISP/DIP 的详细说明请参阅各原则对应的参考文档；六边形/模块化布局请参阅 architecture-patterns.md；模块、服务、接口、处理器、错误和测试脚手架请参阅模板。

SOLID Go - 模块化架构

Agent 工作流（强制）

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

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

---

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

编写任何新代码之前：

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

---

架构（强制采用模块化结构）

层	位置
处理器	internal/modules/[feature]/handlers/
服务	internal/modules/[feature]/services/
仓储	internal/modules/[feature]/repositories/
Ports（接口）	internal/modules/[feature]/ports/
模型	internal/modules/[feature]/models/
共享代码	internal/core/{services,ports,models}/

禁止使用扁平的 internal/ 结构 - 始终使用 internal/modules/[feature]/

---

关键规则（强制）

规则	值
文件行数限制	FUSE_SOLID_MAX_LINES
处理器	保持精简，将工作委托给服务
接口	只能放在 ports/ 目录中
Godoc	为每个导出的函数添加文档
接收接口	返回结构体
小型接口	最多 1-3 个方法（Go 惯例）

---

参考指南

概念

主题	参考文档	何时查阅
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	Port 定义
handler.md	HTTP 处理器
error.md	自定义错误
test.md	表驱动测试

---

禁止事项

反模式	修正方法
文件超过 FUSE_SOLID_MAX_LINES	按职责拆分
在实现文件中定义接口	移至 ports/ 目录
臃肿的接口（4 个或更多方法）	拆分为小型接口
扁平的 internal/ 结构	使用 internal/modules/[feature]/
使用 init() 装配依赖	使用构造函数注入