中间件

什么是服务端函数中间件？

中间件允许您使用诸如共享验证、上下文等功能来自定义使用 createServerFn 创建的服务端函数的行为。中间件甚至可以依赖其他中间件来创建按层级和顺序执行的操作链。

我可以在服务端函数中间件中做什么？

身份验证：在执行服务端函数之前验证用户身份。
授权：检查用户是否具有执行服务端函数所需的必要权限。
日志记录：记录请求、响应和错误。
可观测性：收集指标、跟踪和日志。
提供上下文：将数据附加到请求对象，以便在其他中间件或服务端函数中使用。
错误处理：以一致的方式处理错误。
还有更多！可能性取决于您！

为服务端函数定义中间件

中间件是使用 createMiddleware 函数定义的。此函数返回一个 Middleware 对象，该对象可用于通过 middleware、validator、server 和 client 等方法继续自定义中间件。

tsx

import { createMiddleware } from '@tanstack/react-start'

const loggingMiddleware = createMiddleware().server(async ({ next, data }) => {
  console.log('Request received:', data)
  const result = await next()
  console.log('Response processed:', result)
  return result
})

import { createMiddleware } from '@tanstack/react-start'

const loggingMiddleware = createMiddleware().server(async ({ next, data }) => {
  console.log('Request received:', data)
  const result = await next()
  console.log('Response processed:', result)
  return result
})

在服务端函数中使用中间件

定义中间件后，您可以将其与 createServerFn 函数结合使用，以自定义服务端函数的行为。

tsx

import { createServerFn } from '@tanstack/react-start'
import { loggingMiddleware } from './middleware'

const fn = createServerFn()
  .middleware([loggingMiddleware])
  .handler(async () => {
    // ...
  })

import { createServerFn } from '@tanstack/react-start'
import { loggingMiddleware } from './middleware'

const fn = createServerFn()
  .middleware([loggingMiddleware])
  .handler(async () => {
    // ...
  })

中间件方法

提供了几种方法来自定义中间件。如果您（希望如此）正在使用 TypeScript，则类型系统会强制执行这些方法的顺序，以确保最大的推断和类型安全。

middleware：向链中添加一个中间件。
validator：在数据对象传递到此中间件和任何嵌套中间件之前修改数据对象。
server：定义服务端逻辑，中间件将在任何嵌套中间件以及最终的服务端函数之前执行该逻辑，并将结果提供给下一个中间件。
client：定义客户端逻辑，中间件将在任何嵌套中间件以及最终的客户端 RPC 函数（或服务端函数）之前执行该逻辑，并将结果提供给下一个中间件。

`validator` 方法

validator 方法用于在数据对象传递到此中间件、嵌套中间件以及最终的服务端函数之前修改数据对象。此方法应接收一个函数，该函数接受数据对象并返回经过验证（和可选修改）的数据对象。通常使用像 zod 这样的验证库来执行此操作。这是一个示例

tsx

import { createMiddleware } from '@tanstack/react-start'
import { zodValidator } from '@tanstack/zod-adapter'
import { z } from 'zod'

const mySchema = z.object({
  workspaceId: z.string(),
})

const workspaceMiddleware = createMiddleware()
  .validator(zodValidator(mySchema))
  .server(({ next, data }) => {
    console.log('Workspace ID:', data.workspaceId)
    return next()
  })

import { createMiddleware } from '@tanstack/react-start'
import { zodValidator } from '@tanstack/zod-adapter'
import { z } from 'zod'

const mySchema = z.object({
  workspaceId: z.string(),
})

const workspaceMiddleware = createMiddleware()
  .validator(zodValidator(mySchema))
  .server(({ next, data }) => {
    console.log('Workspace ID:', data.workspaceId)
    return next()
  })

`server` 方法

server 方法用于定义服务端逻辑，中间件将在任何嵌套中间件以及最终的服务端函数之前和之后执行该逻辑。此方法接收一个具有以下属性的对象

next：一个函数，调用时将执行链中的下一个中间件。
data：传递给服务端函数的数据对象。
context：一个对象，用于存储来自父中间件的数据。可以使用将传递给子中间件的附加数据对其进行扩展。

从 `next` 返回必需的结果

next 函数用于执行链中的下一个中间件。您必须等待并返回（或直接返回）提供给您的 next 函数的结果，以便链继续执行。

tsx

import { createMiddleware } from '@tanstack/react-start'

const loggingMiddleware = createMiddleware().server(async ({ next }) => {
  console.log('Request received')
  const result = await next()
  console.log('Response processed')
  return result
})

import { createMiddleware } from '@tanstack/react-start'

const loggingMiddleware = createMiddleware().server(async ({ next }) => {
  console.log('Request received')
  const result = await next()
  console.log('Response processed')
  return result
})

通过 `next` 为下一个中间件提供上下文

next 函数可以选择使用一个对象调用，该对象具有带有对象值的 context 属性。您传递给此 context 值的任何属性都将合并到父 context 中，并提供给下一个中间件。

tsx

import { createMiddleware } from '@tanstack/react-start'

const awesomeMiddleware = createMiddleware().server(({ next }) => {
  return next({
    context: {
      isAwesome: Math.random() > 0.5,
    },
  })
})

const loggingMiddleware = createMiddleware().server(
  async ({ next, context }) => {
    console.log('Is awesome?', context.isAwesome)
    return next()
  },
)

import { createMiddleware } from '@tanstack/react-start'

const awesomeMiddleware = createMiddleware().server(({ next }) => {
  return next({
    context: {
      isAwesome: Math.random() > 0.5,
    },
  })
})

const loggingMiddleware = createMiddleware().server(
  async ({ next, context }) => {
    console.log('Is awesome?', context.isAwesome)
    return next()
  },
)

客户端逻辑

尽管服务端函数主要是服务端绑定的操作，但客户端发出的 RPC 请求周围仍然有很多客户端逻辑。这意味着我们还可以在中间件中定义客户端逻辑，该逻辑将在客户端执行，围绕任何嵌套的中间件以及最终的 RPC 函数及其对客户端的响应。

客户端负载验证

默认情况下，中间件验证仅在服务器上执行，以保持客户端包大小较小。但是，您也可以选择通过将 validateClient: true 选项传递给 createMiddleware 函数，在客户端验证数据。这将导致数据在发送到服务器之前在客户端进行验证，从而可能节省一次往返行程。

为什么我不能为客户端传递不同的验证模式？

客户端验证模式是从服务端模式派生的。这是因为客户端验证模式用于在数据发送到服务器之前验证数据。如果客户端模式与服务端模式不同，则服务器将接收到它不期望的数据，这可能会导致意外行为。

tsx

import { createMiddleware } from '@tanstack/react-start'
import { zodValidator } from '@tanstack/zod-adapter'
import { z } from 'zod'

const workspaceMiddleware = createMiddleware({ validateClient: true })
  .validator(zodValidator(mySchema))
  .server(({ next, data }) => {
    console.log('Workspace ID:', data.workspaceId)
    return next()
  })

import { createMiddleware } from '@tanstack/react-start'
import { zodValidator } from '@tanstack/zod-adapter'
import { z } from 'zod'

const workspaceMiddleware = createMiddleware({ validateClient: true })
  .validator(zodValidator(mySchema))
  .server(({ next, data }) => {
    console.log('Workspace ID:', data.workspaceId)
    return next()
  })

`client` 方法

客户端中间件逻辑是使用 Middleware 对象上的 client 方法定义的。此方法用于定义客户端逻辑，中间件将在任何嵌套中间件以及最终的客户端 RPC 函数（如果您正在执行 SSR 或从另一个服务端函数调用此函数，则为服务端函数）之前和之后执行该逻辑。

客户端中间件逻辑与使用 server 方法创建的逻辑共享许多相同的 API，但它在客户端执行。 这包括

需要调用 next 函数以继续链。
通过 next 函数为下一个客户端中间件提供上下文的能力。
在数据对象传递到下一个客户端中间件之前修改数据对象的能力。

与服务端函数类似，它也接收一个具有以下属性的对象

next：一个函数，调用时将执行链中的下一个客户端中间件。
data：传递给客户端函数的数据对象。
context：一个对象，用于存储来自父中间件的数据。可以使用将传递给子中间件的附加数据对其进行扩展。

tsx

const loggingMiddleware = createMiddleware().client(async ({ next }) => {
  console.log('Request sent')
  const result = await next()
  console.log('Response received')
  return result
})

const loggingMiddleware = createMiddleware().client(async ({ next }) => {
  console.log('Request sent')
  const result = await next()
  console.log('Response received')
  return result
})

将客户端上下文发送到服务器

默认情况下，客户端上下文不会发送到服务器，因为这可能会最终无意中将大型负载发送到服务器。如果您需要将客户端上下文发送到服务器，则必须使用 sendContext 属性和对象调用 next 函数，以将任何数据传输到服务器。传递给 sendContext 的任何属性都将合并、序列化并与数据一起发送到服务器，并且可以在任何嵌套服务端中间件的普通上下文对象上使用。

tsx

const requestLogger = createMiddleware()
  .client(async ({ next, context }) => {
    return next({
      sendContext: {
        // Send the workspace ID to the server
        workspaceId: context.workspaceId,
      },
    })
  })
  .server(async ({ next, data, context }) => {
    // Woah! We have the workspace ID from the client!
    console.log('Workspace ID:', context.workspaceId)
    return next()
  })

const requestLogger = createMiddleware()
  .client(async ({ next, context }) => {
    return next({
      sendContext: {
        // Send the workspace ID to the server
        workspaceId: context.workspaceId,
      },
    })
  })
  .server(async ({ next, data, context }) => {
    // Woah! We have the workspace ID from the client!
    console.log('Workspace ID:', context.workspaceId)
    return next()
  })

客户端发送的上下文安全

您可能已经注意到，在上面的示例中，虽然客户端发送的上下文是类型安全的，但不需要在运行时进行验证。如果您通过上下文传递动态用户生成的数据，这可能会构成安全问题，因此，如果您通过上下文将动态数据从客户端发送到服务器，则应在服务端中间件中验证后再使用它。这是一个示例。

tsx

import { zodValidator } from '@tanstack/zod-adapter'
import { z } from 'zod'

const requestLogger = createMiddleware()
  .client(async ({ next, context }) => {
    return next({
      sendContext: {
        workspaceId: context.workspaceId,
      },
    })
  })
  .server(async ({ next, data, context }) => {
    // Validate the workspace ID before using it
    const workspaceId = zodValidator(z.number()).parse(context.workspaceId)
    console.log('Workspace ID:', workspaceId)
    return next()
  })

import { zodValidator } from '@tanstack/zod-adapter'
import { z } from 'zod'

const requestLogger = createMiddleware()
  .client(async ({ next, context }) => {
    return next({
      sendContext: {
        workspaceId: context.workspaceId,
      },
    })
  })
  .server(async ({ next, data, context }) => {
    // Validate the workspace ID before using it
    const workspaceId = zodValidator(z.number()).parse(context.workspaceId)
    console.log('Workspace ID:', workspaceId)
    return next()
  })

与将客户端上下文发送到服务器类似，您也可以通过使用 sendContext 属性和对象调用 next 函数来将服务端上下文发送到客户端，以将任何数据传输到客户端。传递给 sendContext 的任何属性都将合并、序列化并与响应一起发送到客户端，并且可以在任何嵌套客户端中间件的普通上下文对象上使用。在 client 中调用 next 返回的对象包含从服务器发送到客户端的上下文，并且是类型安全的。中间件能够从 middleware 函数链接的前一个中间件推断出从服务器发送到客户端的上下文。

警告

client 中 next 的返回类型只能从当前中间件链中已知的中间件推断出来。因此，next 最准确的返回类型位于中间件链末端的中间件中。

tsx

const serverTimer = createMiddleware().server(async ({ next }) => {
  return next({
    sendContext: {
      // Send the current time to the client
      timeFromServer: new Date(),
    },
  })
})

const requestLogger = createMiddleware()
  .middleware([serverTimer])
  .client(async ({ next }) => {
    const result = await next()
    // Woah! We have the time from the server!
    console.log('Time from the server:', result.context.timeFromServer)

    return result
  })

const serverTimer = createMiddleware().server(async ({ next }) => {
  return next({
    sendContext: {
      // Send the current time to the client
      timeFromServer: new Date(),
    },
  })
})

const requestLogger = createMiddleware()
  .middleware([serverTimer])
  .client(async ({ next }) => {
    const result = await next()
    // Woah! We have the time from the server!
    console.log('Time from the server:', result.context.timeFromServer)

    return result
  })

读取/修改服务端响应

使用 server 方法的中间件与服务端函数在相同的上下文中执行，因此您可以遵循完全相同的服务端函数上下文实用程序来读取和修改有关请求标头、状态代码等的任何内容。

修改客户端请求

使用 client 方法的中间件在与服务端函数完全不同的客户端上下文中执行，因此您不能使用相同的实用程序来读取和修改请求。但是，在调用 next 函数时，您仍然可以修改请求以返回其他属性。当前支持的属性是

headers：一个包含要添加到请求的标头的对象。

这是一个示例，说明如何使用此中间件为任何请求添加 Authorization 标头

tsx

import { getToken } from 'my-auth-library'

const authMiddleware = createMiddleware().client(async ({ next }) => {
  return next({
    headers: {
      Authorization: `Bearer ${getToken()}`,
    },
  })
})

import { getToken } from 'my-auth-library'

const authMiddleware = createMiddleware().client(async ({ next }) => {
  return next({
    headers: {
      Authorization: `Bearer ${getToken()}`,
    },
  })
})

使用中间件

中间件可以通过两种不同的方式使用

全局中间件：应该为每个请求执行的中间件。
服务端函数中间件：应该为特定服务端函数执行的中间件。

全局中间件

全局中间件在应用程序中的每个服务端函数上自动运行。这对于应应用于所有请求的功能（如身份验证、日志记录和监视）非常有用。

要使用全局中间件，请在您的项目中创建一个 global-middleware.ts 文件（通常位于 app/global-middleware.ts）。此文件在客户端和服务器环境中运行，您可以在其中注册全局中间件。

这是如何注册全局中间件

tsx

// app/global-middleware.ts
import { registerGlobalMiddleware } from '@tanstack/react-start'
import { authMiddleware } from './middleware'

registerGlobalMiddleware({
  middleware: [authMiddleware],
})

// app/global-middleware.ts
import { registerGlobalMiddleware } from '@tanstack/react-start'
import { authMiddleware } from './middleware'

registerGlobalMiddleware({
  middleware: [authMiddleware],
})

全局中间件类型安全

全局中间件类型本质上与服务端函数本身分离。这意味着，如果全局中间件为服务端函数或其他服务端函数特定中间件提供额外的上下文，则类型不会自动传递到服务端函数或其他服务端函数特定中间件。

tsx

// app/global-middleware.ts
registerGlobalMiddleware({
  middleware: [authMiddleware],
})

// app/global-middleware.ts
registerGlobalMiddleware({
  middleware: [authMiddleware],
})

tsx

// authMiddleware.ts
const authMiddleware = createMiddleware().server(({ next, context }) => {
  console.log(context.user) // <-- This will not be typed!
  // ...
})

// authMiddleware.ts
const authMiddleware = createMiddleware().server(({ next, context }) => {
  console.log(context.user) // <-- This will not be typed!
  // ...
})

为了解决这个问题，请将您尝试引用的全局中间件添加到服务端函数的中间件数组中。全局中间件将被去重为一个条目（全局实例），并且您的服务端函数将接收到正确的类型。

这是一个关于其工作原理的示例

tsx

import { authMiddleware } from './authMiddleware'

const fn = createServerFn()
  .middleware([authMiddleware])
  .handler(async ({ context }) => {
    console.log(context.user)
    // ...
  })

import { authMiddleware } from './authMiddleware'

const fn = createServerFn()
  .middleware([authMiddleware])
  .handler(async ({ context }) => {
    console.log(context.user)
    // ...
  })

中间件执行顺序

中间件首先按依赖关系执行，从全局中间件开始，然后是服务端函数中间件。以下示例将按此顺序记录以下内容

globalMiddleware1
globalMiddleware2
a
b
c
d

tsx

const globalMiddleware1 = createMiddleware().server(async ({ next }) => {
  console.log('globalMiddleware1')
  return next()
})

const globalMiddleware2 = createMiddleware().server(async ({ next }) => {
  console.log('globalMiddleware2')
  return next()
})

registerGlobalMiddleware({
  middleware: [globalMiddleware1, globalMiddleware2],
})

const a = createMiddleware().server(async ({ next }) => {
  console.log('a')
  return next()
})

const b = createMiddleware()
  .middleware([a])
  .server(async ({ next }) => {
    console.log('b')
    return next()
  })

const c = createMiddleware()
  .middleware()
  .server(async ({ next }) => {
    console.log('c')
    return next()
  })

const d = createMiddleware()
  .middleware([b, c])
  .server(async () => {
    console.log('d')
  })

const fn = createServerFn()
  .middleware([d])
  .server(async () => {
    console.log('fn')
  })

const globalMiddleware1 = createMiddleware().server(async ({ next }) => {
  console.log('globalMiddleware1')
  return next()
})

const globalMiddleware2 = createMiddleware().server(async ({ next }) => {
  console.log('globalMiddleware2')
  return next()
})

registerGlobalMiddleware({
  middleware: [globalMiddleware1, globalMiddleware2],
})

const a = createMiddleware().server(async ({ next }) => {
  console.log('a')
  return next()
})

const b = createMiddleware()
  .middleware([a])
  .server(async ({ next }) => {
    console.log('b')
    return next()
  })

const c = createMiddleware()
  .middleware()
  .server(async ({ next }) => {
    console.log('c')
    return next()
  })

const d = createMiddleware()
  .middleware([b, c])
  .server(async () => {
    console.log('d')
  })

const fn = createServerFn()
  .middleware([d])
  .server(async () => {
    console.log('fn')
  })

环境 Tree Shaking

中间件功能基于为每个生成的 bundle 的环境进行 tree-shaking。

在服务器上，不会进行 tree-shaking，因此中间件中使用的所有代码都将包含在服务器 bundle 中。
在客户端上，所有特定于服务器的代码都将从客户端 bundle 中删除。这意味着 server 方法中使用的任何代码始终从客户端 bundle 中删除。如果 validateClient 设置为 true，则客户端验证代码将包含在客户端 bundle 中，否则数据验证代码也将被删除。

什么是服务端函数中间件？

我可以在服务端函数中间件中做什么？

为服务端函数定义中间件

在服务端函数中使用中间件

中间件方法

`middleware` 方法

`validator` 方法

`server` 方法

从 `next` 返回必需的结果

通过 `next` 为下一个中间件提供上下文

客户端逻辑

客户端负载验证

`client` 方法

将客户端上下文发送到服务器

客户端发送的上下文安全

将服务端上下文发送到客户端

读取/修改服务端响应

修改客户端请求

使用中间件

全局中间件

全局中间件类型安全

中间件执行顺序

环境 Tree Shaking

订阅 Bytes

订阅 Bytes

中间件

什么是服务端函数中间件？

我可以在服务端函数中间件中做什么？

为服务端函数定义中间件

在服务端函数中使用中间件

中间件方法

middleware 方法

validator 方法

server 方法

从 next 返回必需的结果

通过 next 为下一个中间件提供上下文

客户端逻辑

客户端负载验证

client 方法

将客户端上下文发送到服务器

客户端发送的上下文安全

将服务端上下文发送到客户端

读取/修改服务端响应

修改客户端请求

使用中间件

全局中间件

全局中间件类型安全

中间件执行顺序

环境 Tree Shaking

订阅 Bytes

订阅 Bytes

`middleware` 方法

`validator` 方法

`server` 方法

从 `next` 返回必需的结果

通过 `next` 为下一个中间件提供上下文

`client` 方法