TanStack Router 中 Server Functions 的正确使用方式

在 TanStack Router 项目中，开发者在使用 Server Functions 时可能会遇到一个常见问题：当尝试使用 createServerFn 创建服务器端函数时，系统会抛出错误提示"createServerFn must be called with a function that is marked with the 'use server' pragma"。

问题现象

开发者按照常规思路，可能会在服务器函数中添加"use server"指令，如下所示：

"use server"

export const getCurrentUser = createServerFn()
  .handler(async () => {
    "use server";
    let user = await getAuth(getWebRequest());
    return user?.userId
  });

然而，这种做法反而会导致错误。经过社区讨论和代码分析，发现这实际上是 TanStack Router 的一个特殊设计。

解决方案

正确的做法是完全不需要手动添加任何"use server"指令。TanStack Start 会自动处理这些转换工作。以下是正确的实现方式：

export const getCurrentUser = createServerFn()
  .handler(async () => {
    let user = await getAuth(getWebRequest());
    return user?.userId
  });

技术原理

深入分析 TanStack Router 的源代码可以发现，createServerFn 的实现中有一个特殊检查逻辑。它会自动为函数添加必要的元数据，包括 URL 等信息。当开发者手动添加"use server"指令时，反而会干扰这个自动处理过程。

最佳实践

1. 避免手动添加"use server"指令：让框架自动处理服务器函数的标记
2. 保持函数简洁：直接在 handler 中编写业务逻辑
3. 确保正确配置：检查是否已正确安装和配置了 @tanstack/start-vite-plugin

总结

TanStack Router 的这一设计体现了"约定优于配置"的理念。开发者不需要关心底层的服务器函数标记细节，框架会自动处理这些技术细节，让开发者可以更专注于业务逻辑的实现。这种设计虽然初期可能会让习惯显式标记的开发者感到困惑，但从长期维护和代码简洁性角度来看，是一个值得肯定的设计选择。

对于从其他框架迁移过来的开发者，需要特别注意这一差异，避免将其他框架的使用习惯直接套用到 TanStack Router 中。