tanstack-start-best-practices

TanStack Start 最佳实践

在全栈 React 应用中实现 TanStack Start 模式的综合指南。这些规则涵盖服务端函数、中间件、SSR、身份验证和部署。

适用场景

• 创建用于数据变更的服务端函数
• 设置用于身份验证／日志记录的中间件
• 配置 SSR 和水合
• 实现身份验证流程
• 处理客户端／服务端边界上的错误
• 组织全栈代码
• 部署到各种平台

按优先级划分的规则类别

优先级	类别	规则	影响
CRITICAL	服务端函数	5 条规则	核心数据变更模式
CRITICAL	安全	4 条规则	防止漏洞
HIGH	中间件	4 条规则	请求／响应处理
HIGH	身份验证	4 条规则	安全的用户会话
MEDIUM	API 路由	1 条规则	外部端点模式
MEDIUM	SSR	5 条规则	服务端渲染模式
MEDIUM	错误处理	3 条规则	优雅地处理失败
MEDIUM	环境	1 条规则	配置管理
LOW	文件组织	3 条规则	易于维护的代码结构
LOW	部署	2 条规则	满足生产环境要求

快速参考

服务端函数（前缀：sf-）

• sf-create-server-fn — 使用 createServerFn 编写服务端逻辑
• sf-input-validation — 始终验证服务端函数的输入
• sf-method-selection — 选择适当的 HTTP 方法
• sf-error-handling — 处理服务端函数中的错误
• sf-response-headers — 按需自定义响应头

安全（前缀：sec-）

• sec-validate-inputs — 使用架构验证所有用户输入
• sec-auth-middleware — 使用身份验证中间件保护路由
• sec-sensitive-data — 仅在服务端保留机密信息
• sec-csrf-protection — 为数据变更操作实现 CSRF 防护

中间件（前缀：mw-）

• mw-request-middleware — 使用请求中间件处理横切关注点
• mw-function-middleware — 为服务端函数使用函数中间件
• mw-context-flow — 通过中间件正确传递上下文
• mw-composability — 有效组合中间件

身份验证（前缀：auth-）

• auth-session-management — 实现安全的会话处理
• auth-route-protection — 使用 beforeLoad 保护路由
• auth-server-functions — 在服务端函数中验证身份
• auth-cookie-security — 配置安全的 Cookie 设置

API 路由（前缀：api-）

• api-routes — 为外部使用者创建 API 路由

SSR（前缀：ssr-）

• ssr-data-loading — 以适合 SSR 的方式加载数据
• ssr-hydration-safety — 防止水合不匹配
• ssr-streaming — 实现流式 SSR，以缩短 TTFB
• ssr-selective — 在有益时采用选择性 SSR
• ssr-prerender — 配置静态预渲染和 ISR

环境（前缀：env-）

• env-functions — 使用环境函数进行配置

错误处理（前缀：err-）

• err-server-errors — 处理服务端函数错误
• err-redirects — 合理使用重定向
• err-not-found — 处理未找到的情况

文件组织（前缀：file-）

• file-separation — 分离服务端和客户端代码
• file-functions-file — 使用 .functions.ts 模式
• file-shared-validation — 共享验证架构

部署（前缀：deploy-）

• deploy-env-config — 配置环境变量
• deploy-adapters — 选择适当的部署适配器

使用方法

rules/ 目录中的每个规则文件都包含：

1. 说明 — 此模式为何重要
2. 错误示例 — 应避免的反模式
3. 正确示例 — 推荐的实现方式
4. 上下文 — 何时应用或跳过此规则

完整参考

有关详细指南和代码示例，请参阅 rules/ 目录中的各个规则文件。