refactor(coze): 重构 CozeApiService 使用官方 SDK 并模块化拆分 (#502)

shenjingnan · web-flow · commit 167bdab0fa5a · 2025-12-19T15:43:58.000+08:00
- 为什么改：提升代码可维护性和模块化程度，优化扣子API服务的架构设计
- 改了什么：
  - 将原本的单体 CozeApiService.ts 拆分为三个独立模块
  - 新增 cache.ts：独立的缓存管理器，支持 TTL 和模式匹配清除
  - 新增 client.ts：封装 Coze 客户端创建逻辑，支持中英文环境
  - 新增 service.ts：核心业务逻辑，整合缓存和客户端功能
  - 更新 index.ts：统一导出新模块的接口
  - 优化 CozeApiHandler.ts：增加详细的日志记录，更新导入路径
- 影响范围：
  - 删除 services/CozeApiService.ts 文件（167行）
  - 新增 lib/coze/ 目录下的三个模块文件（共189行）
  - 更新 services/index.ts 移除对旧文件的导出
  - Handler 层通过新路径导入服务，功能保持不变
- 验证方式：
  - API 接口保持向后兼容，无需修改前端调用
  - 缓存功能正常工作，支持按模式清除
  - 日志记录更加详细，便于调试和监控
  - 代码结构更清晰，便于单元测试和维护
diff --git a/apps/backend/handlers/CozeApiHandler.ts b/apps/backend/handlers/CozeApiHandler.ts
@@ -3,10 +3,10 @@
  * 提供扣子工作空间和工作流相关的 RESTful API 接口
  */
 
+import { CozeApiService } from "@/lib/coze";
 import { logger } from "@root/Logger";
 import { configManager } from "@root/configManager";
 import type { CozeWorkflowsParams } from "@root/types/coze";
-import { CozeApiService } from "@services/CozeApiService";
 import type { Context } from "hono";
 
 /**
@@ -136,8 +136,9 @@ export class CozeApiHandler {
       }
 
       const cozeApiService = getCozeApiService();
-      const workspaces = await cozeApiService.getWorkspaces();
 
+      logger.info("调用 Coze API 获取工作空间列表");
+      const workspaces = await cozeApiService.getWorkspaces();
       logger.info(`成功获取 ${workspaces.length} 个工作空间`);
 
       return c.json(
@@ -251,8 +252,11 @@ export class CozeApiHandler {
       };
 
       const cozeApiService = getCozeApiService();
-      const result = await cozeApiService.getWorkflows(params);
 
+      logger.info(
+        `开始获取工作空间 ${workspace_id} 的工作流列表，页码: ${page_num}，每页: ${page_size}`
+      );
+      const result = await cozeApiService.getWorkflows(params);
       logger.info(
         `成功获取工作空间 ${workspace_id} 的 ${result.items.length} 个工作流`
       );
@@ -354,7 +358,9 @@ export class CozeApiHandler {
       const pattern = c.req.query("pattern"); // 可选的缓存模式参数
 
       const cozeApiService = getCozeApiService();
+
       const statsBefore = cozeApiService.getCacheStats();
+      logger.info(`开始清除缓存${pattern ? ` (模式: ${pattern})` : ""}`);
 
       cozeApiService.clearCache(pattern);
 
diff --git a/apps/backend/lib/coze/cache.ts b/apps/backend/lib/coze/cache.ts
@@ -0,0 +1,75 @@
+/**
+ * 扣子 API 缓存管理器
+ * 提供带 TTL 的内存缓存功能
+ */
+
+import type { CacheItem } from "@root/types/coze";
+
+/**
+ * 缓存管理类
+ */
+export class CozeApiCache {
+  private cache = new Map<string, CacheItem>();
+
+  // 缓存过期时间配置（毫秒）
+  private readonly TTL = {
+    workspaces: 30 * 60 * 1000, // 工作空间缓存30分钟
+    workflows: 5 * 60 * 1000, // 工作流缓存5分钟
+  };
+
+  /**
+   * 设置缓存
+   */
+  set<T>(key: string, data: T, type: "workspaces" | "workflows"): void {
+    this.cache.set(key, {
+      data,
+      timestamp: Date.now(),
+      ttl: this.TTL[type],
+    });
+  }
+
+  /**
+   * 获取缓存
+   */
+  get<T>(key: string): T | null {
+    const item = this.cache.get(key);
+    if (!item) {
+      return null;
+    }
+
+    // 检查是否过期
+    if (Date.now() - item.timestamp > item.ttl) {
+      this.cache.delete(key);
+      return null;
+    }
+
+    return item.data as T;
+  }
+
+  /**
+   * 清除缓存
+   */
+  clear(pattern?: string): void {
+    if (!pattern) {
+      this.cache.clear();
+      return;
+    }
+
+    // 清除匹配模式的缓存
+    for (const key of this.cache.keys()) {
+      if (key.includes(pattern)) {
+        this.cache.delete(key);
+      }
+    }
+  }
+
+  /**
+   * 获取缓存统计信息
+   */
+  getStats(): { size: number; keys: string[] } {
+    return {
+      size: this.cache.size,
+      keys: Array.from(this.cache.keys()),
+    };
+  }
+}
diff --git a/apps/backend/lib/coze/client.ts b/apps/backend/lib/coze/client.ts
@@ -0,0 +1,32 @@
+/**
+ * 扣子 API 客户端封装
+ * 提供统一的客户端创建和配置
+ */
+
+import { CozeAPI } from "@/lib/coze";
+import config from "./config";
+
+export type Language = "zh" | "en";
+
+/**
+ * 创建 Coze API 客户端
+ * @param token - API 访问令牌
+ * @param language - API 环境语言，默认为 "zh"（中文），可选 "en"（英文）
+ */
+export function createCozeClient(
+  token: string,
+  language: Language = "zh"
+): CozeAPI {
+  if (!token || typeof token !== "string" || token.trim() === "") {
+    throw new Error("扣子 API Token 不能为空");
+  }
+
+  const env = config[language] || config.zh;
+
+  return new CozeAPI({
+    baseURL: env.COZE_BASE_URL,
+    token: token.trim(),
+    baseWsURL: env.COZE_BASE_WS_URL,
+    debug: false,
+  });
+}
diff --git a/apps/backend/lib/coze/index.ts b/apps/backend/lib/coze/index.ts
@@ -1,2 +1,5 @@
 export { default as config } from "./config";
 export * from "@coze/api";
+export { createCozeClient } from "./client";
+export { CozeApiCache } from "./cache";
+export { CozeApiService } from "./service";
diff --git a/apps/backend/lib/coze/service.ts b/apps/backend/lib/coze/service.ts
@@ -4,104 +4,25 @@
  */
 
 import type { WorkSpace } from "@/lib/coze";
-import { CozeAPI, config } from "@/lib/coze";
 import type {
-  CacheItem,
   CozeWorkflowsData,
   CozeWorkflowsParams,
   CozeWorkflowsResponse,
 } from "@root/types/coze";
-import { logger } from "../Logger";
-
-/**
- * 缓存管理类
- */
-class CozeApiCache {
-  private cache = new Map<string, CacheItem>();
-
-  // 缓存过期时间配置（毫秒）
-  private readonly TTL = {
-    workspaces: 30 * 60 * 1000, // 工作空间缓存30分钟
-    workflows: 5 * 60 * 1000, // 工作流缓存5分钟
-  };
-
-  /**
-   * 设置缓存
-   */
-  set<T>(key: string, data: T, type: "workspaces" | "workflows"): void {
-    this.cache.set(key, {
-      data,
-      timestamp: Date.now(),
-      ttl: this.TTL[type],
-    });
-  }
-
-  /**
-   * 获取缓存
-   */
-  get<T>(key: string): T | null {
-    const item = this.cache.get(key);
-    if (!item) {
-      return null;
-    }
-
-    // 检查是否过期
-    if (Date.now() - item.timestamp > item.ttl) {
-      this.cache.delete(key);
-      return null;
-    }
-
-    return item.data as T;
-  }
-
-  /**
-   * 清除缓存
-   */
-  clear(pattern?: string): void {
-    if (!pattern) {
-      this.cache.clear();
-      return;
-    }
-
-    // 清除匹配模式的缓存
-    for (const key of this.cache.keys()) {
-      if (key.includes(pattern)) {
-        this.cache.delete(key);
-      }
-    }
-  }
-
-  /**
-   * 获取缓存统计信息
-   */
-  getStats(): { size: number; keys: string[] } {
-    return {
-      size: this.cache.size,
-      keys: Array.from(this.cache.keys()),
-    };
-  }
-}
+import { CozeApiCache } from "./cache";
+import { createCozeClient } from "./client";
 
 /**
  * 扣子 API 服务类
  */
 export class CozeApiService {
   private cache = new CozeApiCache();
-  private token: string;
-  private client: CozeAPI;
+  private token: string; // 保留 token 字段用于可能的后续扩展（如 token 刷新）
+  private client: ReturnType<typeof createCozeClient>;
 
   constructor(token: string) {
-    if (!token || typeof token !== "string" || token.trim() === "") {
-      throw new Error("扣子 API Token 不能为空");
-    }
     this.token = token.trim();
-
-    this.client = new CozeAPI({
-      baseURL: config.zh.COZE_BASE_URL,
-      token: this.token,
-      baseWsURL: config.zh.COZE_BASE_WS_URL,
-      debug: false,
-    });
+    this.client = createCozeClient(this.token);
   }
 
   /**
@@ -155,7 +76,6 @@ export class CozeApiService {
    */
   clearCache(pattern?: string): void {
     this.cache.clear(pattern);
-    logger.info(`清除扣子 API 缓存${pattern ? ` (模式: ${pattern})` : ""}`);
   }
 
   /**
diff --git a/apps/backend/services/index.ts b/apps/backend/services/index.ts
@@ -8,4 +8,3 @@ export * from "./ErrorHandler.js";
 
 // CustomMCPHandler 导出 - 避免冲突的 ToolCallResult
 export { CustomMCPHandler } from "./CustomMCPHandler.js";
-export * from "./CozeApiService.js";

Original file line number	Diff line number	Diff line change
`@@ -8,4 +8,3 @@ export * from "./ErrorHandler.js";`
`8`	`8`
`9`	`9`	`// CustomMCPHandler 导出 - 避免冲突的 ToolCallResult`
`10`	`10`	`export { CustomMCPHandler } from "./CustomMCPHandler.js";`
`11`		`-export * from "./CozeApiService.js";`