Node.js와 Express를 이용한 GraphQL: 종합 가이드

API를 구축하는 방식을 혁신할 준비가 되셨나요? 개발 세계에 일정 기간 있었다면, GraphQL, Node.js 및 Express에 대해 들어본 적이 있을 것입니다. 이러한 기술들은 현대적이고 효율적인 API를 구축하기 위한 강력한 도구 키트를 만듭니다. 오늘은 Node.js와 Express를 사용하여 GraphQL의 세계에 깊이 들어가서 이 조합을 프로젝트에 이해하고 구현할 수 있도록 돕겠습니다.

하지만 먼저, API 개발을 훨씬 더 원활하게 만들어 줄 도구를 소개하겠습니다: Apidog. Apidog는 GraphQL, Node.js 및 Express와 원활하게 통합되는 무료 API 테스트 및 관리 도구입니다. API 개발 프로세스를 간소화하고 싶다면 Apidog를 무료로 다운로드하여 차이를 확인해 보세요!

GraphQL, Node.js 및 Express 소개

GraphQL란 무엇인가요?

GraphQL는 API를 위한 쿼리 언어이자, 정의한 데이터 형식 시스템을 사용하여 쿼리를 실행하는 서버 측 런타임입니다. Facebook에서 개발된 GraphQL은 REST에 대한 보다 효율적이고 강력하며 유연한 대안을 제공합니다. GraphQL을 사용하면 필요한 데이터를 정확히 요청할 수 있어 데이터의 과다 또는 부족 가져오기를 피할 수 있습니다.

Node.js란 무엇인가요?

Node.js는 Chrome의 V8 JavaScript 엔진을 기반으로 구축된 JavaScript 런타임입니다. 이를 통해 개발자는 서버 측에서 JavaScript를 사용하여 확장 가능한 네트워크 애플리케이션을 구축할 수 있습니다. Node.js는 경량화 및 효율성을 제공하는 이벤트 기반 비블록킹 I/O 모델로 알려져 있습니다.

Express란 무엇인가요?

Express는 웹 및 모바일 애플리케이션을 개발하기 위해 강력한 기능 집합을 제공하는 최소한의 유연한 Node.js 웹 애플리케이션 프레임워크입니다. Node 기반의 웹 애플리케이션을 빠르게 개발할 수 있도록 도와주며, RESTful API를 구축하는 데 자주 사용됩니다.

개발 환경 설정하기

API를 구축하기 전에 개발 환경을 설정합시다. 필요한 사항은 다음과 같습니다:

Node.js 및 npm (Node Package Manager) 설치
코드 편집기 (예: Visual Studio Code)
터미널 또는 명령 프롬프트

Node.js 및 npm 설치하기

공식 Node.js 웹사이트에서 Node.js를 다운로드하고 설치합니다. npm은 Node.js와 함께 번들로 제공되므로 별도로 설치할 필요가 없습니다.

새 Node.js 프로젝트 초기화하기

터미널을 열고 프로젝트를 위한 새 디렉토리를 생성합니다. 프로젝트 디렉토리로 이동하여 다음 명령어를 실행하여 새 Node.js 프로젝트를 초기화합니다:

npm init -y

이 명령어는 프로젝트 디렉토리에 package.json 파일을 생성합니다.

기본 Express 서버 만들기

이제 프로젝트가 설정되었으니, 기본 Express 서버를 만들어 봅시다.

Express 설치하기

Express를 설치하려면 다음 명령어를 실행하세요:

npm install express

서버 생성하기

server.js라는 새 파일을 만들고 다음 코드를 추가하세요:

const express = require('express');
const app = express();
const PORT = process.env.PORT || 4000;

app.get('/', (req, res) => {
  res.send('Hello World!');
});

app.listen(PORT, () => {
  console.log(`서버가 ${PORT} 포트에서 실행 중입니다`);
});

이 코드는 4000번 포트에서 듣고 "Hello World!"라는 응답을 하는 기본 Express 서버를 설정합니다.

서버를 시작하려면 다음 명령을 실행하세요:

node server.js

브라우저에서 http://localhost:4000를 방문하여 "Hello World!" 메시지를 확인하세요.

Express와 GraphQL 통합하기

기본 서버가 실행되고 있으니, 이제 GraphQL을 통합할 시간입니다.

GraphQL 및 Apollo Server 설치하기

Apollo Server는 모든 GraphQL 클라이언트와 호환되는 커뮤니티 유지 관리, 오픈 소스 GraphQL 서버입니다. GraphQL 요청을 처리하는 데 사용할 것입니다.

Apollo Server와 GraphQL을 설치합니다:

npm install apollo-server-express graphql

Apollo Server 설정하기

Express와 함께 Apollo Server를 설정하기 위해 server.js를 수정하세요:

const express = require('express');
const { ApolloServer, gql } = require('apollo-server-express');
const app = express();
const PORT = process.env.PORT || 4000;

// 스키마 정의하기
const typeDefs = gql`
  type Query {
    hello: String
  }
`;

// 리졸버 정의하기
const resolvers = {
  Query: {
    hello: () => 'Hello World!',
  },
};

// ApolloServer 인스턴스 생성하기
const server = new ApolloServer({ typeDefs, resolvers });

// ApolloServer와 Express 연결을 위한 미들웨어 적용
server.applyMiddleware({ app });

app.listen(PORT, () => {
  console.log(`서버가 ${PORT}${server.graphqlPath}에서 실행 중입니다`);
});

이 코드는 "Hello World!"를 반환하는 단일 hello 쿼리로 기본 Apollo Server를 설정합니다.

GraphQL 스키마와 리졸버 정의하기

이제 기본 GraphQL 서버가 실행된 상태에서, 스키마와 리졸버에 대해 더 깊이 들어가 보겠습니다.

스키마란 무엇인가요?

GraphQL 스키마는 API의 유형과 관계를 정의합니다. 어떤 쿼리가 가능하고 어떤 데이터를 가져올 수 있는지를 설명합니다.

리졸버란 무엇인가요?

리졸버는 스키마의 특정 필드를 위해 데이터를 가져오는 작업을 처리하는 함수입니다. 각 쿼리를 위해 GraphQL이 데이터를 가져오는 방법을 알려줍니다.

보다 복잡한 스키마 정의하기

server.js에서 typeDefs와 resolvers를 확장하세요:

const typeDefs = gql`
  type Book {
    title: String
    author: String
  }

  type Query {
    books: [Book]
  }
`;

const books = [
  {
    title: 'The Awakening',
    author: 'Kate Chopin',
  },
  {
    title: 'City of Glass',
    author: 'Paul Auster',
  },
];

const resolvers = {
  Query: {
    books: () => books,
  },
};

이 스키마는 Book 유형과 책 목록을 반환하는 books 쿼리를 정의합니다.

데이터베이스에 연결하기

실제 애플리케이션의 경우 API를 데이터베이스에 연결해야 합니다. 이 예제에서는 MongoDB를 사용하겠습니다.

MongoDB 설정하기

무료 MongoDB Atlas 계정에 가입하거나 로컬 MongoDB 인스턴스를 설정하세요. 그런 다음 Node.js에서 MongoDB와 상호작용하기 위해 mongoose를 설치합니다:

npm install mongoose

MongoDB에 연결하기

MongoDB에 연결하도록 server.js를 수정하세요:

const mongoose = require('mongoose');

mongoose.connect('mongodb://localhost:27017/graphql', {
  useNewUrlParser: true,
  useUnifiedTopology: true,
});

const db = mongoose.connection;
db.on('error', console.error.bind(console, '연결 오류:'));
db.once('open', () => {
  console.log('MongoDB에 연결되었습니다');
});

// Mongoose 스키마 및 모델 정의하기
const bookSchema = new mongoose.Schema({
  title: String,
  author: String,
});

const Book = mongoose.model('Book', bookSchema);

// MongoDB에서 데이터를 가져오기 위해 리졸버 수정하기
const resolvers = {
  Query: {
    books: async () => await Book.find(),
  },
};

이제 books 쿼리가 MongoDB에서 데이터를 가져옵니다.

GraphQL API 최적화하기

GraphQL API가 효율적이고 성능이 뛰어나도록 하기 위해 다음 최적화 기법을 고려하세요:

효율적인 배치 로딩을 위한 DataLoader

DataLoader는 데이터 가져오기를 배치하고 캐시하는 유틸리티입니다. 이것은 데이터베이스 요청의 수를 줄이는 데 도움을 줍니다.

DataLoader를 설치하세요:

npm install dataloader

리졸버에서 DataLoader를 사용하세요:

const DataLoader = require('dataloader');

const bookLoader = new DataLoader(async (keys) => {
  const books = await Book.find({ _id: { $in: keys } });
  return keys.map((key) => books.find((book) => book.id === key));
});

const resolvers = {
  Query: {
    books: async () => await bookLoader.loadAll(),
  },
};

캐싱

중복된 데이터 가져오기를 피하기 위해 캐싱 전략을 구현하세요. Redis와 같은 인메모리 캐시를 사용하여 자주 요청되는 데이터를 저장할 수 있습니다.

페이지네이션

대량 데이터 세트를 반환하는 쿼리의 경우, 데이터 청크를 가져오기 위해 페이지네이션을 구현하세요. limit 및 skip 매개변수를 사용하여 결과를 페이지로 나누세요.

Apidog로 API 테스트하기

API를 테스트하는 것은 기대한 대로 작동하는지 확인하기 위해 중요합니다. Apidog는 직관적인 인터페이스와 강력한 기능으로 이 과정을 간소화합니다.

button

1단계: Apidog를 열고 새 요청을 작성합니다.

2단계: 만들고자 하는 POST 요청의 API 세부정보를 찾거나 수동으로 입력합니다.

3단계: 필요한 매개변수와 요청 본문에 포함할 데이터를 입력합니다.

Apidog를 워크플로에 통합하면 시간을 절약하고 API 개발에서 흔히 발생하는 오류를 피할 수 있습니다. 또한, 무료로 다운로드하고 사용할 수 있습니다!

GraphQL과 함께하는 Apidog

Apidog를 설치한 후에는 GraphQL 스키마를 임포트하여 API를 보다 효율적으로 관리하고 테스트할 수 있습니다. Apidog의 임포트 섹션으로 이동하여 schema.graphqls 파일을 업로드하세요.

"실행" 탭의 쿼리 상자에 쿼리를 입력하세요. 입력 상자에서 수동으로 스키마 가져오기 버튼을 클릭하여 쿼리 표현식에 대한 "코드 완성" 기능을 활성화할 수 있어 쿼리 문장을 입력하는 데 도움을 줄 수 있습니다.

스키마를 가져온 후에는 Apidog를 사용하여 쿼리 및 뮤테이션을 테스트하고, 문서를 생성하며, 응답을 모의할 수 있습니다. 이를 통해 API가 기대한 대로 작동하는지 확인하고 API 사용자에게 포괄적인 가이드를 제공할 수 있습니다.

Apidog의 자동화된 테스트 기능을 사용하여 테스트 사례를 정기적으로 실행하세요. 이는 초기 문제를 잡고 API가 신뢰할 수 있도록 유지하는 데 도움을 줍니다.

API 구축을 위한 모범 사례

강력하고 확장 가능한 API를 구축하려면 모범 사례를 따라야 합니다. 다음은 몇 가지 주요 팁입니다:

설명적인 오류 메시지 사용하기

API가 의미 있는 오류 메시지를 반환하여 클라이언트가 문제가 무엇인지 이해하는 데 도움을 줄 수 있도록 합니다.

API 보안 유지하기

인증 및 권한 부여 메커니즘을 구현하여 API를 무단 접근으로부터 보호하세요.

API 문서화하기

API에 대한 명확하고 포괄적인 문서를 제공합니다. Swagger 및 GraphQL Playground와 같은 도구는 대화형 문서를 생성하는 데 도움을 줄 수 있습니다.

성능 모니터링하기

모니터링 도구를 사용하여 API의 성능을 추적하세요. 성능 병목 현상을 신속히 식별하고 해결하세요.

코드베이스 정리 유지하기

일관된 코드 구조와 명명 규칙을 따라 코드베이스를 깔끔하고 유지 관리 가능하게 유지하세요.

결론

축하합니다! 이제 Node.js 및 Express로 강력한 GraphQL API를 구축하는 방법을 배웠습니다. 개발 환경 설정에서 스키마 및 리졸버 정의, 데이터베이스 연결, API 최적화, Apidog로 테스트하는 것까지 모든 것을 다루었습니다.

훌륭한 API를 구축하는 것은 지속적인 과정임을 잊지 마세요. 지속적으로 기술을 연마하고 GraphQL 생태계의 최신 발전 사항에 대한 정보를 유지하며 새로운 도구와 기술로 실험을 계속하세요.

button