실험적 세션

타입: SessionConfig
기본값: undefined

Added in: astro@5.1.0 New

세션은 요청 시 렌더링되는 페이지에 대한 요청 사이에 사용자 상태를 저장하는 데 사용됩니다.

이 실험적 기능을 사용하면 로그인 상태, 장바구니 내용 또는 기타 사용자별 데이터와 같은 항목을 저장하고 액세스할 수 있습니다:

---
export const prerender = false; // 'server' 모드에서는 필요하지 않습니다.
const cart = await Astro.session.get('cart');
---

<a href="/checkout">🛒 {cart?.length ?? 0} items</a>

세션은 session 객체에 데이터를 저장하기 위해 구성 가능한 세션 driver에 의존합니다. 세션 쿠키는 식별 세션 ID를 저장합니다.

session 객체를 사용하면 저장된 사용자 상태(예: 장바구니에 항목 추가) 및 세션 ID(예: 로그아웃 시 세션 ID 쿠키 삭제)와 상호 작용할 수 있습니다.

실험적 세션 활성화

현재 experimental.sessions의 초기 릴리스에서는 Astro의 공식 서버 어댑터가 아직 플랫폼의 기본 스토리지 기능을 기반으로 하는 기본 세션 드라이버를 제공하도록 업데이트되지 않았습니다. 이러한 기능이 내장될 때까지 어댑터를 추가하는 것 외에도 experimental.sessions 구성 객체에서 직접 driver를 지정해야 합니다.

다음 섹션에서는 각 어댑터에 대해 권장되는 드라이버를 보여줍니다. (이 기능의 안정적인 릴리스에서는 자동으로 구성됩니다.) 또는 unstorage의 지원되는 드라이버 중 하나를 지정할 수 있습니다.

Node 어댑터로 세션 구성

Node 어댑터는 파일시스템 드라이버와 호환됩니다. 공유 파일시스템이 없는 서버리스 환경에서는 사용할 수 없습니다.

  {
    adapter: node({ mode: 'standalone' }),
    experimental: {
      session: {
        // 필수: unstorage 드라이버의 이름
        driver: "fs",
      },
    },
  }

다른 어댑터의 세션 드라이버 구성

Netlify Blobs 드라이버(netlify-blobs), Cloudflare KV 드라이버(cloudflare-kv-binding) 또는 Deno KV 드라이버(deno-kv)와 같이 호스팅 플랫폼에서 제공하는 스토리지 기능에 해당하는 unstorage driver 이름을 선택하세요. Upstash나 Redis와 같은 크로스 플랫폼 드라이버를 사용할 수도 있습니다.

드라이버 옵션

unstorage 드라이버에 사용 가능한 모든 옵션을 별도의 session.options 객체로 전달할 수도 있습니다. 다음 예제는 Netlify Blobs 드라이버를 구성하면서 name을 제공하고 consistency 모드를 지정합니다:

  {
    adapter: netlify(),
    experimental: {
      session: {
        // unstorage 드라이버의 이름은 kebab-case 형식으로 지정합니다.
        driver: "netlify-blobs",
        options: {
          name: 'astro-sessions',
          // 세션을 사용하기 위해 consistency를 strong으로 지정합니다.
          consistency: 'strong',
        }
      },
    },
  }

세션 사용

드라이버를 구성하면 session 객체를 사용하여 세션과 상호 작용할 수 있습니다. 이 객체는 Astro 컴포넌트와 페이지에서는 Astro.session으로, API 엔드포인트, 미들웨어 및 액션의 context 객체에서 접근할 수 있습니다. API는 모든 경우에 동일합니다.

대부분의 경우 Astro.session.get()과 Astro.session.set()만 사용하면 됩니다. 다른 사용 가능한 메서드는 API 섹션을 참조하세요.

Astro 컴포넌트 및 페이지

.astro 컴포넌트와 페이지에서는 전역 Astro 객체를 통해 세션 객체에 접근할 수 있습니다. 예를 들어, 장바구니의 항목 수를 표시하는 방법은 다음과 같습니다:

---
export const prerender = false; // 'server' 모드에서는 필요하지 않습니다.
const cart = await Astro.session.get('cart');
---

<a href="/checkout">🛒 {cart?.length ?? 0} items</a>

API 엔드포인트

API 엔드포인트에서는 context 객체에서 세션 객체를 사용할 수 있습니다. 예를 들어, 장바구니에 항목을 추가하는 방법은 다음과 같습니다:

import type { APIContext } from "astro";

export async function POST(req: Request, context: APIContext) {
  const cart = await context.session.get("cart");
  cart.push(req.body.item);
  await context.session.set("cart", cart);
  return Response.json(cart);
}

액션

액션에서는 context 객체에서 세션 객체를 사용할 수 있습니다. 예를 들어, 장바구니에 항목을 추가하는 방법은 다음과 같습니다:

import { defineAction } from "astro:actions";
import { z } from "astro:schema";

export const server = {
  addToCart: defineAction({
    input: z.object({ productId: z.string() }),
    handler: async (input, context) => {
      const cart = await context.session.get("cart");
      cart.push(input.productId);
      await context.session.set("cart", cart);
      return cart;
    },
  }),
};

미들웨어

미들웨어에서는 context 객체에서 세션 객체를 사용할 수 있습니다. 예를 들어, 세션에서 마지막 방문 시간을 설정하는 방법은 다음과 같습니다:

import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware(async (context, next) => {
  context.session.set('lastVisit', new Date());
  return next();
});

쿠키

세션은 처음 접근할 때 생성되며 응답에 세션 ID 쿠키가 설정됩니다. 쿠키에는 실제 사용자 데이터가 저장되지 않고 사용자의 세션을 식별하는 데 사용되는 ID만 저장됩니다. 세션은 Astro.session.regenerate()를 사용하여 언제든지 재생성할 수 있으며, Astro.session.destroy()를 사용하여 삭제할 수 있습니다.

`session.cookie`

타입: string | object
기본값: undefined

쿠키 옵션을 설정하기 위한 선택적 속성입니다. cookie.name 속성은 문자열을 제공하여 자동으로 설정할 수 있습니다. 추가 옵션을 구성하려면 객체를 제공하세요.

  {
    experimental: {
      session: {
        // 문자열로 설정하면 쿠키 이름으로 사용됩니다
        // cookie: "my-session-id",
        // 객체로 설정하면 고급 옵션을 설정할 수 있습니다
        cookie: {
          name: "my-session-id"
          sameSite: "Strict",
        },
      }
    }
  }

세션 API

세션 객체는 컴포넌트, 액션 및 API 엔드포인트를 포함한 모든 Astro 컨텍스트에서 사용할 수 있습니다. 컴포넌트에서는 전역 Astro 객체를 통해 접근하고, 액션과 API 엔드포인트에서는 context 객체에서 사용할 수 있습니다. API는 모든 경우에 동일합니다.

값은 콘텐츠 레이어와 액션에서 사용되는 것과 같은 라이브러리인 devalue를 사용하여 직렬화 및 역직렬화됩니다. 이는 지원되는 타입이 동일하며, 문자열, 숫자, Date, Map, Set, URL, 배열 및 일반 객체를 포함한다는 의미입니다.

`session.get()`

타입: (key: string) => Promise<any>

세션에서 주어진 키의 값을 반환합니다. 키가 존재하지 않으면 undefined를 반환합니다.

`session.set()`

타입: (key: string, value: any, options?: { ttl: number }) => void

세션에서 주어진 키의 값을 설정합니다. 값은 직렬화 가능한 모든 타입이 될 수 있습니다.

`session.regenerate()`

타입: () => void

세션 ID를 재생성합니다. 세션 고정 공격을 방지하기 위해 사용자가 로그인하거나 권한을 높일 때 호출하는 것이 가장 좋습니다.

`session.destroy()`

타입: () => void

세션을 파괴하고 쿠키와 객체를 백엔드에서 삭제합니다. 사용자가 로그아웃하거나 세션이 무효화될 때 호출해야 합니다.

더 알아보기

이 실험적 API에 대한 자세한 내용과 피드백을 제공하려면 세션 RFC를 참조하세요.

기여하기 커뮤니티 후원하기