ApiFlow

Appearance

ApiFlow DSL 文档技能 ​

概述 ​

本技能提供完整的 ApiFlow DSL（Domain Specific Language）语法文档，帮助用户创建和管理基于事件驱动的工作流系统。

文档结构 ​

所有参考文档位于 ApiFlow-Dsl语法/ 目录，按主题组织为以下章节：

快速导航 ​

基础入门：

触发与任务：

编排与扩展：

使用指南 ​

何时查看哪些文档 ​

用户想创建新工作流时：

  1. 先查看 01-概述.md 了解基本概念
  2. 再查看 02-项目结构与配置.md 配置项目
  3. 然后查看 03-工作流基础.md 学习工作流结构

用户想配置触发器时：

用户想实现特定任务时：

用户遇到语法错误时：

用户想查找完整示例时：

工作流程 ​

当帮助用户使用 ApiFlow 时，遵循以下流程：

  1. 理解需求 - 明确用户想要实现的功能
  2. 选择文档 - 根据需求选择相关章节阅读
  3. 提供方案 - 基于文档提供具体的 DSL 代码
  4. 解释说明 - 解释代码中的关键概念和语法
  5. 加载验证 - 修改工作流后必须调用 reload_engine 加载更新并检查错误
  6. 问题定位 - 遇到问题时使用 query_system_logs 查询系统日志定位错误

AI 助手工具（MCP） ​

ApiFlow 提供了以下 MCP 工具供 AI 助手使用：

1. reload_engine - 重新加载引擎 ​

使用时机：

  • 必须调用：每次修改工作流文件、配置文件后，必须立即调用此工具重新加载引擎
  • 验证修改是否成功生效
  • 检查是否存在语法错误或配置错误

功能说明：

  • 重新加载和初始化开发流程引擎
  • 返回加载状态和任何文件错误信息
  • 如果有错误，会详细列出错误文件和错误消息

返回信息：

  • status: "succeed" 或 "failed"
  • errorFiles: 错误文件及其错误信息的映射
  • errorMsg: 整体错误消息

最佳实践：

当你修改了工作流文件后：
1. 立即调用 reload_engine
2. 检查返回的 status 是否为 "succeed"
3. 如果 status 为 "failed"，检查 errorFiles 和 errorMsg
4. 根据错误信息修正问题，再次 reload_engine
5. 重复直到 status 为 "succeed"

2. query_system_logs - 查询系统日志 ​

使用时机：

  • 定位工作流执行错误
  • 调试任务执行问题
  • 查看引擎运行状态
  • 追踪特定时间段的系统行为

参数说明：

  • startTime (必需): 开始时间，格式 "yyyy-MM-dd HH:mm:ss"
  • endTime (可选): 结束时间，格式 "yyyy-MM-dd HH:mm:ss"
  • level (可选): 日志级别过滤 - DEBUG, INFO, WARN, ERROR
  • keyword (可选): 关键字搜索
  • loggerName (可选): Logger 名称过滤
  • page (可选): 页码，从 0 开始，默认 0
  • size (可选): 每页大小，默认 100，最大 1000

典型使用场景：

场景1：查看最近的错误日志
  参数: startTime="2025-12-12 10:00:00", level="ERROR"

场景2：搜索特定任务的执行日志
  参数: startTime="2025-12-12 10:00:00", keyword="taskName"

场景3：定位 reload_engine 失败原因
  参数: startTime="2025-12-12 10:00:00", keyword="engine", level="ERROR"

3. get_log_stats - 获取日志统计 ​

使用时机：

  • 了解系统日志整体情况
  • 查看各级别日志分布
  • 确认日志是否正常记录

返回信息：

  • 日志总数
  • 最大容量
  • 各级别（DEBUG, INFO, WARN, ERROR）日志数量分布

重要提示 ​

  • ApiFlow DSL 基于 Groovy，语法灵活但有规范约束
  • 所有任务都有声明、初始化、执行三个阶段
  • 编排模块 start {} 中只能使用指令，不能编写普通代码
  • 快捷声明时使用延迟插值 ${-> expression} 引用其他任务结果
  • HTTP 任务支持重试、异常处理、前后置拦截器
  • EACH 任务采用管道式设计，支持 filter/map/limit 等操作
  • when 指令支持多种判定方式：isTrue/isFalse/isNull/notNull/isError/to
  • exit 指令用于立即终止流程并返回结果
  • JSON 工具类提供 JSON.parse() 和 JSON.string() 方法用于JSON处理
  • Assert 工具类提供参数验证功能，确保数据有效性

技术要点 ​

  • Groovy 基础：需要了解字符串插值、闭包、Map/List 定义
  • 延迟插值：${-> expression} 用于在任务初始化阶段计算值
  • 隐式对象：config、input、log 等自动注入对象
  • 任务组：闭包包裹的一组指令，可作为参数传递
  • InvokeTask：所有调用外部服务的任务基类，支持 retry、doFirst、doLast

从索引开始 ​

如果不确定从哪里开始，建议先阅读 README.md 获取完整的文档导航和推荐学习路径。