SOLID 架构准则

技能文档

---
name: majiayu000-solid-architecture
title: SOLID 架构准则
description: 在编写、审查或重构代码时应用 SOLID 原则、组合优于继承、模块组织与副作用边界准则，保证代码可维护、可测试、确定性。当用户实现新功能、修复 bug、创建新模块、审查代码质量或重构设计时主动应用。触发词：SOLID、架构设计、代码重构、模块划分、代码质量审查。
category: 开发工具
---

# SOLID 架构准则

编写或修改代码时应用以下原则；当设计决策冲突时，将其作为裁决依据。

## 技能工作流

### 步骤 1：明确核心目标（按优先级）

1. **可维护性**——修改时不破坏无关部分
2. **可测试性**——核心逻辑不依赖 I/O 或 UI 即可测试
3. **确定性**——相同输入（含固定种子的随机数）可复现结果
4. **关注点分离**——领域逻辑、基础设施、UI 清晰分层

### 步骤 2：组合优于继承

优先使用小型、聚焦的类型组合，而非深层继承树。想扩展一个类时，先自问：「用组合能否实现？」

### 步骤 3：逐条检查 SOLID 原则

#### 单一职责（SRP）

每个模块/类型/函数**只有一个变化理由**。

**违反信号：**
- 无法用一句话说清用途
- 领域逻辑与基础设施混杂
- 一个文件存在多个不相关的修改原因

**处理：** 拆分为目标单一、职责聚焦的模块。

#### 开闭原则（OCP）

通过新增实现来扩展，而不是反复修改既有代码。

**违反信号：**
- 新增行为需要改动现有代码
- switch/if-else 链不断增长
- 稳定模块被频繁修改

**处理：** 通过新模块与组合添加行为，而不是堆条件分支。

#### 里氏替换（LSP）

子类型必须能在任何使用基类型的地方正常工作。

**违反信号：**
- 子类型对继承来的操作直接抛异常
- 子类型忽略或空实现继承方法
- 深层继承层级

**处理：** 优先用接口而非深层继承，确保可替换性。

#### 接口隔离（ISP）

只依赖所需的最小接口面。

**违反信号：**
- 接口方法过多过大
- 调用方只用到接口的一个子集
- 「胖」接口迫使实现者写空实现

**处理：** 拆出小型、具体的接口。

#### 依赖倒置（DIP）

依赖抽象，不依赖具体实现。

**违反信号：**
- 直接 import 具体实现
- 用全局单例管理随机数、配置、I/O
- 硬编码依赖

**处理：** 注入依赖；用显式传递的上下文/环境对象。

### 步骤 4：检查模块组织

**文件粒度：**

- 非平凡类型（类、结构体、复杂组件）：独占一个文件
- 相关工具函数：按内聚目的归入同一模块
- 避免「大杂烩」utils 文件——按用途分组

**分层：**

建立清晰的依赖方向：

```
core → domain → application → UI
```

**规则：**

- 下层**禁止** import 上层
- 临时违反要显式标记并跟踪清理
- barrel/index 文件仅用于公共 API
- 内部模块直接互相引用；外部消费方走公共 API
- 避免循环依赖

### 步骤 5：检查副作用与边界

**纯与不纯分离：**

- **纯（无副作用）：** 计算、变换、业务逻辑；所有输入经参数传入，不修改外部状态
- **不纯（有副作用）：** I/O（文件、网络、数据库）、随机数生成、时间日期、日志与指标

**依赖注入：**

时钟、随机数（可播种以保证可复现）、I/O 适配器均通过注入传入系统，保证测试确定性。

**边界模块：**

把 I/O 与外部集成推到系统边缘的小型、命名清晰的边界模块中。重构时优先让核心逻辑更纯、副作用外移。

### 步骤 6：提交前快速检查清单

- [ ] 每个模块的用途能用一句话说清吗？
- [ ] 领域逻辑不含基础设施细节吗？
- [ ] 依赖是注入的而非硬编码的吗？
- [ ] 下层没有 import 上层吗？
- [ ] 副作用都被推到系统边界了吗？
- [ ] 不 mock I/O 也能测试核心逻辑吗？

使用说明

# SOLID 架构准则

一套在编写、审查、重构代码时使用的架构准则：SOLID 五原则、组合优于继承、模块组织与副作用边界，帮助产出可维护、可测试、确定性的代码。

## 使用场景

- 实现新功能、创建新模块时的设计参考
- 代码审查时作为质量检查依据
- 重构遗留代码时的裁决准则

## 用法示例

```text
按照 SOLID 架构准则审查 src/ 目录的代码
帮我重构这个模块，注意副作用边界
```

内置提交前检查清单，可逐项核对设计质量。

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。