ApiFlow

Appearance

项目结构与配置 ​

工作流项目结构 ​

每个工作流项目由若特定目录及groovy脚本文件组成，你可以充分利用系统文件的编辑管理生态如：采用任何你熟悉的工具创建和编辑文件，并通过git进行版本管理 ，再通过rsync进行传输等。又或是利用claude code 、cursor等AI工具进行编辑。

以下是ApiFlow DSL 的项目结构：

# 我的工作流项目
📁 my-workflow-project/
  📁 api/							 # 工作流根目录
      flow1.groovy  			 # 工作流1
      📁 example/
            📄 flow2.groovy  # 工作流2
            📄 flow3.groovy  # 工作流3
  📁 public/					 # 可对外公开访问的目录
  		 📄 logo.png
  		 📄 index.html
  📁 app/      					 # 保留目录
  📄config.groovy 			 # 配置信息
  #.. 除保留目录外可创建其它目录及文件(目前没有规范要求)

目录说明 ​

  1. 配置文件：名称和位置都是固定的即：{项目路径}/config.groovy
  2. 工作流文件：必须在api目录以及子目录下的groovy文件，命名不能是中文、不能用下划线以外的特殊符号、不能以数字开头，须符合java类命名规则。
  3. 公开静态文件：必须在public目录下，存放外部可直接访问的静态文件如图片、html等。
  4. 其它文件： 可存放其它目录及文件目前暂未制定规范要求

上述目录中除工作流文件与配置文件外其它都不是必须的。

项目配置 ​

{项目路径}/config.groovy 配置文件基于 groovy的ConfigSlurper 实现，必须遵循其基本语法。

配置语法 ​

配置项名 = 配置值
复合配置项.子项 = 配置值
  • 配置项名需符合groovy命名规则，
  • 配置值可以是groovy 中任意可序列化的数据类型如字符串、boolean、数字、Map、List、Date等。
  • 配置项可以拥有1到多个子项，组成一个复合配置对象
  • 配置项可以采用中文表示

简单示例 ​

groovy
welcome = "welcome  apiFlow" // 基本配置
isDev = false // 是否为开发环境
// 复合配置
http.token= "XXXXX"
http.content.timeout= 2000
http.read.timeout= 2000
// 引用其它配置信息
http.describe = "token:${http.token} ,readTimeout:${http.read.timeout} "

上述配置信息可在工作流文件中通过config隐示对象进行引入如：config.welcome 或config.http.token

嵌套配置 ​

复合配置也可以采用嵌套方式进行配置如：

groovy
// 嵌套配置
http {
  address {
    host = "127.0.0.1"
    port = 9000
  }
}

// 上述配置等同于如下:
http.address.host=""
http.address.port=9000

app 应用配置 ​

使用指定app应用前须在config.groovy中进行声明和配置其格式如下：

groovy
app.实例名称.type= ""   		// 应用类型 （必填项）
app.实例名称.配置1= ""	 			// 应用配置1
app.实例名称.配置2= 0   		// 应用配置2
//...其它配置

应用配置统一前缀是app，子项是应用名，再往后就是应用相关配置，其中type是固定的必填项，是应用的完整java类名。其它配置视应用要求而定。

MySQL 应用配置示例 ​

groovy
app.mysql.type="org.apiFlow.database.MySqlApp" 					// mySql应用类名
app.mysql.url="jdbc:mysql://192.168.0.11:3306/wechat_ai" // jdbc url连接
app.mysql.user="root"														 // mySql用户名
app.mysql.password="123456"													 // mySql密码

配置好应用之后就可以在工作流文件中直接引用应用实例名称，如下例就调用了前面配置好的mysql应用

groovy
// 声明任务t1，在mysql中执行sql语句
t1 = mysql "select 1"

复杂配置 ​

config.groovy 基于ConfigSlurper 实现，本质上还是一个groovy脚本，可编写任意groovy代码来实现配置：如循环、if判断等。

配置随机数示例 ​

下例首先配置一个空列表，然后通过循环为其配置了10个随机数，之后就可以在工作流文件中引入该随机数，如取第一个随机数：config.randoms[0]

groovy
// 配置10个100以内的随机数
randoms = []
for (i in 0..9) {
    randoms[i]=new Random().nextInt(100)
}

判断操作系统示例 ​

下例定义了一个os复合对象并根据系统属性os.name 来判断当前运行的平台。

groovy
// 判断当前操作系统
os {
    def osName = System.getProperty("os.name").toLowerCase() //定义局部变量 ，该值不会出现在最终的配置中
    isWindows = osName.contains("win")
    isLinux = osName.contains("ffff")
    isMac = osName.contains("mac")
}

上例中 def 定义的变量为局部变量，该值不会出现在最终的配置中。

配置编写建议 ​

  • 如果复合变量所有子项没有超过10项，建议采用级联的方式而不是嵌套的方式。
  • 尽量避免脚本来初始化变量，而是采用固定的值
  • 不要在配置中定义不可序化的对象值如 ：System.out、 new Thread() 、new Object() 等
  • 不要在配置中定义闭包，目前关于工具函数还没有制定相关规范。
  • 尽量不要在配置中import 其它类，而是尽量采用ApiFlow上下文中引入的默认工具类，除非默认工具类实现不了需求。
  • 要是尽可能采用groovy语法糖以简化配置 如日期解析:Date.pase('yyyy-MM-dd','2025-11-11')

下一步 ​