变量与参数

在数据模型与流转中，我们了解到变量和参数承担着应用运行过程中的“内存”角色。如果说数据库是应用长期保存记忆的“硬盘”，那么变量与参数就是应用在运行过程中进行瞬时计算、跨边界传递信息的“内存”。

要构建高内聚、低耦合的应用架构，必须从本质上区分两者的心智模型：

• 变量：用于**“存储”状态。关注的是数据的生命周期和作用域**。
• 参数：用于**“传递”信息。关注的是跨越物理/逻辑边界时的输入与输出契约**。

1. 变量 —— 状态的存储与复用

变量用于在特定的运行范围内，存储、更新和复用临时性的状态或数据。根据作用范围的不同，Zion 中的变量分为三个层级：

1.1 客户端变量

• 作用域：全局跨页面生效。只要当前用户未关闭或退出应用，客户端变量的值在所有页面中均可以被直接读取或修改。
• 生命周期：伴随整个应用会话。在应用打开时初始化，并在用户关闭应用或刷新页面（网页端）时重置。
• 典型场景：存储全局应用配置、当前登录用户的基本信息缓存、跨多个页面的购物车草稿。

1.2 页面变量

• 作用域：仅限当前单页面生效。只能在创建该变量的单页面内部组件中被引用或修改。
• 生命周期：伴随页面生命周期。进入页面时初始化，离开该页面时自动销毁并释放内存。
• 典型场景：表单输入的暂存、控制当前页面内弹窗/抽屉的显隐状态（布尔值）、页面内的临时检索关键字。

1.3 行为流变量 (局部变量)

• 作用域：仅限当前行为流运行期间生效。
• 生命周期：伴随逻辑流的执行。行为流开始时初始化，运行结束时立即物理销毁。
• 典型场景：在复杂的后台业务流中暂存中间计算结果。例如在“循环节点”中不断累加总金额，或在发起 API 请求前拼接并暂存一段文本。

2. 参数 —— 跨边界的信息传递

参数不用于“存储”长期状态，而是作为信息通道，专门用于在两个具有隔离边界的模块之间传递数据。无论是页面、组件，还是 API、AI 和行为流，它们都遵循统一的输入与输出契约模型。

2.1 路由与页面参数（跨页面边界）

当进行页面跳转时，通过 URL 传递参数是标准的跨页面通信方式：

• 路径参数：直接作为网址路由的一部分（如 /product/:id）。它是结构化且必填的，决定了页面的核心内容。极度利于搜索引擎优化（SEO），常用于详情页。
• 查询参数：附加在网址末尾的键值对（如 ?source=qr&page=2）。它是非结构化且选填的，不改变核心路由。常用于渠道追踪、分页、筛选条件传递。

2.2 自定义组件参数（跨 UI 组件边界）

当您将一组 UI 封装为“自定义组件”时，它就形成了一个独立的黑盒，需要通过参数与外部页面通信：

• 属性与输入参数：外部父页面向内部子组件传递数据（如向“商品卡片”组件传入 商品图片 和 商品价格）。
• 事件与输出参数：内部子组件向外部父页面抛出动作及携带的数据（如卡片内部的“加入购物车”按钮被点击时，向外抛出 当前商品ID）。

2.3 逻辑处理参数（跨系统/逻辑边界）

无论是行为流、外部 API 还是 AI Agent，它们在本质上都是“接收指令 -> 处理计算 -> 返回结果”的黑盒。它们统一遵循以下参数模型：

• 输入参数：外部调用方（如按钮点击事件）必须提供的前置数据。例如，调用支付 API 需要传入 订单号 和 金额；调用 AI 节点需要传入 提示词文本；调用创建订单的行为流需要传入 商品列表。
• 输出参数：黑盒逻辑执行完毕后，返回给调用方的结果。例如行为流算完价格后返回的 总价；AI 返回的 生成的文案；API 返回的 状态码。前端组件通过捕获这些输出参数，进行后续的页面渲染或反馈。

3. 变量与参数的选型矩阵