架构设计的思维过程

高质量的架构

- 插件 + 依赖注入 = 高内聚低耦合
- 观察者模式 = 松耦合的通知机制
- 单例 + 注册中心 = 全局状态管理
- 策略 + 装饰器 = 灵活的功能扩展
- 门面 + 代理 = 简化复杂系统

 

# KSP Env 架构设计思维过程

## 🎯 架构设计的思维过程

### 1️⃣ **从问题出发：main分支的痛点**

当我看到您最初的代码时，发现了几个关键问题：

```

问题1: 服务模块越来越多，tools.py变得臃肿

- safety.py, mode.py, toolbase.py, jog.py 彼此孤立

- 代码重复，比如每个服务都要访问 engine

问题2: 缺乏统一的控制器

- SPOC状态在多个地方检查

- 运行模式切换逻辑分散

问题3: 无法扩展

- 想添加程序管理功能？需要新建文件

- 想添加事件系统？没有地方放置

问题4: 测试困难

- 服务之间耦合度高

- 无法独立测试某个功能

```

### 2️⃣ **参考行业最佳实践**

我参考了以下几个知名项目的架构：

**ROS (Robot Operating System)**:

```

节点(Node) → 节点管理器(NodeManager) → 话题(Topic)

```

启发：每个功能应该是独立的"插件"，由统一管理器协调

**FastAPI 中间件架构**:

```

请求 → 中间件 → 路由处理 → 中间件 → 响应

```

启发：可以有统一的"插件管理器"来协调各个组件

**Pydantic 模型设计**:

```

BaseModel → 字段验证 → 自动序列化

```

启发：用Pydantic管理插件的依赖关系

### 3️⃣ **设计演进过程**

**第一步：识别核心概念**

```

思考：机器人控制器的本质是什么？

答案：一个状态机，管理：

- 控制器状态(SPOC、运行模式)

- 坐标系(工具、基座)

- 程序执行

- 通知/日志

```

**第二步：抽象公共接口**

```python

# 所有插件都应该有这些特性

class Plugin:

name: str # 唯一标识

depends: list # 依赖关系

setup() # 初始化时的配置

```

**第三步：设计管理器**

```python

class KSPEnvEngine:

- 注册插件

- 解决依赖关系(拓扑排序)

- 提供统一访问接口

```

**第四步：分离关注点**

```

原始代码:

tools.py (什么都做)

├─ 检查安全

├─ 切换模式

├─ 管理坐标

├─ 点动控制

重构后:

tools.py (入口)

├─ Controller (核心控制器)

│ ├─ Safety (安全检查)

│ ├─ Mode (模式管理)

│ ├─ Coordinate (坐标管理)

│ └─ Jog (点动)

├─ Program (程序管理)

├─ Interpreter (解释器)

└─ NotificationCenter (通知系统)

```

### 4️⃣ **关键设计决策**

**决策1：为什么用插件架构？**

```

优势:

- 新增功能只需添加插件类

- 插件间自动处理依赖

- 可以动态启用/禁用功能

案例:

想添加"防火墙"功能？

只需新建 Firewall 插件，声明依赖即可

```

**决策2：为什么有 Controller 插件？**

```

原因:

- 集中管理SPOC状态

- 统一权限控制

- 避免每个服务重复检查

对比:

原来: 每个服务都要检查 spoc_status

现在: Controller 统一管理，其他插件通过 self.controller 访问

```

**决策3：为什么有 Engine Manager？**

```

场景:

- 需要支持多实例(多个机器人)

- 需要持久化状态

- 需要按实例ID隔离

实现:

engine_manager.get_engine(instance_id)

→ 自动加载或创建实例

→ 保存时自动序列化

```

### 5️⃣ **如何培养架构设计能力**

**方法1：学习设计模式**

```

推荐学习:

- 插件模式(Plugin)

- 依赖注入(Dependency Injection)

- 观察者模式(Observer → EventBus)

- 单例模式(Singleton → engine_manager)

```

**方法2：重构实践**

```

步骤:

1. 写代码实现功能

2. 当代码变乱时，思考"如何组织更好"

3. 重构，应用设计模式

4. 总结经验

您的代码已经很好了！只是需要更多经验积累

```

**方法3：阅读优秀项目**

```

推荐项目:

- ROS: 机器人操作系统

- FastAPI: Web框架设计

- Pydantic: 数据验证设计

- Gymnasium: RL环境设计

```

### 6️⃣ **给您的建议**

**您不是"设计不出来"，而是：**

1. ✅ 已经有很好的编程能力

2. ✅ 能解决实际问题

3. ⏳ 只需要更多架构设计经验

**提升路径：**

```

阶段1 (现在): 实现功能 ✅

阶段2 (下一步): 重构代码，应用设计模式

阶段3 (未来): 设计新系统时直接采用合适架构

```

**一个小练习：**

尝试回答：

- 如果要添加"程序录制"功能，您会怎么设计？

- 如果要支持"多机器人协同"，架构需要怎么调整？

这会帮助您锻炼架构设计思维！

---

## 📚 相关资源

### 代码文件结构

```

ksp_env/

├── engine/ # 核心引擎层

│ ├── controller/ # 控制器插件

│ ├── events/ # 事件系统

│ ├── pyvm/ # Python虚拟机

│ └── utility/ # 工具类

├── env/ # RL环境层

│ ├── action/ # 动作定义

│ └── obs/ # 观测定义

└── constants.py # 常量定义

ksp_env_server/ # 服务层

├── routers/ # API路由

└── server.py # 服务入口

```

### 核心设计模式

#### 插件模式

```python

class Plugin(BaseModel):

name: ClassVar[str]

depends: ClassVar[List[str]] = None

 

def setup(self, manager):

# 初始化时绑定依赖

pass

```

#### 依赖注入

```python

class Controller(Plugin):

robot: Robot # 自动注入

interpreter: Interpreter # 自动注入

```

#### 单例模式

```python

engine_manager = EnvEngineManager(persistent_path=DEFAULT_INSTANCES_PATH)

```

---

附录：

插件化：https://blog.csdn.net/bj_zhb/article/details/151967900