tian/NavisworksTransport

Fork 0

tian 773e3e63ae 完成了UI架构重构，增加了一些测试。解决了测试框架依赖导致的启动崩溃问题。

2025-08-17 23:02:09 +08:00

8.0 KiB

Raw Blame History

Command Pattern基础框架使用指南

文档类型: 技术使用指南
创建时间: 2025年8月17日
作者: NavisworksTransport开发团队
版本: 1.0

概述

本文档描述了NavisworksTransport项目中新实现的Command Pattern基础框架，这是UI架构重构项目的T1.5任务成果。该框架为后续业务逻辑重构提供了标准化的命令执行基础设施。

架构设计

核心组件

IPathPlanningCommand接口 (IPathPlanningCommand.cs)
- 定义了标准化的命令执行接口
- 支持异步执行和结果返回
- 提供执行状态跟踪和进度报告
CommandBase抽象基类 (CommandBase.cs)
- 提供公共的Command执行逻辑
- 统一的异常处理机制
- 执行状态管理和事件通知
PathPlanningResult数据传输对象 (PathPlanningResult.cs)
- 标准化的操作结果格式
- 支持泛型结果类型
- 包含成功/失败状态、数据、错误信息
CommandExecutor异步执行框架 (CommandExecutor.cs)
- 基于Task的异步执行
- 支持命令队列和并发控制
- 与UIStateManager深度集成
CommandManager统一管理器 (CommandManager.cs)
- 命令注册和工厂模式
- 参数化命令支持
- 执行状态统计和监控

与UIStateManager集成

Command Pattern框架与T1.1任务实现的UIStateManager深度集成：

线程安全UI更新: 所有UI相关操作通过UIStateManager进行
异步UI操作: 支持ExecuteUIUpdateAsync异步UI更新
队列UI更新: 支持QueueUIUpdate非阻塞UI更新
优先级控制: 支持UIUpdatePriority控制更新优先级

使用示例

基本命令执行

// 创建命令
var command = new TestCommand("示例命令", 3000);

// 验证命令
var canExecute = command.CanExecute();
if (!canExecute.IsSuccess)
{
    // 处理验证错误
    return;
}

// 执行命令
var result = await command.ExecuteAsync();
if (result.IsSuccess)
{
    // 处理成功结果
    LogManager.Info($"命令执行成功: {result.Message}");
}
else
{
    // 处理失败结果
    LogManager.Error($"命令执行失败: {result.ErrorMessage}");
}

通过CommandManager执行

var commandManager = CommandManager.Instance;

// 执行预注册的命令
var result = await commandManager.ExecuteCommandAsync("TestCommand");

// 执行参数化命令
var paramResult = await commandManager.ExecuteCommandAsync("TestCommandWithParams", 
    new object[] { "参数消息", 2000 });

队列执行

var executor = CommandExecutor.Instance;

// 将命令加入队列
var queueResult = await executor.EnqueueAsync(command, CommandPriority.High);

命令状态生命周期

NotStarted → Validating → Executing → Completed/Failed/Cancelled
                ↓              ↓
           ValidationError   ExecutionError

事件通知

框架提供多层次的事件通知：

命令级事件: StatusChanged、ProgressChanged
执行器级事件: CommandStarted、CommandCompleted
管理器级事件: CommandRegistered、CommandExecutionStarted

测试和验证

集成测试

CommandPatternIntegrationTest.cs: 完整的集成测试套件
CommandFrameworkIntegrationTest.cs: 功能测试和示例
TestCommand.cs: 测试用例和示例实现

快速验证

// 快速验证框架可用性
var isValid = await CommandPatternIntegrationTest.QuickVerificationAsync();

完整测试

// 运行完整集成测试
var testResult = await CommandPatternIntegrationTest.RunIntegrationTestAsync();

扩展点

创建自定义命令

public class CustomCommand : CommandBase
{
    public CustomCommand() : base("CustomCommand", "自定义命令", "示例自定义命令")
    {
    }

    protected override PathPlanningResult ValidateParameters()
    {
        // 实现参数验证逻辑
        return PathPlanningResult.Success("验证通过");
    }

    protected override async Task<PathPlanningResult> ExecuteInternalAsync(CancellationToken cancellationToken)
    {
        // 实现命令执行逻辑
        UpdateProgress(50, "执行中...");
        await Task.Delay(1000, cancellationToken);
        UpdateProgress(100, "完成");
        
        return PathPlanningResult.Success("执行成功");
    }
}

注册自定义命令

var commandManager = CommandManager.Instance;
commandManager.RegisterCommand("CustomCommand", () => new CustomCommand());

性能特性

异步执行: 基于Task/async-await模式，避免阻塞UI线程
并发控制: 支持最大并发执行数限制（默认3个）
队列管理: 内置命令队列，支持优先级排序
内存优化: 使用ConcurrentDictionary和ConcurrentQueue保证线程安全
资源清理: 实现IDisposable模式，确保资源正确释放

错误处理

统一异常处理: CommandBase提供统一的异常捕获和转换
详细错误信息: PathPlanningResult包含完整的错误上下文
日志集成: 与LogManager集成，提供完整的执行日志
取消支持: 支持CancellationToken的优雅取消

与现有系统的关系

替代事件驱动模式

Command Pattern框架将逐步替代现有的事件驱动模式，特别是：

PathPlanningManager.StatusChanged事件
其他业务逻辑中的事件驱动操作

业务逻辑分离

完全分离: 业务逻辑与UI完全分离
可测试性: 命令可以独立测试，不依赖UI环境
可重用性: 命令可以在不同上下文中重用

后续开发指导

T2.x任务集成

后续的业务逻辑重构任务（T2.2, T2.3等）应该：

基于Command Pattern实现业务逻辑
使用CommandManager进行命令管理
通过UIStateManager进行UI更新
遵循异步编程模式

最佳实践

命令设计: 每个命令应该有明确的职责和边界
参数验证: 在ValidateParameters中进行完整的参数验证
进度报告: 使用UpdateProgress提供用户反馈
错误处理: 提供清晰、可操作的错误消息
取消支持: 在长时间运行的操作中检查取消令牌

文件结构

src/Commands/
├── IPathPlanningCommand.cs          # 核心接口
├── CommandBase.cs                   # 抽象基类
├── PathPlanningResult.cs            # 结果数据传输对象
├── CommandExecutor.cs               # 异步执行框架
├── CommandManager.cs                # 统一管理器
├── Examples/
│   └── TestCommand.cs              # 测试用例和示例

tests/Integration/
├── CommandFrameworkIntegrationTest.cs  # 功能测试
└── CommandPatternIntegrationTest.cs    # 集成测试

开发团队使用建议

代理A - UI重构专家

使用CommandManager集成命令执行到UI组件
通过UIStateManager确保线程安全的UI更新
在ViewModel中使用Command Pattern替代事件驱动

代理B - 数据架构专家

设计数据相关的命令操作
确保数据操作的事务性和一致性
实现数据验证相关的命令

代理C - 业务逻辑专家

实现核心业务逻辑命令
设计命令的组合和编排
确保业务规则的正确实现

总结

Command Pattern基础框架成功实现了T1.5任务的所有要求：

✅ 定义了标准化的IPathPlanningCommand接口
✅ 实现了CommandBase抽象基类
✅ 创建了PathPlanningResult数据传输对象
✅ 建立了异步命令执行框架
✅ 与UIStateManager深度集成
✅ 提供了完整的测试和验证

该框架为后续的业务逻辑重构（T2.x任务）提供了坚实的基础，实现了业务逻辑与UI的完全分离，彻底解决了线程安全问题。

文档状态: 完成
下次更新: 根据T2.x任务的实施情况进行更新
相关文档:

UI架构重构技术设计方案_20250816.md
UIStateManager使用指南_20250817.md
线程安全修复报告.md

8.0 KiB Raw Blame History Unescape Escape