Referencia de la API de enrutamiento de búsquedas

Agregado en: astro@7.0.0

El módulo astro/fetch ofrece controladores de enrutamiento avanzado basados en la API estándar de búsqueda.

Importaciones desde astro/fetch

import {
  FetchState,
  astro,
  cache,
  i18n,
  middleware,
  notFound,
  pages,
  redirects,
  sessions,
  trailingSlash,
} from 'astro/fetch';

FetchState

El objeto de estado por solicitud. Crea uno al inicio de tu método fetch:

src/fetch.ts

import { FetchState } from 'astro/fetch';

export default {
  async fetch(request: Request): Promise<Response> {
    const state = new FetchState(request);
    // Tu lógica de enrutamiento avanzado...
  },
};

FetchState registra la ruta coincidente, las cookies, los proveedores de sesión y otros datos específicos de cada solicitud. Todas las funciones de control lo requieren como primer argumento.

Aprende a componer controladores con FetchState en la guía de enrutamiento avanzado.

Propiedades

state.request

Tipo: Request

El objeto Request entrante.

state.url

Tipo: URL

Una URL normalizada derivada de la solicitud.

state.pathname

Tipo: string

La ruta de la solicitud sin la base y descodificada (p. ej., /sobre-mí o /blog/mi-artículo).

state.routeData

Tipo: RouteData | undefined

La ruta coincidente para esta solicitud, si la hay. Esto se resuelve automáticamente al crear el FetchState.

state.cookies

Tipo: AstroCookies

Una instancia de AstroCookies (EN) para leer y configurar cookies en esta solicitud.

state.locals

Tipo: App.Locals

Un objeto con ámbito de solicitud para almacenar datos personalizados. Se trata del mismo objeto locals (EN) disponible en middleware (EN) y en rutas de la API (EN).

state.params

Tipo: Params | undefined

Parámetros de ruta derivados de la ruta y el nombre de ruta coincidentes (p. ej., { slug: 'mi-artículo' }). undefined cuando la ruta no coincide o no tiene parámetros.

state.session

Tipo: AstroSession | undefined

El objeto de sesión para esta solicitud. Solo está disponible después de llamar al controlador sessions().

astro()

Tipo: (state: FetchState) => Promise<Response>

El controlador de enrutamiento predeterminado. Gestiona la caché, las redirecciones, las barras diagonales finales, la internacionalización, las sesiones y el renderizado en el orden estándar de Astro:

src/fetch.ts

import { FetchState, astro } from 'astro/fetch';

export default {
  async fetch(request: Request): Promise<Response> {
    const state = new FetchState(request);
    return astro(state);
  },
};

astro() equivale a encadenar manualmente todos los controladores individuales en el orden recomendado. Usa controladores individuales cuando necesites insertar lógica personalizada entre los pasos de enrutamiento.

cache()

Tipo: (state: FetchState) => Promise<Response> | undefined

Comprueba si la solicitud entrante puede ser atendida por la caché. Si es así, devuelve una Response en caché. Si la ruta es dinámica o la página no está en caché, devuelve undefined.

i18n()

Tipo: (state: FetchState) => Promise<Response> | undefined

Gestiona la redirección y el enrutamiento i18n (EN). Devuelve una respuesta de redirección si la solicitud coincide con una regla de redirección de idioma (p. ej., redirigir a un prefijo de idioma predeterminado), o undefined si el procesamiento de la solicitud debe continuar. Llama a esta función al principio de tu pipeline (después de cache()):

src/fetch.ts

import { FetchState, i18n } from 'astro/fetch';

export default {
  async fetch(request: Request): Promise<Response> {
    const state = new FetchState(request);
    const redirect = await i18n(state);
    if (redirect) return redirect;
    // ...resto del pipeline...
  },
};

middleware()

Tipo: (state: FetchState, next: (state: FetchState) => Promise<Response>) => Promise<Response>

Ejecuta el middleware (EN) del proyecto. Acepta la función FetchState y una función next que se llama con el estado (potencialmente modificado) para continuar con el pipeline. Normalmente, envolverías pages(state):

src/fetch.ts

import { FetchState, middleware, pages } from 'astro/fetch';

export default {
  async fetch(request: Request): Promise<Response> {
    const state = new FetchState(request);
    const response = await middleware(state, (s) => pages(s));
    return response;
  },
};

notFound()

Tipo: (state: FetchState) => Promise<Response> | undefined

Agregado en: astro@7.4.0 Nuevo

Renderiza tu página 404 personalizada, incluyendo un 404.astro prerenderizado, cuando ninguna ruta coincide. Esto devuelve undefined para una ruta coincidente o una respuesta 400 vacía para una ruta de solicitud con codificación excesiva. La función que la invoca puede decidir entonces si continuar con el procesamiento.

astro() ya incluye este manejo. Cuando compongas controladores individuales en su lugar, añade notFound() antes de middleware() y pages() para renderizar la página 404 para rutas no coincidentes:

src/fetch.ts

import { FetchState, middleware, notFound, pages } from 'astro/fetch';

export default {
  async fetch(request: Request): Promise<Response> {
    const state = new FetchState(request);
    const notFoundResponse = await notFound(state);
    if (notFoundResponse) return notFoundResponse;
    return middleware(state, (s) => pages(s));
  },
};

pages()

Tipo: (state: FetchState) => Promise<Response>

Envía la solicitud a la ruta de Astro correspondiente (página, endpoint o fallback). Este es el controlador de renderizado principal, y la mayoría de los pipelines personalizados lo incluirán.

Añade notFound() antes de pages() para renderizar tu página 404 personalizada para rutas no coincidentes.

redirects()

Tipo: (state: FetchState) => Promise<Response> | undefined

Gestiona las rutas de redirección definidas en tu configuración de Astro (EN). Devuelve una Response de redirección si la ruta coincidente es una redirección, o undefined si la función que la invoca debe continuar con el procesamiento.

sessions()

Tipo: (state: FetchState) => Promise<void> | void

Registra el proveedor de una sesión. Las sesiones se crean de forma diferida cuando tu código accede a ctx.session y se guardan automáticamente al final de la solicitud. Llama a esta función al principio del pipeline (antes de que se ejecute el middleware):

src/fetch.ts

import { FetchState, sessions } from 'astro/fetch';

export default {
  async fetch(request: Request): Promise<Response> {
    const state = new FetchState(request);
    await sessions(state);
    // ...pipeline de renderizado...
  },
};

Este controlador no registra ningún proveedor cuando no hay ningún controlador de sesión configurado, o cuando las sesiones están deshabilitadas. En ambos casos, ctx.session será undefined.

trailingSlash()

Tipo: (state: FetchState) => Response | undefined

Comprueba si la ruta de la solicitud necesita normalización con barra final (EN) y, en caso afirmativo, devuelve una Response de redireccionamiento. Devuelve undefined cuando no es necesario ningún redireccionamiento.