应用调试与排查

调试是应用开发中的关键环节。Zion 平台为您提供了多种强大的排错工具：从基础的前端控制台、网络面板，到内置的无代码 AI 智能诊断，再到针对复杂实时场景的 WebSocket 订阅调试。

调试通用四步法：复现问题 → 观察现象 → 提出猜想 → 验证猜想

1. 调试通用排查流程

当应用运行出现异常（如点击无反应、数据不更新、报错弹窗）时，建议遵循以下标准排查流程：

步骤一：复现问题

在相同的设备和操作路径下尝试复现问题。
确认该问题是偶发性（如弱网引起）还是持续性（如逻辑配置错误）。
记录问题发生时的具体步骤和环境（真机、小程序、浏览器等）。

步骤二：系统性观察现象

建议从以下四个层面对系统进行多维度的观察：

层面	观察要点	推荐工具
UI 表现层	组件样式、布局、交互事件是否符合预期	浏览器开发者工具、小程序预览版
前端状态层	页面变量、全局变量、临时状态的数据流是否正常	浏览器 `Console` 面板、手机端 `vConsole`
请求传输层	GraphQL/API 请求体和响应体是否符合预期	浏览器 `Network` 面板、Zion 运行日志
数据库存储层	实体表、行级权限约束、关联关系是否正确	数据库控制台、系统诊断日志

步骤三：提出合理猜想

结合观察到的报错，推测可能导致问题的根本原因：

数据未加载：是否漏配了页面数据源或入参绑定？
操作被拦截：是否行级权限 (RLS) 未对当前用户角色开放？
数据写失败：必填项是否有缺失，或由于唯一约束冲突被数据库拦截？

步骤四：修改验证

针对猜想修改编辑器中的对应配置，重新预览并观察问题是否解决。若未解决，重新收集现象信息并开启下一轮循环。

2. 核心排障工具与方法

2.1 AI Debugger 智能诊断

AI 小助手是内置于 Zion 编辑器中的无代码智能诊断工具。它能自动分析您提供的问题、查找相关技术文档、解析运行日志并定位根本原因。

核心功能：
1. 智能匹配问题所属的功能模块。
2. 智能检索底层异常日志，解析 traceId。
3. 提供直白、可视化的解决方案。
4. 若判定为系统底层缺陷，可一键上报缺陷至官方处理。

AI 智能诊断使用指引

1. 准备所需的诊断信息

在向 AI 提问时，提供的信息越精准，诊断结果越准确：

现象描述：清晰的操作路径和异常表现（如：“提交表单后一直转圈”）。
traceId：日志追踪 ID。点击编辑器右上角“日志”图标打开运行日志，每条异常记录后都有一个 traceId。
标识符 ID：提供受影响的项目 ID（可从地址栏 URL 中复制）或对应的组件 ID（在组件右侧属性面板右上角复制）。

2. 呼出 AI 诊断界面

打开项目编辑器，点击右上角的 AI 小助手 图标：

3. 提交描述与 traceId

在对话框中详细描述问题，并直接将复制的错误 traceId 粘贴给小助手，由其自动调取后端运行日志并进行深度解析：

4. 缺陷一键上报

如果 AI 小助手诊断后认为该问题大概率是系统底层缺陷（概率 > 80%），它会提供一键“提交缺陷”选项。点击后系统将自动生成缺陷工单并指派官方值班工程师进行加急处理：

2.2 前端网络请求调试

在排查 API 请求失败、第三方服务对接异常或数据未能如期刷新的问题时，审查网络请求是最直接有效的手段。

第一步：捕获异常请求

微信小程序：
- 在小程序右上角菜单中选择 “开发调试” → 开启 vConsole。
- 触发异常操作，在底部的 vConsole 面板中切换到 Network 标签，查看对应的请求 (request) 与返回结果 (result)：
网页端/H5/Web：
- 按 F12 键打开浏览器开发者工具，切换到 Network（网络） 面板。
- 重新操作或刷新页面，在请求列表中查找并关注 graphql-v2 请求：

第二步：提取请求信息进行分析

检查网络请求时，应着重比对两个核心板块：

请求体（Request Payload）：

确认前端向服务器传输的参数（Variables）是否齐全，数据格式是否正确。

示例（查询列表时的请求体）：


{
  "query": "query blogArticleList_82df5ec2($where: blog_article_bool_exp!) { blog_article(where: $where) { id title } }",
  "variables": { "where": { "title": { "_like": "%AI%" } } }
}

响应体（Response Body）：

检查返回数据中是否存在 errors 数组。若是，提取其中具体的错误字段并参阅常见错误与解决方案进行定位：

示例（权限受限的错误响应体）：


{
  "data": null,
  "errors": [
    {
      "errorCode": 403,
      "extensions": { "classification": "TABLE_ACCESS" },
      "message": "User 1 has no permission for SELECT on order"
    }
  ]
}

2.3 GraphQL 订阅连接调试 (WebSocket)

在 Zion 平台中，诸如即时通讯、订单状态实时变更、多端协同等动态功能底层均依赖于 GraphQL WebSocket 订阅连接。如果数据未能发生实时改变，需要对 WebSocket 消息流进行专项调试。

WebSocket 排查五步法

按 F12 唤出浏览器开发者工具，并切换至 Network（网络） 面板。
在过滤分类栏中，点击并选择 WS 或 Socket 标签页。如果未显示此标签，可直接在过滤器搜索框中键入 ws。
重新刷新页面或触发订阅操作。
观察请求列表中是否出现了名为 graphql-subscription 的长连接通道。
选中该连接条目，在右侧面板中切换到 Messages（消息） 选项卡。此处将展示双向交互的实时消息流。

订阅脉搏：Keep Alive 心跳

长连接成功建立后，您会在消息流中持续接收到如下格式的控制消息：


{ "type": "ka" }

技术含义：代表 Keep Alive 心跳包，即服务器每隔 10–30 秒发送一次脉搏信号以防止连接闲置超时。
调试指导：如果接收不到 ka，说明底层网络连接已经失效、处于断开状态。

WebSocket 异常及解决方法

表现形式	可能原因	对应解决方案
找不到 `graphql-subscription` 连接	1. 未点击 WS 过滤按钮。 2. 数据源被配置成了常规的“查询”，未配置为“订阅”。	1. 选中 WS 分类并刷新页面重新加载。 2. 前往编辑器数据绑定面板，确认该数据源的拉取方式已切换至订阅类型。
连接状态频闪，且提示 `auth` 异常	当前用户的身份登录凭证 (Token) 已过期或校验失效。	重新执行登录操作，并在首个 `connection_init` 消息中检查 `authToken` 属性。
连接正常，但数据更新时页面毫无反应	1. 无数据发生真正变更。 2. 过滤条件过严，拦截了事件。 3. 当前用户对数据表无订阅权限。	在数据库中手动改写目标字段进行测试，观察消息流是否会有类型为 `type: "data"` 的新包送达。如果出现 `type: "error"`，则表示权限不足。

3. 常见排错场景案例分析

本章节汇总了 Zion 开发中高频出现的五类排障典型案例：

案例 1：支付、退款执行失败（权限校验拦截）

故障现象：执行支付/退款动作流时，前台界面报错，行为流直接中断。
原因分析：日志异常多表现为权限受限。Zion 平台的写操作需要特定的操作角色支持，而后台对应角色的数据表写入或 API 行为调用权限未打开。
解决办法：进入应用权限控制面板，开启特定角色对退款行为流、支付记录表的访问和创建权限。
排障图示：

案例 2：小程序 API 执行错误（非空字段传空）

故障现象：小程序端提交表单或执行远程 API 动作时直接提示出错。
原因分析：传参类型发生偏离，将本应是非空文本/数值的参数绑定，向后台传送了 null 值。
解决办法：在编辑器中追溯触发此行为的事件，检查其各输入参数的数据绑定逻辑。确保该动作触发时，绑定源（如输入组件、局部变量）中拥有合规有效的数据内容。
排障图示：

案例 3：行为流运行故障（字段拼写拼错）

故障现象：动作链执行失败，后台运行日志抛出异常。
原因分析：在进行前端逻辑绑定、第三方 Webhook 对接或代码块节点书写时，对数据库字段名称、实体关系别名的拼写出现笔误，导致底层的数据库引擎无法识别对应的字段。
解决办法：检查报错日志中的报错信息，对照数据模型设计面板中的字段名，更正对应绑定节点中的属性别名。
排障图示：

案例 4：更改表数据报错（唯一约束冲突引发崩溃）

故障现象：点击创建或更新数据时，界面卡死并弹出服务器内部异常。
原因分析：在对设定了“唯一”（Unique）约束的字段（例如“手机号”、“用户名”）录入重复信息，导致违反了数据库的原子约束。
解决办法：对写入逻辑进行审查，或在写入操作触发前增加查重逻辑分支；确保产生冲突的数据不会被强行提交。
排障图示：

案例 5：条件容器展现不合预期（数据逻辑分支问题）

故障现象：特定卡片或状态在页面上没有展示，或展示的内容错乱。
原因分析：条件式容器中所关联的控制字段（如：status_code，role_id）的内容未被正确赋值、传递过程丢失，或判断条件未配置最后的兜底“总是”分支。
解决办法：通过控制台或日志提取该数据源真实的字段取值，对条件式容器的各视图展现条件及逻辑边界（如等于、包含、非空）重新梳理校准。
排障图示：

4. 技术支持与求助指南

当通过上述手段均无法自我定位或闭环解决问题时，可按以下指南联系 Zion 官方团队寻求协助：

4.1 官方求助渠道

平台帮助中心：首选在帮助文档中检索对应组件的配置指南。
官方社区与交流群：在 Zion 官方社区發帖，或在官方交流社群中@值班技术支持。
专属技术支持：对时效和保密性有高要求的商业级项目，建议在个人中心订阅专属的一对一技术大拿服务，提供专人代排查。

4.2 高效提问规范

为了让技术支持团队能秒级理解并着手处理您的问题，提问时请务必整理并提供以下要素：

✓ 推荐的提问格式（示例）：
1. 我的期望：在完成退款审批动作流后，订单状态能够实时变更，且退款原路退回。
2. 我已做过的排查：已确认退款行为流调用成功，微信支付商户端资金余额充裕。
3. 故障组件及页面：项目 ID 为 jnPx68566AD，在 pages/admin_refund 的“确认退款”动作流节点。
4. 异常日志与截图：traceId 为 refund-trace-83279184。附带 Network 抛出 TABLE_ACCESS 的截图。
✗ 错误的提问示例：
- “预览出错了，麻烦看看是怎么回事？”（缺失核心要素，技术人员无法定位）
- “我想做一个小程序商城，怎么配？”（问题过于宏大，不属于具体的故障调试范围）