Gate 低代码平台设计

在营销活动、大促活动页面的迭代通常面临高频次、多语种、多端自适应以及极高的高峰期性能要求。传统的全代码开发模式周期长、维护成本高，难以跟上运营步伐。

本架构方案展示了一套基于 Next.js (App/Pages Router) + Builder.io SDK 核心驱动的前端低代码搭建体系。通过将底层通用能力（鉴权、埋点、多语言、主题、SEO）抽离为平台基建，将复杂多变的业务逻辑封装为独立弹药库（业务组件库），并借助低代码引擎实现动态 Schema 的下发与高效预渲染（SSR/SSG）。该方案成功实现了“研发一次封装，运营千次复用”的降本增效目标。

作为公司运营增长部分的工具，主要处理两种类型的活动，大型活动与可同质化活动，大型活动需要更多的特效、视频等用户体验，可同质化相对来说不需要非常高的特效，当然这也不代表只能用最简单页面效果。

而低代码部分就是用来处理同质化活动的工具。它需要具备不错的用户体验的同时可以更快速的搭建与发布，因为在这个时候选择了使用低代码工具 builder.io 作为搭建的平台。

为何不自己搭建的原因有以下几点：

• 占用人力资源多，需要前后端测试等一大批人投入到去从零开发
• 维护成本多，后期维护以及匹配公司活动上需要有设计以及更新
• 前期开发时间和活动快速搭建有冲突

因此选择了使用低代码平台中的 builder.io 来作为搭建平台。只需要考虑怎么把这个低代码平台融入到现有的架构中去即可。

整体架构图 - 技术栈与模块关系

一、 核心系统分层详解

整个架构体系自上而下、自左向右可以划分为五个内聚的模块：

1. 全局服务与底层基建 (Global Services & Infrastructure)

作为整套架构的底层支撑，负责为上层所有的页面和组件提供标准的上下文环境与统一的 UI 容器：

• 全局能力矩阵：
  • 性能监控：负责页面核心性能指标（Web Vitals 等）的采集与上报，保障用户体验。
  • 错误追踪：全局捕获 JS 异常、接口报错及渲染崩溃，提供线上问题的快速定位能力。
  • 主题系统 (CSS 变量)：利用 CSS 变量定义核心色盘，配合 Tailwind CSS 的原子化类名，实现多端皮肤（如深色/浅色、节假日大促主题）的无缝切换。
  • 多语言：为全球化业务提供多语言包的按需加载与动态重水合。
  • SEO 优化：对页面的 TDK (Title, Description, Keywords) 进行动态注入，保障搜索引擎的友好爬取。
• Layout 容器：负责感知设备视口，自适应包裹内部组件，根据业务需求（如大屏/移动端）提供统一的页面骨架布局。

2. 状态管理分层 (State Management)

应对低代码画布中复杂的数据交互流，架构采用了 MobX + Zustand 的双轨驱动模式：

• 全局状态 (MobX - globalStore)：作为重型武器，管理全站级、重交互的核心状态及复杂数据流。
• 轻量配置下发 (Zustand - localPages StoreConfig / SysGlobalConfig)：针对低代码页面内的局部配置、系统全局环境变量以及画布内部组件间的瞬时状态传递，结合 React Hooks 提供更加灵活的状态流转。

3. 数据接入与网络层 (Data Fetching)

统一了静态页面 Schema 的拉取与动态业务数据的交互逻辑：

• 常规接口 (REST API / axios)：负责封装标准的异步接口请求。
• 低代码接入层 (Builder.io SDK)：结合 SDK，在服务端预渲染（SSR）或静态生成（SSG）阶段（如通过 getStaticProps），抓取并注入低代码平台的静态化页面配置。

4. 动态分发与页面路由入口 (Routing & Entrance)

基于 Next.js 的路由机制，实现了从 URL 到可视化页面的动态映射：

• 动态分发中心 (pages/campaigns/[...page].tsx)：利用 Next.js 的通配路由（Catch-all Routes）机制，作为前端页面动态分发的统一入口。
• 视觉解析注入器 (builder-components)：当动态路由捕获到 Builder.io 下发的页面 Schema 后，交由注入器将 JSON 数据深度解析，并映射渲染为真实的 React DOM 节点。

5. 业务组件库 (Business Component Ecosystem)

这是整个低代码系统的“弹药库”，底部的所有模块均是被高度封装的自定义业务组件，供低代码画布调用：

• 交易核心组件：涵盖 fiat-trade (法币交易)、crypto-trade (现货交易)、web3-trade (Web3 交易) 等。
• 活动增长组件：如 competition (交易赛)、regular (常规活动板块)。

二 全链路渲染流程 (Data Flow & Rendering Lifecycle)

一个典型的低代码营销页从请求到渲染，经历以下完整生命周期：

1. 路由捕获：用户发起请求（例如 /campaigns/double-11），Next.js 中间件和动态路由组件拦截请求。
2. Schema 预抓取：在服务端（Server Side），利用 Builder.io SDK 携带当前路由 Key 触发 API 请求，获取该页面的布局和组件配置 JSON。
3. 架构组装与混入：
   • 路由中心解析 JSON 中的组件名称，在 业务组件库 中匹配对应的前端 React 组件（如拉取 competition 核心块）。
   • 将组件配置传递给解析引擎，并在最外层包裹包含多语言、埋点、CSS 变量的 Layout 容器。
4. 服务端渲染 (SSR / SSG)：Next.js 将组装好的组件树转化为高性能的静态 HTML 字符串和数据上下文。
5. 客户端激活 (Hydration)：浏览器接收到 HTML 后进行水合。此时，Zustand 初始化系统配置，MobX 接管并激活动态的交易组件（如账户余额、下单面板），完成静态页面向高交互应用的无缝蜕变。

页面生命周期流程图 - 从请求到渲染

为了更清晰地展示基于 Next.js 与 Builder.io 架构下的页面加载机制，我们通过一张完整的时序图，拆解了用户从发起访问到最终页面可交互的完整生命周期。整个流程主要分为四大核心阶段：服务端构建/抓取、页面下发水合、以及客户端动态渲染。

以用户访问一个典型的活动路由（例如：/zh/campaigns/vip-airdrop）为例，系统的流转链路如下：

1. 初始请求拦截

• 用户发起访问：用户在浏览器中输入或点击链接，向目标路由发起请求。
• 节点拦截：请求首先到达 CDN / Node.js 服务器，触发 Next.js 的页面响应机制。

2. 构建时与服务端抓取阶段 (Build Time / SSG)

在这个阶段，系统主要负责拉取静态布局和全局配置，生成有利于 SEO 且加载极快的静态 HTML：

• 路由匹配 (getStaticPaths)：服务器向 Builder.io 发起请求，获取当前已发布的所有活动页面 Slug 列表，以确定当前访问的路由是否有效。
• 页面 Schema 抓取 (getStaticProps)：命中路由后，服务器再次请求 Builder.io，获取该特定页面的 Content（即低代码可视化块的配置 JSON）和 Metadata。
• 全局数据注入：服务器并行向内部网关（Gate API）请求该页面的多语言包 (i18n)、全局 Header/Footer 配置以及主题 JSON。
• HTML 编译：将上述获取到的组件 Schema 和全局配置融合，在服务端生成包含完整 DOM 结构的静态 HTML 与页面所需的 Props。

3. 运行时下发与客户端水合 (Runtime & Hydration)

• 增量静态生成 (ISR) 下发：CDN/服务器将生成的 HTML 和 JSON Props 响应给浏览器。图中标记了 revalidate: 60s，意味着该页面采用了 Next.js 的 ISR 机制，每 60 秒会在后台重新验证并生成新的缓存，完美兼顾了静态页面的极速响应和页面内容的准实时更新。
• React 水合 (Hydrate)：浏览器接收到静态 HTML 并快速呈现首屏视觉后，React 开始接管页面，绑定事件监听器。
• 状态初始化：
  • MobX 介入：通过 useLocalObservable 初始化全局的 globalStore（如用户信息、全局会话等）。
  • Zustand 介入：初始化 BuilderPageStoreProvider，将服务端下发的局部配置和页面状态注入当前的活动上下文中。

4. 客户端动态渲染与数据刷新 (Client-Side Rendering)

水合完成后，页面进入纯客户端接管阶段，处理动态的、与用户强相关的个性化数据：

• Builder 缓存刷新 (可选 SWR)：前端利用 useSWR 机制，在客户端静默请求 Builder.io 获取最新配置（getBuilderPageInfo），若有更新则无缝替换本地缓存，确保用户停留在页面时也能感知到运营的紧急修改。
• 组件级初始化：解析引擎开始渲染 Builder Schema，将 JSON 映射并初始化提前注册好的自定义 React 组件（Custom Components）。
• 动态业务数据请求：自定义组件内部触发各自的 React Hooks，直接向业务线后端（Gate API）发起 AJAX 请求获取动态数据（例如：当前用户的任务完成进度、实时排行榜等）。
• 响应式更新：接口数据返回后，触发 MobX 或局部状态的更新，observer 包裹的组件感知到状态变化，完成局部的 DOM 重新渲染。

数据流向图 - 状态管理三层结构

在复杂的动态前端应用中，如何优雅地管理服务端下发状态与客户端动态数据，是架构设计的核心挑战。本系统采用了 MobX + Zustand 双轨驱动 的状态管理模式，配合统一的网络基建，实现了从 SSR 水合到客户端静默更新的完整闭环。

整体数据流向由左至右，清晰地划分为三个核心层级与一个统一拦截枢纽：

第一层：全局 SSR 数据流 (基于 MobX)

这一层主要负责处理页面初始化时的重型、全局性状态，确保服务端预渲染的数据能够平滑过渡到客户端。

• 服务端入口 (getServerSideProps)：在 SSR 阶段获取页面的核心基础数据，并将其作为 props 注入。
• 应用级中转 (_app.tsx)：接管初始化的 pageProps，作为数据下发的总线。
• 状态初始化 (globalStore / useLocalObservable)：利用 MobX 的 useLocalObservable 接收服务端下发的数据并完成客户端实例的初始化，使静态数据转变为响应式状态。
• 视图绑定与调用 (Layout & Pages)：通过 MobX 的 observer 高阶组件包裹外层 Layout 及核心 Page，当全局状态（如用户登录态、全局资产）发生变化时，自动触发重渲染；同时，这些组件在生命周期内向下游的统一网络层发起动态接口调用。

第二层：局部动态配置流转 (基于 Zustand)

这一层专门针对 Builder.io 下发的低代码可视化配置，提供轻量、无污染的上下文环境。

• 配置源接入 (Builder 页面动态化)：接收来自低代码平台下发的复杂 JSON 页面配置。
• 局部状态容器 (BuilderPageStoreProvider)：基于 Zustand 构建。它将解析后的 JSON 配置转化为局部状态，并提供 useBuilderPageStore Hook 供内部组件调用。
• 状态透传 (全局单例引用 / 上下文向下透传)：通过 Context 或单例模式，将配置状态精准透传给需要的深层业务组件，避免了 Props Drilling（属性钻取）。
• 业务注入 (X Growth Page Loop 自定义注入)：结合业务逻辑（如增长活动的特定循环或条件渲染），将状态绑定至真实的渲染 DOM 上，并按需向网络层发起交互。

中间枢纽：统一网络与异常接管 (Axios 实例)

所有的组件调用与业务逻辑，其向外的数据请求都会汇聚于此，形成标准化的网关拦截体系。

• 统一请求入口 (axios 实例 src/utils/request)：
  • 请求鉴权：自动在请求头中注入 API 签名校验、token 以及 cookie，随后向后端微服务 (Gate API) 发起真实请求。
  • 统一兜底与错误处理：全局拦截网络异常或业务报错（如接口非 200 或业务 code 异常），向下游输出标准化的 UI 反馈（如 Toast 提示或缺省页）。
  • 前端监控上报 (错误上报)：将捕获到的异常或崩溃日志，通过 @gate/track-pro 及 window.exception 机制自动上报至前端监控平台，形成完整的闭环追踪。

第三层：客户端动态渲染与静默更新

当网络层完成数据交互后，数据回流至视图层，驱动客户端的高频动态更新。

• 业务驱动更新 (usePageStoreConfig)：
  • 组件接收到 API 返回的新数据后，通过状态更新触发 UI 渲染引擎（例如：重新计算并渲染交易赛排行榜、Team 战队信息、个人持仓等）。
  • 基于 React 的 Diff 算法进行条件重染，最终完成页面重新渲染，确保用户看到的业务数据是最新的。
• 静默缓存刷新 (useSWR)：
  • 引入 SWR 机制对 Builder 页面的配置信息（getBuilderPageInfo）进行客户端定时静默更新。
  • 具备完善的 Fallback 策略：对比本地缓存与 API 返回的数据差异，一旦发现运营在后台修改了页面配置，能够利用数据差异触发对应的页面重新渲染，无需用户手动刷新浏览器即可看到最新活动状态。

Builder 组件注册架构 - 按地区分层

在全球化 Web3 与金融交易业务中，由于不同国家和地区的监管政策存在巨大差异（如欧洲的严格合规要求、美国的特定牌照限制等），低代码活动页不能简单地粗暴采用“一套组件打天下”的模式。

本架构图展示了系统如何通过统一入口拦截、环境分支判断与按需注册，实现了一套底层代码库稳健支撑全球多个独立站点的低代码渲染需求，做到了业务组件的“物理级合规隔离”与“性能按需加载”。

核心渲染链路解析

整体的组件注册链路呈清晰的树状/漏斗状分支，从顶部的统一工程入口向下按需分发，最终汇聚于底层的低代码渲染引擎：

1. 统一分发枢纽 (builder-entrance/main/index.ts)

作为所有低代码页面的组件注册总控入口，这里不执行简单的全量引入。相反，请求首先会经过一个核心的环境变量分发器（SUB_WEB 条件分支），用于精准识别当前运行的站点标识和国家环境。

2. 多站点合规隔离层 (Regional & Compliance Isolation)

这是该全球化架构的精髓所在。分发器根据当前的站点环境，动态拉取并注册高度定制化的区域组件：

• Main 版 (主站)：仅注入专供主站主站合规组件，屏蔽不合规的交易玩法。
• EU 版 (欧洲主站)：仅注入专供欧洲市场的欧洲合规组件，屏蔽不合规的交易玩法。
• US 主站版 (美国市场)：根据当地政策，注入深度定制的美版特殊组件。
• 土耳其单独版：针对特定高增长或高本地化需求的国家，注入土耳其定制组件。

架构思考：通过这种懒加载与按需注册的隔离策略，确保了 A 地区的页面绝对无法调用 B 地区的敏感业务组件。即使运营配置出错，只要当前环境的注册表里没有该组件，页面就会安全降级，从根本上杜绝了越权与合规风险。

3. 主站核心业务组件池 (Core Business Components)

对于没有特殊合规限制的通用主站环境，系统会穿透到 main主站 和 _builder-business 目录下，激活庞大的通用业务组件池。这些组件涵盖了丰富的交易与增长生命周期：

• 交易类核心：regional-trade (区域交易模块)、p2p (C2C 法币交易)、pre-market (盘前交易)。
• 高级交易与机构：bot-trade (量化与机器人交易)、agent-trade (代理商专属交易)、institutional (机构大客业务模块)。
• 增长与互动：competition (交易挑战排位赛)、learn (学赚中心)、以及沉淀的 new-style-components (新一代 UI 组件) 和 lite-components (轻量化组件)。

4. 汇聚与引擎接管 (Builder.io SDK & Content Engine)

所有的组件流（无论是主站通用业务还是区域定制模块），最终都将被统一收集并注入到 Builder.io SDK 中进行集中注册。 注册完成后，页面的控制权正式交由最底层的 Content 渲染引擎。当服务端或客户端获取到页面 JSON Schema 时，引擎会在当前环境专属的“安全组件字典”中进行精准比对与映射，最终渲染出符合当地特性的交互 DOM。

模板系统流程 - 非 Builder 静态营销页

在复杂的全球化营销场景中，活动页面的形态千变万化。有的只需简单拼接图片和文案，有的则是高度标准化的交易排位赛，还有的则是诸如“元宵节”这种极具交互特色的一次性定制活动。

为了兼顾开发效率与业务定制深度，系统在最外层的动态路由入口（pages/campaigns）进行了智能分流，构建了三条并行的渲染链路：

链路一：纯低代码动态页面 (Builder 承接)

适用场景：运营主导的常规拉新、促活、公告类页面，无重度定制交互。

• 路由捕获：通过 Next.js 的 Catch-all 路由 pages/campaigns/[...page].tsx 进行无差别拦截。
• 服务端预取 (getStaticProps)：在服务端直接调用 Builder.io API，拉取该路由对应的页面结构与元数据（Metadata）。
• 性能策略：强制开启 60s ISR (增量静态生成) 缓存。保证页面具备纯静态级别的秒开体验，同时允许运营的修改在 1 分钟内全网生效。
• 产物：输出纯粹的 Builder Content Schema 与 SEO 信息，交由底层解析引擎渲染。

链路二：标准化高阶业务模版 (特定路由承接)

适用场景：高度标准化、但内部逻辑极其复杂的重型业务，如“交易竞赛”、“打榜赛”等。这类页面如果完全用低代码配置，由于数据流转太复杂，极易出错。

• 路由分流：分配至专属路由域，如 pages/campaigns/coin/[...page].tsx。
• 业务逻辑与数据层：
  • 在 getStaticProps 阶段，解析 URL 中的活动 ID 或 Slug，向内部后端（Gate API）发起 HTTP 请求拉取活动详情。
  • 将关键活动信息注入为 pageProps.seoConfig，实现精准的动态 SEO 优化。
  • 客户端通过专属的 Custom Hooks（如 useGetActivityInfo, useGetRanking, useSubmitAnswer）利用 Axios 与后端的 REST API 进行高频数据交互。
• UI 视图层 (template/trading-competition)：
  • 提取并封装了高度内聚的交易赛组件池：包括顶部详情 (banner)、任务卡片 (tasks)、规则说明 (rules)、实时排行榜 (ranking) 以及奖品池 (prize)。
  • 这些组件作为“插槽”或“区块”，与上述的数据 Hooks 紧密绑定，形成标准化的页面骨架。

链路三：重度定制化独立模版 (独立路由承接)

适用场景：一次性、强视觉、重交互的节日特色活动（如元宵节猜灯谜、春节集五福等）。

• 路由硬编码：直接建立独立路由，如 pages/campaigns/lantern-festival.tsx。
• 逻辑与 UI 的强解耦：
  • Hooks 层：抽象出抽奖逻辑、奖池拉取逻辑（useGetPrizePool, useDraw）。
  • 组件抽象层：将通用的底层交互 UI（如倒计时弹窗、通用对话框）从页面中剥离。
  • 定制视图层 (template/lantern-festival)：沉淀专属的节日组件库，如“灯谜题目展示区”、“动态抽奖展位”等。
• 统一网关：底层统一汇聚至 Gate API 获取最终的奖品与资金池数据。

主题系统与样式流程 - CSS 变量动态注入

在低代码营销页面的构建中，视觉主题的频繁变更（如：春节、大促、VIP 专属皮肤）是最大的痛点之一。如果采用传统的 CSS 覆盖模式，不仅代码极难维护，还容易引发样式冲突。

本架构图展示了一套以 CSS 变量 (CSS Variables) 为核心，结合服务端预渲染（SSR/SSG）与 Tailwind CSS 的动态主题注入系统。它成功实现了主题配置的后台下发与前端 UI 库的无缝桥接。

核心主题流转机制详解

整个主题系统的渲染链路可以分为“配置解析注入”、“UI 生态同步”与“动态缓存更新”三个核心阶段：

1. 配置解析与全局注入 (Initialization & Injection)

当用户进入页面时，系统会从宏观配置向下提取并注入具体的样式 Token：

• 提取预设标识：页面初始化时，解析 Builder.io styleTemplate 下发的页面大盘配置，获取当前页面的主题预设名称（如：spring、vip、black-gold）。
• 基础注入 (Mantine ThemeProvider)：底层 UI 库 Mantine 的 Provider 捕获这些标识，并在 document.documentElement (即 <html> 标签) 上直接注入顶层 CSS 变量，确立全局的基础样式基调。
• 按需拉取 Token：核心的 LayoutProvider (src/components/layout/provider.tsx) 根据读取到的主题标识，向内部网关（/api/web/v1/builder/themeConfig）发起请求，获取该主题精确的 colors, fonts, spacing 等设计令牌（Design Tokens）。

2. UI 生态协同与 Tailwind 深度融合 (UI Binding & Tailwind)

获取到精确的 CSS 变量字典后，系统需要将其同步给所有的前端 UI 消费者：

• 内部组件库同步：将 Token 数据同步给公司内部的组件库容器 @gate/gui ThemeProvider，将其转化为标准化的 CSS 变量 Map（例如：--primary: #f00, --secondary: #0f0 等）。
• Tailwind 原子化消费：这是整套架构在工程化上的最大亮点。业务开发者在写代码时，直接使用 Tailwind 的任意值语法或扩展配置（如 from-[var(--primary)] 或 bg-primary），直接引用上述生成的 CSS 变量。

架构收益：Tailwind 负责原子化类名的生成，而 CSS 变量负责真实色值的控制。做到了样式结构的静态化与颜色数据的动态化完美解耦。

3. 编辑态与生产环境的动态更新 (Editing & ISR Revalidation)

当运营人员在 Builder.io 可视化编辑器中切换页面主题时：

• 触发更新链路：用户的修改会触发 Next.js 的 getStaticProps 重新执行，去拉取最新的 Theme JSON 配置文件。
• 开发态与生产态双轨处理：
  • API 同步：通过重新调用 /api/web/v1/builder/themeConfig，确保服务端拿到最新的 CSS 变量定义。
  • ISR 延迟生效：对于线上生产环境，基于 Next.js 的 ISR (增量静态生成) 机制，静态页面会在后台进行更新。更新后的全新 HTML（携带着最新的主题 CSS 变量）将在 60秒后正式生效。
• 最终渲染：用户刷新页面即可看到应用了全新 CSS 变量定义 的最终页面 UI。

Conclusion

在这套体系全面落地并支撑了海量活动后，沉淀了以下几个核心的工程化资产与架构思考：

1. 多站点的管理与多项目的迁移

因为这样的低代码对于大部分团队都可以快速实现活动搭建，所以有各种站点或者一些其他团队（web3、Aden）会想要使用，如果快速在其他的项目中可以快速实现部署是一个新的点。

2. 受限与 Builder.io

因为目前使用的是 Builder.io 的 SDK，因为一些接口如果出现波动以及报错，很容易造成大规模活动的瘫痪，需要有一个缓存机制来进行兜底，相信这也是使用第三方 SDK 必须考虑的地方。

未来的演进方向

受限于框架，当时并没有进一步探索 React Server Components (RSC)，将更多静态组件直接在服务端渲染完毕，以追求更极致的客户端 Bundle 缩减；但同时已经在关注 AIGC 结合低代码的可能性，正在尝试 Ui Craft 项目，去通过设计稿 Figma 转 Next 代码，将组建基本结构与样式都快速完成，只需要实现业务逻辑。