미들웨어

미들웨어를 사용하면 페이지나 엔드포인트가 렌더링될 때마다 요청과 응답을 가로채고 동작을 동적으로 추가할 수 있습니다. 이 렌더링은 사전 렌더링된 모든 페이지에 대해서는 빌드 시 발생하지만 요청 시 렌더링되는 페이지에 대해서는 경로가 요청될 때 발생합니다.

또한 미들웨어를 사용하면 모든 Astro 컴포넌트 및 API 엔드포인트에서 사용할 수 있는 locals 객체를 변경하여 엔드포인트와 페이지 전반에 걸쳐 요청별 정보를 설정하고 공유할 수 있습니다. 이 객체는 빌드 시 이 미들웨어가 실행되는 경우에도 사용할 수 있습니다.

사용 방법

src/middleware.js|ts 파일을 생성합니다. (또는 src/middleware/index.js|ts 파일을 생성할 수도 있습니다.)

이 파일에서 context 객체와 next() 함수를 전달할 수 있는 onRequest() 함수를 내보냅니다. 이는 기본 내보내기가 아니어야 합니다.

export function onRequest ({ locals, request }, next) {
    // 요청의 응답 데이터 가로채기
    // 선택적으로 `locals`의 속성을 수정합니다.
    locals.title = "새로운 제목";

    // Response 객체 또는 `next()` 함수의 호출 결과를 반환합니다.
    return next();
};

.astro 파일에서 Astro.locals를 통해 응답 데이터를 사용합니다.

---
const data = Astro.locals;
---
<h1>{data.title}</h1>
<p>{data.property} 속성은 미들웨어로부터 전달되었습니다.</p>

`context` 객체

context 객체에는 렌더링 프로세스 중 다른 미들웨어, API 경로 및 .astro 경로에 사용할 수 있는 정보가 포함되어 있습니다.

이는 onRequest()에 전달되는 선택적 인수로, 렌더링 중 공유할 추가 속성과 locals 객체를 포함할 수 있습니다. 예를 들어, context 객체에는 인증에 사용되는 쿠키가 포함될 수 있습니다.

`context.locals`에 데이터 저장

context.locals는 미들웨어에서 조작할 수 있는 객체입니다.

이 locals 객체는 요청 처리 프로세스를 통해 전달되며 APIContext 및 AstroGlobal에 대한 속성으로 사용할 수 있습니다. 이를 통해 미들웨어, API 경로 및 .astro 페이지 간에 데이터를 공유할 수 있습니다. 이는 렌더링 단계 전반에 걸쳐 사용자 데이터와 같은 요청별 데이터를 저장하는 데 유용합니다.

locals에는 문자열, 숫자, 심지어 함수나 맵과 같은 모든 타입의 데이터를 저장할 수 있습니다.

export function onRequest ({ locals, request }, next) {
    // 요청의 응답 데이터 가로채기
    // 선택적으로 `locals`의 속성을 수정합니다.
    locals.user.name = "John Wick";
    locals.welcomeTitle = () => {
        return "반가워요 " + locals.user.name;
    };

    // Response 객체 또는 `next()` 함수의 호출 결과를 반환합니다.
    return next();
};

그러면 Astro.locals를 통해 .astro 파일에서 이 정보를 사용할 수 있습니다.

---
const title = Astro.locals.welcomeTitle();
const orders = Array.from(Astro.locals.orders.entries());
---
<h1>{title}</h1>
<p>이 {data.property} 속성은 미들웨어로부터 전달되었습니다.</p>
<ul>
    {orders.map(order => {
        return <li>{/* 각각의 order에 대해 해야 할 작업 */}</li>;
    })}
</ul>

locals는 단일 Astro 경로 내에서 살고 죽는 객체입니다. 경로 페이지가 렌더링되면, 기존 locals가 제거되고 새로운 locals가 생성됩니다. 그러므로 여러 페이지 요청에 걸쳐 지속되어야 하는 정보는 다른 곳에 저장되어야 합니다.

예: 민감한 정보 수정

아래 예에서는 페이지에서 수정된 HTML을 렌더링할 수 있도록 미들웨어를 사용하여 “비밀 정보”라는 단어를 “수정됨”으로 대체합니다.

export const onRequest = async (context, next) => {
    const response = await next();
    const html = await response.text();
    const redactedHtml = html.replaceAll("비밀 정보", "수정됨");

    return new Response(redactedHtml, {
        status: 200,
        headers: response.headers
    });
};

미들웨어 타입

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

import { defineMiddleware } from "astro:middleware";

// `context`와 `next`가 자동으로 입력됩니다.
export const onRequest = defineMiddleware((context, next) => {

});

대신 JsDoc을 사용하여 타입 안전성을 활용하는 경우 MiddlewareHandler를 사용할 수 있습니다.

/**
 * @type {import("astro").MiddlewareHandler}
 */
// `context`와 `next`가 자동으로 입력됩니다.
export const onRequest = (context, next) => {

};

.astro 파일과 미들웨어 코드에서 자동 완성 기능을 제공하는 Astro.locals의 데이터에 타입 정보를 제공하려면 env.d.ts 파일에 전역 네임스페이스를 선언하세요.

/// <reference types="astro/client" />
declare namespace App {
    interface Locals {
        user: {
            name: string
        },
        welcomeTitle: () => string,
        orders: Map<string, object>
    }
}

그러면 미들웨어 파일에서 자동 완성 및 타입 안전성을 활용할 수 있습니다.

미들웨어 체이닝

sequence()를 사용하여 여러 미들웨어를 지정된 순서로 결합할 수 있습니다.

import { sequence } from "astro:middleware";

async function validation(_, next) {
    console.log("validation 요청");
    const response = await next();
    console.log("validation 응답");
    return response;
}

async function auth(_, next) {
    console.log("auth 요청");
    const response = await next();
    console.log("auth 응답");
    return response;
}

async function greeting(_, next) {
    console.log("greeting 요청");
    const response = await next();
    console.log("greeting 응답");
    return response;
}

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

그러면 다음과 같은 순서대로 콘솔에 메시지가 출력됩니다.

validation 요청
auth 요청
greeting 요청
greeting 응답
auth 응답
validation 응답

오류 페이지

미들웨어는 일치하는 경로를 찾을 수 없는 경우에도 주문형 렌더링된 모든 페이지에 대해 실행을 시도합니다. 여기에는 Astro의 기본 (비어있는) 404 페이지와 사용자 정의 404 페이지가 포함됩니다. 그러나 해당 코드의 실행 여부는 어댑터에 따라 결정됩니다. 일부 어댑터는 플랫폼별 오류 페이지를 대신 제공할 수 있습니다.

또한 미들웨어 자체 실행 중에 서버 오류가 발생하지 않는 한, 미들웨어는 사용자 정의 500 페이지를 포함하여 500 오류 페이지를 제공하기 전에 실행을 시도합니다. 미들웨어가 성공적으로 실행되지 않으면 500 페이지를 렌더링하기 위해 Astro.locals에 액세스할 수 없습니다.

GitHub Issue 생성

의견 보내기

미들웨어

사용 방법

`context` 객체

`context.locals`에 데이터 저장

예: 민감한 정보 수정

미들웨어 타입

미들웨어 체이닝

오류 페이지

미들웨어

사용 방법

context 객체

context.locals에 데이터 저장

예: 민감한 정보 수정

미들웨어 타입

미들웨어 체이닝

오류 페이지

`context` 객체

`context.locals`에 데이터 저장