从零构建 API 低代码平台系列（九）表达式系统设计与实现

前言

上文《从零构建 API 低代码平台系列（八）流程执行引擎核心原理》我们介绍了流程执行引擎的核心原理。本文将深入探讨 APIFlow 的表达式系统——这是实现节点间数据传递和动态参数的关键能力，也是让低代码平台真正灵活强大的核心特性。

💡 为什么表达式系统如此重要？

在低代码平台中，数据需要在节点之间流转。表达式系统让用户可以用简单的 {{input.user_id}} 语法，实现复杂的数据引用和转换，无需编写代码即可完成业务逻辑。

一、表达式系统概览

1.1 表达式语法

APIFlow 采用类似 n8n 的表达式语法，简单直观：

基本语法：{{变量路径}}

示例：
{{input.user_id}}           → 获取输入参数 user_id
{{json.rows[0].name}}       → 获取上游节点输出的第一行 name 字段
{{node-1.result}}           → 获取指定节点 node-1 的输出
{{$now}}                    → 获取当前时间
{{$uuid}}                   → 生成 UUID

1.2 表达式分类

🎯 商业价值解读

表达式系统对企业意味着什么？

二、核心表达式详解

2.1 输入参数表达式

获取 API 请求传入的参数：

请求体：
{
  "user_id": 123,
  "query": {
    "status": "active"
  }
}

表达式：
{{input.user_id}}        → 123
{{input.query.status}}   → "active"

支持的数据来源：

2.2 上游节点输出表达式

获取上游节点的执行结果：

上游 MySQL 节点输出：
{
  "rows": [
    { "id": 1, "name": "张三" },
    { "id": 2, "name": "李四" }
  ],
  "affected": 2
}

表达式：
{{json.rows}}           → 完整的 rows 数组
{{json.rows[0]}}        → 第一行数据
{{json.rows[0].name}}   → "张三"
{{json.affected}}       → 2

2.3 指定节点输出表达式

当流程有多个分支时，可以指定获取某个节点的输出：

流程结构：
Webhook ──▶ MySQL(node-1) ──▶ Response
                │
                └──▶ Redis(node-2)

表达式：
{{node-1.rows}}     → MySQL 节点的输出
{{node-2.value}}    → Redis 节点的输出

2.4 内置变量表达式

系统提供的内置变量：

2.5 环境变量表达式

获取系统环境变量：

{{$env.DB_HOST}}     → 数据库主机地址
{{$env.API_KEY}}     → API 密钥
{{$env.ENV_NAME}}    → 环境名称

安全说明：敏感环境变量可在后台配置白名单，非白名单变量不可访问。

三、高级表达式功能

3.1 数组操作

支持数组索引和切片：

数据：
{
  "items": ["a", "b", "c", "d", "e"]
}

表达式：
{{json.items[0]}}       → "a"（第一个元素）
{{json.items[-1]}}      → "e"（最后一个元素）
{{json.items[0:3]}}     → ["a", "b", "c"]（切片）

3.2 对象嵌套

支持多层嵌套访问：

数据：
{
  "user": {
    "profile": {
      "name": "张三",
      "age": 25
    }
  }
}

表达式：
{{json.user.profile.name}}    → "张三"
{{json.user.profile.age}}     → 25

3.3 表达式组合

支持在字符串中组合多个表达式：

模板：
"用户 {{json.rows[0].name}} 的订单数量为 {{json.rows[0].order_count}}"

解析结果：
"用户 张三 的订单数量为 5"

3.4 条件表达式

支持简单的条件判断：

语法：{{条件 ? 真值 : 假值}}

示例：
{{json.status == 'active' ? '正常' : '禁用'}}
{{json.count > 0 ? json.count : 0}}

四、表达式编辑器

4.1 智能提示

配置面板内置智能提示功能：

输入 {{        → 自动显示可用变量列表
输入 {{json.   → 自动显示上游节点输出的字段
输入 {{$       → 自动显示内置变量列表

4.2 实时预览

编辑表达式时实时显示解析结果：

┌─────────────────────────────────────────────────────────────────┐
│  SQL 语句                                                        │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ SELECT * FROM users WHERE id = {{input.user_id}}         │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  预览结果：                                                      │
│  SELECT * FROM users WHERE id = 123                            │
└─────────────────────────────────────────────────────────────────┘

4.3 错误提示

表达式错误时提供明确提示：

五、性能优化

5.1 解析优化

5.2 性能数据

六、最佳实践

6.1 命名规范

建议使用有意义的变量名：

✅ 推荐：
{{input.user_id}}
{{json.order_info}}
{{node-query-user.rows}}

❌ 不推荐：
{{input.a}}
{{json.x}}
{{node-1.r}}

6.2 错误处理

建议为可能为空的表达式提供默认值：

{{json.user.name || '未知用户'}}
{{json.count || 0}}

6.3 调试技巧

使用 Response 节点输出中间结果：

调试配置：
{
  "input": {{input}},
  "mysql_result": {{json}},
  "redis_result": {{node-2}}
}

七、总结

APIFlow 的表达式系统，体现了低代码平台的核心能力：

• ✅ 语法简单：{{变量路径}} 一学就会

• ✅ 功能强大：支持数组、对象、条件判断

• ✅ 智能辅助：自动提示、实时预览、错误提示

• ✅ 性能优异：毫秒级解析，支持高并发

• ✅ 兼容 n8n：语法与 n8n 保持一致

这是一个让业务人员也能轻松使用的数据传递系统。

🎁 获取方式，添加微信：daniel5185186

源码授权

• ✅ 完整源代码（前端 + 后端）

• ✅ 详细部署文档

• ✅ 一对一技术支持

• ✅ 后续版本更新

定制开发

• ✅ 新增表达式函数

• ✅ 自定义变量类型

• ✅ 性能优化定制

• ✅ 技术培训服务