Pylon

Pylon을 사용해 GraphQL API를 구축하는 과정은 간단하고 직관적이다. Pylon은 Hono를 기반으로 구축된 백엔드 프레임워크로, 코드 우선 방식의 GraphQL API 개발을 제공한다.

GraphQL 스키마는 여러분의 TypeScript 정의에서 실시간으로 생성된다. 이를 통해 서비스 로직 작성에만 집중할 수 있다. 이 접근 방식은 개발 속도를 크게 향상시키고, 타입 안전성을 높이며, 오류를 줄인다.

코드의 변경 사항은 즉시 API에 반영된다. 이를 통해 기능에 미치는 영향을 바로 확인할 수 있다.

더 많은 정보는 Pylon을 확인하라.

새로운 Pylon 서비스 설정하기

Pylon은 npm create pylon 명령어를 사용해 새로운 서비스를 생성할 수 있다. 이 명령어는 기본 프로젝트 구조와 설정이 포함된 새로운 Pylon 프로젝트를 생성한다. 설정 과정에서 Bun, Node.js, Cloudflare Workers와 같은 원하는 런타임을 선택할 수 있다.

이 가이드에서는 Bun 런타임을 사용한다.

새로운 프로젝트 생성

새로운 Pylon 프로젝트를 생성하려면 다음 커맨드를 실행한다:

npm create pylon my-pylon@latest

이 커맨드는 my-pylon이라는 디렉토리를 생성하고, 기본 Pylon 프로젝트 구조를 설정한다.

프로젝트 구조

Pylon 프로젝트는 다음과 같은 구조로 구성된다.

my-pylon/
├── .pylon/
├── src/
│   ├── index.ts
├── package.json
├── tsconfig.json

• .pylon/: 프로젝트의 프로덕션 빌드 파일이 위치한다.
• src/: 프로젝트의 소스 코드가 저장된다.
• src/index.ts: Pylon 서비스의 진입점(entry point) 파일이다.
• package.json: npm 패키지 설정 파일이다.
• tsconfig.json: TypeScript 설정 파일이다.

기본 예제

다음은 기본적인 Pylon 서비스의 예제이다:

import { app } from '@getcronit/pylon'

export const graphql = {
  Query: {
    sum: (a: number, b: number) => a + b,
  },
  Mutation: {
    divide: (a: number, b: number) => a / b,
  },
}

export default app

API 보안 설정

Pylon은 클라우드 네이티브 기반의 ID 및 접근 관리 솔루션인 ZITADEL과 통합되어 API의 안전한 인증과 권한 부여를 제공한다. ZITADEL 문서에 설명된 단계를 따라 Pylon API를 쉽게 보안 설정할 수 있다.

더 복잡한 API 만들기

Pylon은 실시간 스키마 생성 기능을 활용해 더 복잡한 API를 만들 수 있게 해준다. 지원되는 TypeScript 타입과 API 정의 방법에 대한 자세한 내용은 Pylon 문서를 참조한다.

이 예제는 Pylon에서 복잡한 타입과 서비스를 정의하는 방법을 보여준다. TypeScript 클래스와 메서드를 활용해 데이터베이스, 외부 서비스, 그리고 다른 리소스와 상호작용하는 강력한 API를 만들 수 있다.

import { app } from '@getcronit/pylon'

class Post {
  id: string
  title: string

  constructor(id: string, title: string) {
    this.id = id
    this.title = title
  }
}

class User {
  id: string
  name: string

  constructor(id: string, name: string) {
    this.id = id
    this.name = name
  }

  static async getById(id: string): Promise<User> {
    // 데이터베이스에서 사용자 데이터를 가져옴
    return new User(id, 'John Doe')
  }

  async posts(): Promise<Post[]> {
    // 데이터베이스에서 이 사용자의 게시물을 가져옴
    return [new Post('1', 'Hello, world!')]
  }

  async $createPost(title: string, content: string): Promise<Post> {
    // 데이터베이스에 이 사용자의 새 게시물을 생성함
    return new Post('2', title)
  }
}

export const graphql = {
  Query: {
    user: User.getById,
  },
  Mutation: {
    createPost: (userId: string, title: string, content: string) => {
      const user = User.getById(userId)
      return user.$createPost(title, content)
    },
  },
}

export default app

API 호출하기

Pylon API는 어떤 GraphQL 클라이언트 라이브러리로도 호출할 수 있다. 개발 목적으로는 Pylon Playground를 사용하는 것을 추천한다. Pylon Playground는 웹 기반 GraphQL IDE로, API와 실시간으로 상호작용할 수 있다.

1. 프로젝트 디렉토리에서 bun run dev를 실행해 Pylon 서버를 시작한다.
2. 브라우저에서 http://localhost:3000/graphql로 이동해 Pylon Playground를 연다.
3. 왼쪽 패널에 GraphQL 쿼리나 뮤테이션을 작성한다.

Hono 컨텍스트에 접근하기

getContext 함수를 사용하면 코드 어디서든 Hono 컨텍스트에 접근할 수 있다. 이 함수는 현재 컨텍스트 객체를 반환하며, 이 객체는 요청, 응답 및 기타 컨텍스트 관련 데이터를 포함한다.

import { app, getContext } from '@getcronit/pylon'

export const graphql = {
  Query: {
    hello: () => {
      const context = getContext()
      return `Hello, ${context.req.headers.get('user-agent')}`
    },
  },
}

export default app

Hono 컨텍스트 객체와 그 속성에 대한 자세한 내용은 Hono 문서와 Pylon 문서를 참고한다.

Hono의 역할

Pylon은 Hono 위에 구축된 경량 웹 프레임워크이다. Hono는 웹 애플리케이션과 API를 구축하는 데 핵심적인 기능을 제공하며, Pylon은 이 기능을 확장해 GraphQL API 개발을 지원한다.

GraphQL 외에도 Pylon은 기본 Hono 앱 인스턴스에 접근해 커스텀 라우트와 미들웨어를 추가할 수 있게 한다. 이를 통해 Hono의 모든 기능을 활용해 더 복잡한 API와 서비스를 구축할 수 있다.

import { app } from '@getcronit/pylon'

export const graphql = {
  Query: {
    sum: (a: number, b: number) => a + b,
  },
  Mutation: {
    divide: (a: number, b: number) => a / b,
  },
}

// Pylon 앱에 커스텀 라우트 추가
app.get('/hello', (ctx, next) => {
  return new Response('Hello, world!')
})

결론

Pylon은 GraphQL API 개발을 단순화하는 강력한 웹 프레임워크다. TypeScript 타입 정의를 활용해 실시간 스키마 생성을 제공하며, 타입 안전성을 높이고 오류를 줄인다. Pylon을 사용하면 비즈니스 요구 사항을 충족하는 안전하고 확장 가능한 API를 빠르게 구축할 수 있다. Pylon과 Hono의 통합을 통해 GraphQL API 개발에 집중하면서도 Hono의 모든 기능을 활용할 수 있다.

Pylon에 대한 더 자세한 정보는 공식 문서를 참고한다.

참고 자료

• Pylon
• Pylon 문서
• Hono 문서
• ZITADEL 문서