frontend-query-mutation

前端查询与变更

意图

• 将 API 钩子放在 controllers/API/queries/{domain}/ 中，作为有序的事实来源。
• 使用 UseRequestProcessor 统一处理重试、失效和错误。
• 所有 HTTP 调用都使用 Axios api 实例（REST 请求绝不使用原始 fetch）。
• 流式操作（构建、聊天）使用 performStreamingRequest()。
• 在变更的 onSettled 回调中处理缓存失效。

架构概览

Langflow 使用 Axios + TanStack React Query v5 获取数据。项目没有 oRPC 或契约层。架构如下：

Component
  -> API hook (controllers/API/queries/{domain}/use-{verb}-{resource}.ts)
    -> UseRequestProcessor (controllers/API/services/request-processor.ts)
      -> useQuery / useMutation (TanStack React Query)
        -> queryFn / mutationFn
          -> api.get/post/patch/delete (Axios instance from controllers/API/api.tsx)

关键文件

文件	用途
controllers/API/api.tsx	Axios 实例、ApiInterceptor 组件、performStreamingRequest()
controllers/API/services/request-processor.ts	UseRequestProcessor 钩子，封装 useQuery/useMutation，并设置默认重试配置
controllers/API/helpers/constants.ts	URL 常量（URLs）和 getURL() 辅助函数
controllers/API/queries/{domain}/	按领域组织的查询和变更钩子
types/api/index.ts	useQueryFunctionType、useMutationFunctionType 类型辅助工具
stores/	用于客户端状态的 Zustand 存储

工作流

1. 确定变更范围。
   • 阅读 references/query-patterns.md，了解钩子结构、命名、URL 模式以及查询/变更的调用点形式。
   • 阅读 references/runtime-rules.md，了解条件查询、失效处理、错误处理和流式传输。
   • 如果任务涉及钩子创建和运行时行为，请阅读这两份参考文档。
2. 按照现有模式实现钩子。
   • 使用 UseRequestProcessor 封装 query() 和 mutate()。
   • 所有 HTTP 调用都使用 Axios api 实例。
   • 使用 getURL() 构建 API 路径。
   • 使用 useQueryFunctionType 或 useMutationFunctionType 为钩子指定类型。
3. 遵循 Langflow 约定。
   • 查询键是包含钩子名称的数组：["useGetFlows"]。
   • 变更在 onSettled 中使相关查询失效。
   • Zustand 存储的更新应在查询/变更函数中执行，而不是在组件中执行。
   • UseRequestProcessor 提供默认重试机制（查询重试 5 次，变更重试 3 次），并使用指数退避。

常见修改文件

• controllers/API/queries/{domain}/use-get-*.ts（查询钩子）
• controllers/API/queries/{domain}/use-post-*.ts（创建变更）
• controllers/API/queries/{domain}/use-patch-*.ts（更新变更）
• controllers/API/queries/{domain}/use-delete-*.ts（删除变更）
• controllers/API/helpers/constants.ts（URL 常量）
• types/api/index.ts（API 类型定义）
• stores/（由查询触发的 Zustand 存储更新）

参考资料

• 钩子结构、命名约定、目录布局和反模式，请参阅 references/query-patterns.md。
• 条件查询、失效处理、mutate 与 mutateAsync 的区别、错误处理和流式请求，请参阅 references/runtime-rules.md。

将此技能视为 Langflow 前端工作的查询与变更唯一入口。详细规则应保留在参考文件中，不要在项目文档中重复。