미들웨어 API 참조

Added in: astro@2.6.0

미들웨어를 사용하면 페이지나 엔드포인트가 렌더링될 때마다 요청과 응답을 가로채고 동작을 동적으로 주입할 수 있습니다. 기능 및 사용 예시는 미들웨어 가이드를 확인하세요.

astro:middleware에서 가져오기

섹션 제목: astro:middleware에서 가져오기

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

defineMiddleware()

섹션 제목: defineMiddleware()

타입 안전성을 활용하기 위해 유틸리티 함수 defineMiddleware()를 가져와 사용할 수 있습니다:

src/middleware.ts

import { defineMiddleware } from "astro:middleware";

// `context` 및 `next`의 타입이 자동으로 설정됩니다.
export const onRequest = defineMiddleware((context, next) => {

});

sequence()

섹션 제목: sequence()

타입: (...handlers: MiddlewareHandler[]) => MiddlewareHandler

미들웨어 함수를 인수로 받아 전달된 순서대로 실행하는 함수입니다.

src/middleware.js

import { sequence } from "astro:middleware";

async function validation(_, next) {...}
async function auth(_, next) {...}
async function greeting(_, next) {...}

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

createContext()

섹션 제목: createContext()

타입: (context: CreateContext) => APIContext

Added in: astro@2.8.0

Astro 미들웨어 onRequest() 함수에 전달될 APIContext를 생성하는 저수준 API입니다.

이 함수는 Astro 미들웨어를 프로그래밍 방식으로 실행하기 위해 통합/어댑터에서 사용할 수 있습니다.

trySerializeLocals()

섹션 제목: trySerializeLocals()

타입: (value: unknown) => string

Added in: astro@2.8.0

모든 값을 받아들여 해당 값의 직렬화된 버전 (문자열)을 반환하려고 시도하는 저수준 API입니다. 값을 직렬화할 수 없으면 함수에서 런타임 오류가 발생합니다.

미들웨어 내보내기

섹션 제목: 미들웨어 내보내기

프로젝트의 미들웨어를 src/middleware.js에서 정의할 때, 다음 사용자 정의 함수를 내보내세요:

onRequest()

섹션 제목: onRequest()

타입: (context: APIContext, next: MiddlewareNext) => Promise<Response> | Response | Promise<void> | void

모든 페이지 또는 API 경로를 렌더링하기 전에 호출되는 src/middleware.js에서 내보낸 필수 함수입니다. 두 개의 인수 context 및 next()를 전달받습니다. onRequest()는 Response를 직접 반환하거나 next()를 호출하여 반환해야 합니다.

src/middleware.js

export function onRequest (context, next) {
    // 요청의 응답 데이터를 가로챕니다.
    // 선택적으로 응답을 변환합니다.
    // Response를 직접 반환하거나 `next()` 호출 결과를 반환합니다.
    return next();
};

onRequest() 함수는 다음 인자를 전달받아 호출됩니다.

context

섹션 제목: context

타입: APIContext

onRequest()의 첫 번째 인수는 컨텍스트 객체입니다. 이는 많은 Astro 전역 프로퍼티를 반영합니다.

컨텍스트 객체에 대해 더 자세히 알아보기 위해 엔드포인트 컨텍스트를 방문하세요.

next()

섹션 제목: next()

타입: (rewritePayload?: string | URL | Request) => Promise<Response>

onRequest()의 두 번째 인수는 체인의 모든 후속 미들웨어를 호출하고 Response를 반환하는 함수입니다. 예를 들어, 다른 미들웨어가 응답의 HTML 본문을 수정할 수 있으며 next()의 결과를 기다리면 미들웨어가 이러한 변경 사항에 응답할 수 있습니다.

Astro v4.13.0부터 next()는 새 렌더링 단계를 다시 트리거하지 않고 현재 요청을 리라이트하기 위해 문자열 형식의 선택적 URL 경로 매개 변수인 URL 또는 Request를 허용합니다.