技能封装的标准化实践：如何设计高可复用的skill一般得封装格式

2次阅读

没有评论

共计 2120 个字符，预计需要花费 6 分钟才能阅读完成。

在开发技能型应用时，我们常常会遇到各种封装问题。这些问题不仅影响开发效率，还会导致系统难以维护和扩展。今天，我们就来聊聊如何设计一个高可复用的 skill 封装格式，解决这些痛点。

在技能模块开发中，常见的封装问题包括：

接口混乱：不同技能的输入输出格式不一致，导致调用方需要针对每个技能做特殊处理。
上下文污染：技能之间共享全局变量，容易造成数据污染和不可预知的错误。
错误处理缺失：很多技能没有统一的错误处理机制，调用方难以捕获和处理异常。
可维护性差：技能内部逻辑复杂，缺乏清晰的边界，修改一个功能可能影响其他功能。

这些问题不仅增加了开发难度，还降低了系统的稳定性和可维护性。

为了解决这些问题，我们可以遵循以下四个核心原则来设计 skill 的封装格式：

单一职责：每个 skill 只负责一个明确的功能，避免功能过于复杂。
接口契约：定义清晰的输入输出格式，确保调用方和技能之间的交互标准化。
上下文隔离：每个 skill 拥有独立的上下文，避免数据污染。
错误封装：统一错误处理机制，提供详细的错误信息和恢复策略。

下面是一个 TypeScript 的完整封装示例，展示了如何实现这些原则：

/**
 * Skill 基类，定义统一的接口和错误处理机制
 */
abstract class Skill {
  // 上下文类型，用于隔离技能内部状态
  protected context: Record<string, any> = {};

  /**
   * 执行技能
   * @param input 输入参数
   * @returns 执行结果
   */
  async execute(input: SkillInput): Promise<SkillOutput> {
    try {
      // 输入验证
      this.validateInput(input);

      // 执行技能逻辑
      const result = await this.run(input);

      // 返回标准化输出
      return {
        success: true,
        data: result,
        timestamp: new Date().toISOString()
      };
    } catch (error) {
      // 统一错误处理
      return {
        success: false,
        error: this.normalizeError(error),
        timestamp: new Date().toISOString()
      };
    }
  }

  // 抽象方法，由子类实现具体逻辑
  protected abstract run(input: SkillInput): Promise<any>;

  // 输入验证
  protected validateInput(input: SkillInput): void {if (!input) {throw new Error('Input is required');
    }
    // 子类可以添加更多验证逻辑
  }

  // 错误规范化
  protected normalizeError(error: unknown): SkillError {if (error instanceof Error) {
      return {
        code: 'INTERNAL_ERROR',
        message: error.message,
        stack: process.env.NODE_ENV === 'development' ? error.stack : undefined
      };
    }
    return {
      code: 'UNKNOWN_ERROR',
      message: 'An unknown error occurred'
    };
  }
}

// 标准化的输入输出接口
type SkillInput = Record<string, any>;
interface SkillOutput {
  success: boolean;
  data?: any;
  error?: SkillError;
  timestamp: string;
}

interface SkillError {
  code: string;
  message: string;
  stack?: string;
}

这个示例展示了如何实现一个标准的 skill 基类，包含了输入验证、错误处理、上下文管理等关键功能。子类只需要实现 run 方法，专注于业务逻辑即可。