SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场start-execution-model

start-execution-model

编程与开发

查看项目

更新于 10-26 16:21

技能介绍

用途

该技能面向使用 TanStack Start（目标 @tanstack/react-start v1.168.58）的开发者，用于回答“这段代码在哪里运行”这一核心问题。资料称这是 Start 中最重要的概念，也是 AI 生成代码缺陷的首要来源。适用场景包括：决定放置服务端或客户端逻辑、修复密钥泄漏、修复在 loader 中直接访问数据库的问题、以及解决水合不匹配。

核心规则

资料强调三条关键规则：

  • 默认同构：每个模块同时进入服务端与客户端 bundle，route loader 在 SSR 和客户端导航时都会运行；数据库、文件系统与密钥必须放在 createServerFn（或 createServerOnlyFn）内，不能放在裸 loader 或模块作用域。
  • 按请求读取环境变量：process.env 不应在模块作用域读取，因为模块级读取可能被内联进客户端 bundle（导致泄漏），且在请求时注入环境变量的边缘运行时上为 undefined。
  • 前缀暴露风险：带 VITE_/PUBLIC_ 前缀的变量会暴露给客户端，服务端密钥不得带此类前缀。

边界 API 速查

资料给出以下 API 及其客户端/服务端行为：

  • createServerFn()：用于 RPC、数据与变更；客户端发起网络请求，服务端直接执行。
  • createServerOnlyFn(fn)：服务端工具函数；客户端调用抛错，服务端直接执行。
  • createClientOnlyFn(fn)：浏览器工具函数；客户端直接执行，服务端抛错。
  • createIsomorphicFn()：按环境提供实现，客户端用 .client() 实现，服务端用 .server() 实现。
  • <ClientOnly fallback>：仅浏览器 UI；客户端渲染子节点，服务端渲染 fallback。
  • useHydrated()：水合后逻辑；客户端水合后为 true，服务端为 false。
  • import '@tanstack/react-start/server-only'：整文件仅服务端；客户端导入被拒绝。
  • import '@tanstack/react-start/client-only'：整文件仅客户端；服务端导入被拒绝。

边界创建函数均从 @tanstack/react-start 导入；<ClientOnly> 与 useHydrated 来自 @tanstack/react-router。

典型示例

错误写法是在 createFileRoute 的 loader 中直接读取 process.env.API_SECRET 并发起请求，因为 loader 是同构的，密钥会进入浏览器。正确写法是将逻辑封装为 createServerFn({ method: 'GET' }).handler(async () => {...})，在 handler 内读取密钥，loader 只调用该函数。

决策框架

  • 仅服务端（createServerFn / createServerOnlyFn）：密钥、数据库、文件系统、外部 API 密钥。
  • 仅客户端（createClientOnlyFn / <ClientOnly>）：DOM、localStorage、地理位置、分析统计。
  • 同构（默认 / createIsomorphicFn）：格式化、业务逻辑、共享工具、loader。

禁止做法

  • 在裸 loader 中使用数据库、密钥或文件系统（应改用 createServerFn）。
  • 在模块作用域读取 process.env（泄漏风险，且在边缘运行时为 undefined）。
  • 给密钥加 VITE_/PUBLIC_ 前缀。
  • 非确定性渲染输出（如直接使用 new Date()），会导致水合不匹配。
  • 对 *.functions.ts 服务端函数使用动态 import()（存在打包器问题）。

参考文档与工作流

资料列出参考文件：references/isomorphic-by-default.md（同构原因与心智模型）、references/environment-boundaries.md（各边界 API、导入标记及选择）、references/environment-variables.md（VITE_/PUBLIC_ 与 process.env、按请求读取、运行时变量）、references/templates/boundaries.md（各类边界完整可复制示例）。资料还要求：在编写边界代码前用 Context7 与 Exa 核验 API，修改后运行 fuse-ai-pilot:sniper。

限制

资料明确该技能不用于初始项目搭建（应使用 start-core），也不用于文件与目录的 SOLID 组织（应使用 solid-tanstack-start）。价格、付费方式、平台支持等信息暂未提供。