Справочник API Middleware (Мидлвар)

Добавлено в: astro@2.6.0

Middleware (мидлвар) позволяет перехватывать запросы и ответы и динамически внедрять поведение каждый раз, когда страница или эндпоинт готовы к рендерингу. О функциях и примерах использования читайте в нашем руководстве по middleware.

Импорт из astro:middleware

Следующие помощники импортируются из виртуального модуля middleware:

import {
  defineMiddleware,
  sequence,
} from 'astro:middleware';

defineMiddleware()

Тип: (fn: MiddlewareHandler) => MiddlewareHandler

Функция для определения функции middleware с типобезопасностью. Когда вы используете эту утилиту, аргументы context и next() автоматически типизируются, и вы получите ошибку Typescript, если попытаетесь вернуть значение, не поддерживаемое в вашем middleware.

src/middleware.ts

import { defineMiddleware } from "astro:middleware";

export const onRequest = defineMiddleware((context, next) => {
  /* логика вашего middleware */
});

sequence()

Тип: (…handlers: MiddlewareHandler[]) => MiddlewareHandler

Функция, которая принимает функции middleware в качестве аргументов и выполняет их в том порядке, в котором они были переданы.

src/middleware.js

import { sequence } from "astro:middleware";

async function validation(context, next) {/* ... */}
async function auth(context, next) {/* ... */}
async function greeting(context, next) {/* ... */}

export const onRequest = sequence(validation, auth, greeting);

Импорт из astro/middleware

Следующие помощники могут быть импортированы из обычного модуля middleware при создании интеграции Astro:

import {
  createContext,
  defineMiddleware,
  sequence,
  trySerializeLocals,
} from "astro/middleware";

createContext()

Тип: (context: CreateContext) => APIContext

Добавлено в: astro@2.8.0

Низкоуровневый API для создания APIContext, который передается в функцию Astro middleware onRequest().

Эта функция может использоваться интеграциями/адаптерами для программного выполнения middleware Astro.

defineMiddleware()

Смотрите defineMiddleware() из astro:middleware.

sequence()

Смотрите sequence() из astro:middleware.

trySerializeLocals()

Тип: (value: unknown) => string

Добавлено в: astro@2.8.0

Низкоуровневый API, который принимает любое значение и пытается вернуть его сериализованную версию (строку). Если значение не может быть сериализовано, функция выбросит ошибку времени выполнения.

Типы astro/middleware

Следующие типы импортируются из обычного модуля middleware:

import type {
  CreateContext,
} from "astro/middleware";

CreateContext

Тип: { request: Request; params?: Params; userDefinedLocales?: string[]; defaultLocale: string; locals: App.Locals; }

Добавлено в: astro@2.8.0

Объект для создания контекста, который будет передан в Astro middleware. Содержит следующие свойства:

request

Тип: Request

Входящий объект Request.

params

Тип: Params

Объект, содержащий необязательные параметры, которые будут переданы в Astro.params.

userDefinedLocales

Тип: string[]

Добавлено в: astro@3.5.0

Список поддерживаемых локалей, определенных в конфигурации i18n пользователя.

defaultLocale

Тип: string

Добавлено в: astro@4.16.0

Локаль по умолчанию, определенная в конфигурации i18n пользователя.

locals

Тип: App.Locals

Добавлено в: astro@5.0.0

Объект для хранения произвольной информации из middleware, доступный пользователю через Astro.locals.

Узнайте больше о хранении данных в locals с примером использования.

Типы astro

import type {
  MiddlewareHandler,
  MiddlewareNext,
  RewritePayload,
} from "astro";

MiddlewareHandler

Тип: (context: APIContext, next: MiddlewareNext) => Promise<Response> | Response | Promise<void> | void

Представляет функцию middleware Astro. Обработчики middleware получают два аргумента и могут либо вернуть Response напрямую, либо вызвать next() для вызова следующего middleware в цепочке. В качестве альтернативы вы можете использовать defineMiddleware() для получения типобезопасности для вашего middleware.

Следующий пример импортирует тип MiddlewareHandler для получения типобезопасности в функции onRequest():

src/middleware.ts

import type { MiddlewareHandler } from "astro";

export const onRequest: MiddlewareHandler = (context, next) => {
  /* логика middleware */
};

Обработчик middleware получает следующие свойства:

context

Тип: APIContext

Объект контекста Astro, зеркалирующий многие глобальные свойства Astro.

next()

Тип: MiddlewareNext

Функция, которая вызывает все последующие middleware в цепочке и возвращает Response. Например, другие middleware могут изменить HTML-тело ответа, и ожидание результата next() позволит вашему middleware отреагировать на эти изменения.

Начиная с Astro v4.13.0, next() принимает необязательный параметр пути URL в виде строки, URL или Request для перезаписи (rewrite) текущего запроса без повторного запуска новой фазы рендеринга.

Следующий пример использует next() для обслуживания контента из другого пути, когда текущий путь совпадает с /old-path:

src/middleware.ts

import type { MiddlewareHandler } from "astro";

export const onRequest: MiddlewareHandler = (context, next) => {
  if (context.url.pathname === '/old-path') {
    return next('/new-path');
  }
  return next();
};

MiddlewareNext

Тип: (rewritePayload?: RewritePayload) => Promise<Response>

Представляет функцию next(), передаваемую в обработчики middleware.

RewritePayload

Тип: string | URL | Request

Добавлено в: astro@4.13.0

Представляет назначение для перезаписи (rewrite) при передаче в функцию next().

Экспорты middleware

При определении middleware вашего проекта в src/middleware.js экспортируйте следующие определенные пользователем функции:

onRequest()

Тип: MiddlewareHandler

Обязательная экспортируемая функция из src/middleware.js, которая будет вызываться перед рендерингом каждой страницы или маршрута API. Она получает два аргумента: context и next(). onRequest() должна возвращать Response: либо напрямую, либо вызывая next().

src/middleware.js

export function onRequest (context, next) {
  // перехват данных ответа из запроса
  // опционально, трансформация ответа
  // возврат Response напрямую или результата вызова `next()`
  return next();
};