미들웨어 API 참조

추가된 버전: astro@2.6.0

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

astro:middleware에서 가져오기

다음 도우미 함수는 가상 미들웨어 모듈에서 가져옵니다.

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

defineMiddleware()

타입: (fn: MiddlewareHandler) => MiddlewareHandler

타입 안전성을 갖춘 미들웨어 함수를 정의하기 위한 함수입니다. 이 유틸리티를 사용하면 context 및 next() 인수에 대한 타입이 자동으로 지정되며, 미들웨어에서 지원되지 않는 값을 반환하려고 하면 TypeScript 오류가 발생합니다.

src/middleware.ts

import { defineMiddleware } from "astro:middleware";

export const onRequest = defineMiddleware((context, next) => {
  /* 미들웨어 로직 */
});

sequence()

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

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

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에서 가져오기

다음 도우미 함수는 Astro 통합을 빌드할 때 일반 미들웨어 모듈에서 가져올 수 있습니다.

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

createContext()

타입: (context: CreateContext) => APIContext

추가된 버전: astro@2.8.0

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

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

defineMiddleware()

astro:middleware의 defineMiddleware()를 확인하세요.

sequence()

astro:middleware의 sequence()를 확인하세요.

trySerializeLocals()

타입: (value: unknown) => string

추가된 버전: astro@2.8.0

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

astro/middleware 타입

다음 타입은 일반 미들웨어 모듈에서 가져옵니다.

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

CreateContext

타입: { request: Request; params?: Params; userDefinedLocales?: string[]; defaultLocale: string; locals: App.Locals; }

추가된 버전: astro@2.8.0

Astro 미들웨어에 전달될 컨텍스트를 생성하는 객체입니다. 이 객체는 다음 속성을 포함합니다.

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

미들웨어에서 임의의 정보를 저장하는 객체로, 사용자는 Astro.locals를 통해 접근할 수 있습니다.

예시 사용법을 통해 locals에 데이터를 저장하는 방법을 자세히 알아보세요.

astro 타입

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

MiddlewareHandler

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

Astro 미들웨어 함수를 나타냅니다. 미들웨어 핸들러는 두 개의 인수를 받으며, Response를 직접 반환하거나 체인의 다음 미들웨어를 호출하기 위해 next()를 호출할 수 있습니다. 또는 defineMiddleware()를 사용하여 미들웨어에 대한 타입 안전성을 확보할 수 있습니다.

다음 예시는 onRequest() 함수에서 타입 안전성을 확보하기 위해 MiddlewareHandler 타입을 가져오는 방법을 보여줍니다.

src/middleware.ts

import type { MiddlewareHandler } from "astro";

export const onRequest: MiddlewareHandler = (context, next) => {
  /* 미들웨어 로직 */
};

미들웨어 핸들러는 다음 속성을 받습니다.

context

타입: APIContext

Astro 전역 속성의 많은 부분을 반영하는 Astro 컨텍스트 객체입니다.

next()

타입: MiddlewareNext

체인에 있는 모든 후속 미들웨어를 호출하고 Response를 반환하는 함수입니다. 예를 들어, 다른 미들웨어가 HTML 본문을 수정했다면 next()의 결과를 기다림으로써 해당 변경사항을 반영한 응답을 만들 수 있습니다.

Astro v4.13.0부터 next()는 문자열, URL, Request 형태의 선택적 URL 경로 매개변수를 받아 새로운 렌더링 단계를 다시 실행하지 않고 현재 요청을 다시 작성할 수 있습니다.

아래 예시는 현재 경로가 /old-path와 일치할 때 next()를 사용하여 다른 경로의 콘텐츠를 제공하는 방법을 보여줍니다.

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() 함수를 나타냅니다.

RewritePayload

타입: string | URL | Request

추가된 버전: astro@4.13.0

next() 함수에 전달될 경우, 리라이트의 목적지를 나타냅니다.

미들웨어 내보내기

프로젝트의 미들웨어를 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();
};