API Gateway 마스터하기: 분산 시스템의 지능형 관문
안녕하세요, 10년 경력의 소프트웨어 엔지니어이자 기술 교육자입니다. 오늘은 현대 웹 아키텍처, 특히 마이크로서비스 환경에서 빼놓을 수 없는 핵심 개념인 API Gateway에 대해 깊이 있게 다뤄보겠습니다. 마이크로서비스가 대세가 되면서 시스템의 복잡성은 기하급수적으로 증가했습니다. 이 복잡성을 효과적으로 관리하고, 클라이언트가 수많은 서비스와 직접 통신해야 하는 부담을 덜어주는 중요한 역할을 하는 것이 바로 API Gateway입니다.
초중급 개발자라면 이 개념을 정확히 이해하고 실제 프로젝트에 적용하는 방법을 아는 것이 중요합니다. 실제 면접에서도 자주 등장하며, 분산 시스템 설계의 기본 소양이기도 합니다. 자, 그럼 API Gateway의 모든 것을 파헤쳐 봅시다!
1. 개념 소개: 정의, 탄생 배경, 왜 중요한지
정의
API Gateway는 클라이언트의 요청을 받아 적절한 백엔드 서비스로 라우팅하고, 그 응답을 다시 클라이언트에 전달하는 단일 진입점(Single Entry Point) 역할을 하는 서버 또는 서비스입니다. 단순한 프록시를 넘어, 인증(Authentication), 인가(Authorization), 로깅(Logging), 모니터링(Monitoring), 캐싱(Caching), 트래픽 관리(Rate Limiting, Throttling), 서비스 디스커버리(Service Discovery) 등 다양한 교차 관심사(Cross-Cutting Concerns)를 처리할 수 있습니다.
탄생 배경
API Gateway의 필요성은 마이크로서비스 아키텍처가 확산되면서 급증했습니다. 과거 모놀리식(Monolithic) 아키텍처에서는 하나의 거대한 애플리케이션이 모든 기능을 담당했기 때문에, 클라이언트는 단 하나의 백엔드 서비스와 통신하면 됐습니다. 하지만 애플리케이션의 규모가 커지고 기능이 복잡해지면서, 유지보수의 어려움, 확장성의 한계, 배포의 제약 등의 문제가 발생했습니다.
이를 해결하기 위해 등장한 것이 마이크로서비스 아키텍처입니다. 마이크로서비스는 하나의 큰 애플리케이션을 작고 독립적인 서비스들로 분리하여 개발하고 배포하는 방식입니다. 각 서비스는 특정 비즈니스 기능(예: 사용자 관리, 상품 관리, 주문 처리)을 담당하며, 독립적으로 개발, 배포, 확장될 수 있습니다.
하지만 마이크로서비스 아키텍처로 전환하면서 새로운 문제들이 발생했습니다:
- 다수의 서비스 엔드포인트: 클라이언트는 여러 개의 마이크로서비스와 직접 통신해야 합니다. 이는 클라이언트의 코드를 복잡하게 만들고, 서비스가 추가되거나 변경될 때마다 클라이언트 코드를 수정해야 하는 번거로움을 야기합니다.
- 공통 기능의 중복: 인증, 인가, 로깅과 같은 기능은 모든 서비스에서 필요하지만, 각 서비스마다 이를 구현하면 코드 중복과 관리의 비효율성을 초래합니다.
- 서비스 간 통신 복잡성: 서비스 간의 직접 통신은 의존성을 높이고, 특정 서비스의 장애가 다른 서비스로 전파될 위험이 있습니다.
- 보안 취약점: 내부 서비스의 엔드포인트가 외부에 직접 노출되면 보안에 취약해질 수 있습니다.
API Gateway는 이러한 문제들을 해결하기 위해 탄생했습니다. 클라이언트와 마이크로서비스 사이에 위치하여, 클라이언트의 요청을 단일화된 방식으로 처리하고, 내부 서비스의 복잡성을 숨겨주는 역할을 합니다.
왜 중요한가?
API Gateway는 현대 분산 시스템에서 다음과 같은 이유로 매우 중요합니다.
- 복잡성 감소 및 단순화: 클라이언트는 단일 API Gateway만 알고 통신하면 됩니다. 내부의 수많은 마이크로서비스 구조나 엔드포인트 변경에 대해 알 필요가 없어 클라이언트 개발이 훨씬 단순해집니다.
- 보안 강화: 내부 서비스의 엔드포인트를 외부에 직접 노출하지 않고, Gateway에서 인증, 인가, WAF(Web Application Firewall) 연동 등을 통해 보안을 강화할 수 있습니다.
- 성능 최적화: 캐싱, 압축, 트래픽 관리(Rate Limiting, Throttling) 등을 통해 시스템의 전체적인 응답 속도를 개선하고 과부하를 방지할 수 있습니다.
- 개발 생산성 향상: 공통 기능을 Gateway에서 처리함으로써 각 마이크로서비스는 핵심 비즈니스 로직에만 집중할 수 있어 개발 속도가 빨라집니다.
- 유연한 아키텍처: 서비스 라우팅 규칙을 Gateway에서 중앙 집중적으로 관리하므로, 내부 서비스의 리팩토링이나 변경이 발생해도 클라이언트에게 영향을 주지 않고 유연하게 대응할 수 있습니다.
- 모니터링 및 로깅: 모든 요청이 Gateway를 통과하므로, 중앙 집중적인 로깅 및 모니터링 지점을 확보하여 시스템의 전반적인 상태를 파악하기 용이합니다.
2. 핵심 원리 설명 (비유와 다이어그램 활용)
API Gateway의 핵심 원리는 클라이언트와 백엔드 서비스 사이의 "중개자" 또는 "관문" 역할입니다. 마치 복잡한 건물에 들어서기 전, 모든 방문객이 거쳐야 하는 프론트 데스크나 종합 안내소와 같습니다.
비유: 당신이 거대한 쇼핑몰에 방문했다고 상상해 봅시다. 이 쇼핑몰에는 수백 개의 상점(마이크로서비스)이 있습니다. 옷 가게, 식당, 전자제품 매장, 영화관 등 다양한 상점이 복잡하게 얽혀있죠. 만약 당신이 특정 상점을 찾을 때마다 직접 그 상점의 위치를 기억하고 찾아가야 한다면 얼마나 불편할까요? 게다가 상점마다 입장 규정(인증)이 다르고, 특정 시간에는 들어갈 수 없거나(트래픽 제한), 물건을 구매할 때 다른 상점의 쿠폰을 사용하려면 복잡한 절차를 거쳐야 한다면요?
이때 쇼핑몰 입구에 있는 **종합 안내 데스크(API Gateway)**는 당신의 불편함을 해소해 줍니다.
- 단일 진입점: 당신은 쇼핑몰에 들어갈 때 오직 안내 데스크를 통해서만 들어갑니다.
- 안내 및 라우팅: "음식점 코너로 가고 싶어요"라고 말하면, 안내 데스크는 가장 적절한 음식점 코너의 위치를 알려주거나, 당신을 그곳으로 직접 안내해 줍니다. (요청을 적절한 서비스로 라우팅)
- 입장 심사(인증/인가): VIP 고객은 특별한 통로로 안내하고, 일반 고객은 신분증 확인 후 입장시킵니다. (사용자 인증 및 권한 확인)
- 정보 제공(캐싱): "오늘의 할인 상품이 뭐예요?"라고 물으면, 안내 데스크는 이미 가지고 있는 정보를 즉시 알려줍니다. 매번 각 상점에 물어볼 필요가 없습니다. (자주 요청되는 데이터를 캐싱)
- 보안: 수상한 사람이나 허가받지 않은 사람은 안내 데스크에서 미리 차단합니다. (보안 정책 적용)
- 통계/관리: 안내 데스크는 오늘 몇 명의 손님이 어떤 상점을 방문했는지 기록하고, 특정 상점에 손님이 너무 몰리면 대기 줄을 관리합니다. (로깅, 모니터링, 트래픽 제어)
이처럼 API Gateway는 클라이언트의 요청을 받아 내부 서비스의 복잡성을 숨기고, 다양한 정책을 적용하여 요청을 처리한 후, 그 결과를 클라이언트에게 다시 전달하는 역할을 합니다.
다이어그램:
graph TD
subgraph Client
A[웹 브라우저]
B[모바일 앱]
end
subgraph API Gateway
direction LR
G1(인증/인가)
G2(라우팅)
G3(캐싱)
G4(로깅/모니터링)
G5(트래픽 관리)
G6(응답 변환)
end
subgraph Microservices
S1(사용자 서비스)
S2(상품 서비스)
S3(주문 서비스)
end
A --> |HTTP 요청: /users/profile| G1
B --> |HTTP 요청: /products/list| G1
G1 -- (인증/인가 후) --> G2
G2 -- (라우팅) --> S1
G2 -- (라우팅) --> S2
G2 -- (라우팅) --> S3
S1 --> |응답| G6
S2 --> |응답| G6
S3 --> |응답| G6
G6 --> |응답 변환 후| A
G6 --> |응답 변환 후| B
위 다이어그램에서 볼 수 있듯이, 클라이언트는 오직 API Gateway와만 통신합니다. API Gateway는 클라이언트의 요청을 받아서:
- 인증/인가: 요청을 보낸 사용자가 누구인지 확인하고, 해당 리소스에 접근할 권한이 있는지 검사합니다.
- 라우팅: 요청 URL(
users/profile,products/list등)에 따라 적절한 마이크로서비스(사용자 서비스,상품 서비스등)로 요청을 전달합니다. 이때 서비스 디스커버리 기능을 사용하여 서비스 인스턴스의 위치를 찾을 수 있습니다. - 캐싱: 이전에 요청했던 동일한 데이터라면, 백엔드 서비스까지 가지 않고 Gateway에 캐시된 데이터를 바로 반환하여 응답 속도를 높입니다.
- 로깅/모니터링: 모든 요청의 흐름을 기록하고, 트래픽 및 성능 지표를 수집하여 시스템 상태를 파악하는 데 도움을 줍니다.
- 트래픽 관리: 특정 서비스로의 요청이 너무 많아지면 요청을 제한(Rate Limiting)하거나, 과부하 방지를 위해 요청을 거부(Throttling)할 수 있습니다.
- 응답 변환: 백엔드 서비스의 응답 형식을 클라이언트가 원하는 형태로 변환하여 제공할 수 있습니다 (예: 여러 서비스의 응답을 하나로 합치거나, 특정 필드를 제거).
이러한 기능들을 통해 API Gateway는 클라이언트와 백엔드 서비스 간의 간극을 메우고, 분산 시스템의 효율성과 안정성을 크게 향상시킵니다.
3. 코드 예제 2개 (Node.js/Express)
여기서는 Node.js의 Express 프레임워크와 http-proxy-middleware 라이브러리를 사용하여 간단한 API Gateway를 구현하는 방법을 보여드리겠습니다. 실제 프로덕션 환경에서는 AWS API Gateway, Kong, Spring Cloud Gateway와 같은 전용 솔루션을 사용하지만, 개념 이해를 돕기 위한 예제입니다.
예제를 실행하기 위해 다음 패키지를 설치해야 합니다.
npm init -y
npm install express http-proxy-middleware jsonwebtoken dotenv
.env 파일에 비밀 키를 설정합니다.
JWT_SECRET=your_super_secret_jwt_key
예제 1: 기본 라우팅 및 프록시
이 예제는 /users로 시작하는 요청은 사용자 서비스로, /products로 시작하는 요청은 상품 서비스로 전달하는 간단한 라우팅 기능을 구현합니다.
// gateway.js
require('dotenv').config(); // .env 파일 로드
const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');
const jwt = require('jsonwebtoken');
const app = express();
const PORT = process.env.PORT || 3000;
const JWT_SECRET = process.env.JWT_SECRET;
// ----- 더미 마이크로서비스 (실제 서비스가 있다고 가정) -----
// 사용자 서비스 (User Service)
const userService = express();
userService.get('/users/profile', (req, res) => {
// 실제라면 토큰에서 사용자 ID를 추출하여 DB에서 프로필 정보를 조회
const userId = req.userId || 'guest'; // 인증 미들웨어에서 userId를 추가했다고 가정
console.log(`[User Service] Profile requested for user: ${userId}`);
res.json({ id: userId, name: `User ${userId}`, email: `${userId}@example.com` });
});
userService.listen(3001, () => console.log('User Service running on port 3001'));
// 상품 서비스 (Product Service)
const productService = express();
productService.get('/products/list', (req, res) => {
console.log('[Product Service] Product list requested');
res.json([
{ id: 1, name: 'Laptop', price: 1200 },
{ id: 2, name: 'Mouse', price: 25 }
]);
});
productService.listen(3002, () => console.log('Product Service running on port 3002'));
// --------------------------------------------------------
// 미들웨어: JWT 토큰을 검증하고 사용자 정보를 요청 객체에 추가
const authenticateJWT = (req, res, next) => {
const authHeader = req.headers.authorization;
if (authHeader) {
const token = authHeader.split(' ')[1]; // "Bearer TOKEN" 형식
jwt.verify(token, JWT_SECRET, (err, user) => {
if (err) {
console.error('JWT Verification Error:', err.message);
return res.sendStatus(403); // 유효하지 않은 토큰
}
req.user = user; // 토큰에 담긴 사용자 정보
req.userId = user.id; // 예시로 userId 추가
next();
});
} else {
// 토큰이 없으면 인증 없이 진행 (예: 공개 API)
// 또는 401 Unauthorized를 반환할 수 있음
// res.sendStatus(401);
console.log('No JWT token provided. Proceeding as guest.');
next();
}
};
// API Gateway 설정
app.use(express.json()); // JSON 요청 본문 파싱
// 테스트용 로그인 엔드포인트 (JWT 발급)
app.post('/auth/login', (req, res) => {
// 실제로는 DB에서 사용자 인증 후 토큰 발급
const { username, password } = req.body;
if (username === 'testuser' && password === 'password') {
const user = { id: 'testuser', role: 'admin' };
const accessToken = jwt.sign(user, JWT_SECRET, { expiresIn: '1h' });
return res.json({ accessToken });
}
res.status(401).send('Invalid credentials');
});
// 사용자 서비스로 라우팅 (인증 미들웨어 적용)
app.use('/users', authenticateJWT, createProxyMiddleware({
target: 'http://localhost:3001',
changeOrigin: true, // 대상 호스트의 오리진을 변경
pathRewrite: { '^/users': '/users' }, // 경로 재작성 (옵션)
onProxyReq: (proxyReq, req, res) => {
// JWT 토큰을 User Service로 전달 (선택 사항)
if (req.headers.authorization) {
proxyReq.setHeader('Authorization', req.headers.authorization);
}
console.log(`[Gateway] Proxying /users request to User Service: ${proxyReq.path}`);
},
onError: (err, req, res) => {
console.error(`[Gateway] User Service Proxy Error: ${err.message}`);
res.status(500).send('User Service Unavailable');
}
}));
// 상품 서비스로 라우팅 (인증 미들웨어 적용, 필요에 따라 생략 가능)
app.use('/products', authenticateJWT, createProxyMiddleware({
target: 'http://localhost:3002',
changeOrigin: true,
pathRewrite: { '^/products': '/products' },
onProxyReq: (proxyReq, req, res) => {
if (req.headers.authorization) {
proxyReq.setHeader('Authorization', req.headers.authorization);
}
console.log(`[Gateway] Proxying /products request to Product Service: ${proxyReq.path}`);
},
onError: (err, req, res) => {
console.error(`[Gateway] Product Service Proxy Error: ${err.message}`);
res.status(500).send('Product Service Unavailable');
}
}));
// 기본 라우트 (API Gateway 자체의 루트)
app.get('/', (req, res) => {
res.send('Welcome to the API Gateway!');
});
app.listen(PORT, () => {
console.log(`API Gateway running on port ${PORT}`);
});
실행 방법:
node gateway.js실행.- 로그인 요청:
POST http://localhost:3000/auth/login(Body:{ "username": "testuser", "password": "password" }) ->accessToken획득 - 사용자 프로필 요청 (인증 필요):
GET http://localhost:3000/users/profile(Headers:Authorization: Bearer <획득한 accessToken>) - 상품 목록 요청 (인증 필요):
GET http://localhost:3000/products/list(Headers:Authorization: Bearer <획득한 accessToken>) - 사용자 프로필 요청 (인증 없이):
GET http://localhost:3000/users/profile-> "No JWT token provided. Proceeding as guest." 메시지와 함께id: guest응답. (예제에서는 인증 없어도 진행하도록 설정) - 상품 목록 요청 (잘못된 토큰):
GET http://localhost:3000/products/list(Headers:Authorization: Bearer invalid_token) ->403 Forbidden응답.
예제 2: 인증 미들웨어 추가 및 트래픽 관리 (Rate Limiting)
이 예제는 API Gateway에 인증 미들웨어를 추가하고, 특정 엔드포인트에 대한 요청 수를 제한하는 Rate Limiting 기능을 적용합니다.
// gateway_with_ratelimit.js
require('dotenv').config();
const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');
const jwt = require('jsonwebtoken');
const rateLimit = require('express-rate-limit'); // Rate Limiting 라이브러리
const app = express();
const PORT = process.env.PORT || 3000;
const JWT_SECRET = process.env.JWT_SECRET;
// ----- 더미 마이크로서비스 (이전 예제와 동일) -----
// 사용자 서비스 (User Service)
const userService = express();
userService.get('/users/profile', (req, res) => {
const userId = req.userId || 'guest';
console.log(`[User Service] Profile requested for user: ${userId}`);
res.json({ id: userId, name: `User ${userId}`, email: `${userId}@example.com` });
});
userService.listen(3001, () => console.log('User Service running on port 3001'));
// 상품 서비스 (Product Service)
const productService = express();
productService.get('/products/list', (req, res) => {
console.log('[Product Service] Product list requested');
res.json([
{ id: 1, name: 'Laptop', price: 1200 },
{ id: 2, name: 'Mouse', price: 25 }
]);
});
productService.listen(3002, () => console.log('Product Service running on port 3002'));
// --------------------------------------------------------
// API Gateway 설정
app.use(express.json());
// 테스트용 로그인 엔드포인트 (JWT 발급)
app.post('/auth/login', (req, res) => {
const { username, password } = req.body;
if (username === 'testuser' && password === 'password') {
const user = { id: 'testuser', role: 'admin' };
const accessToken = jwt.sign(user, JWT_SECRET, { expiresIn: '1h' });
return res.json({ accessToken });
}
res.status(401).send('Invalid credentials');
});
// 미들웨어: JWT 토큰을 검증하고 사용자 정보를 요청 객체에 추가
const authenticateJWT = (req, res, next) => {
const authHeader = req.headers.authorization;
if (authHeader) {
const token = authHeader.split(' ')[1];
jwt.verify(token, JWT_SECRET, (err, user) => {
if (err) {
return res.sendStatus(403); // 유효하지 않은 토큰
}
req.user = user;
req.userId = user.id;
next();
});
} else {
res.sendStatus(401); // 토큰이 없으면 401 Unauthorized 반환 (인증 필수)
}
};
// Rate Limiting 설정 (예: 5분 동안 동일 IP당 최대 100개의 요청)
const apiLimiter = rateLimit({
windowMs: 5 * 60 * 1000, // 5분
max: 100, // 5분 동안 최대 100개 요청
message: 'Too many requests from this IP, please try again after 5 minutes',
standardHeaders: true, // RateLimit-* 헤더 추가
legacyHeaders: false, // X-RateLimit-* 헤더 비활성화
});
// 특정 API에 대한 더 엄격한 Rate Limiting (예: /products/list는 1분 동안 10개 요청)
const productListLimiter = rateLimit({
windowMs: 1 * 60 * 1000, // 1분
max: 10, // 1분 동안 최대 10개 요청
message: 'Too many product list requests, please try again after 1 minute',
standardHeaders: true,
legacyHeaders: false,
});
// 모든 API 요청에 일반 Rate Limiting 적용
app.use(apiLimiter);
// 사용자 서비스로 라우팅 (인증 필수)
app.use('/users', authenticateJWT, createProxyMiddleware({
target: 'http://localhost:3001',
changeOrigin: true,
pathRewrite: { '^/users': '/users' },
onProxyReq: (proxyReq, req, res) => {
proxyReq.setHeader('Authorization', req.headers.authorization);
console.log(`[Gateway] Proxying /users request to User Service: ${proxyReq.path}`);
},
onError: (err, req, res) => {
console.error(`[Gateway] User Service Proxy Error: ${err.message}`);
res.status(500).send('User Service Unavailable');
}
}));
// 상품 서비스로 라우팅 (인증 필수, /products/list에는 추가 Rate Limiting 적용)
app.use('/products', authenticateJWT, createProxyMiddleware({
target: 'http://localhost:3002',
changeOrigin: true,
pathRewrite: { '^/products': '/products' },
onProxyReq: (proxyReq, req, res) => {
proxyReq.setHeader('Authorization', req.headers.authorization);
console.log(`[Gateway] Proxying /products request to Product Service: ${proxyReq.path}`);
},
onError: (err, req, res) => {
console.error(`[Gateway] Product Service Proxy Error: ${err.message}`);
res.status(500).send('Product Service Unavailable');
}
}));
// /products/list 엔드포인트에만 더 엄격한 Rate Limiting 적용
app.get('/products/list', productListLimiter, (req, res, next) => {
// 이 부분은 이미 위에서 createProxyMiddleware로 처리되므로,
// 실제로는 라우팅 미들웨어 이전에 위치시켜야 효과가 있습니다.
// 여기서는 개념 설명을 위해 라우트 정의 바로 앞에 배치했습니다.
// 실제 사용 시에는 `app.use('/products/list', productListLimiter, ...)` 형태로 사용됩니다.
next();
});
// 기본 라우트
app.get('/', (req, res) => {
res.send('Welcome to the API Gateway with Rate Limiting!');
});
app.listen(PORT, () => {
console.log(`API Gateway with Rate Limiting running on port ${PORT}`);
});
실행 방법:
node gateway_with_ratelimit.js실행.- 로그인 요청:
POST http://localhost:3000/auth/login(Body:{ "username": "testuser", "password": "password" }) ->accessToken획득 - 상품 목록 요청 (인증 필요):
GET http://localhost:3000/products/list(Headers:Authorization: Bearer <획득한 accessToken>)- 이 요청을 1분 안에 10번 넘게 보내면, 11번째 요청부터는
429 Too Many Requests상태 코드와 함께 "Too many product list requests, please try again after 1 minute" 메시지를 받게 됩니다.
- 이 요청을 1분 안에 10번 넘게 보내면, 11번째 요청부터는
- 사용자 프로필 요청 (인증 없이):
GET http://localhost:3000/users/profile->401 Unauthorized응답. (예제 1과 다르게 인증이 필수로 변경됨)
이 예제들은 API Gateway가 어떻게 클라이언트 요청을 가로채고, 인증/인가 및 트래픽 관리와 같은 공통 기능을 적용한 후, 적절한 백엔드 서비스로 라우팅하는지 보여줍니다.
4. 실무 적용 사례
API Gateway는 마이크로서비스 아키텍처를 도입하는 거의 모든 현대적인 시스템에서 핵심적인 역할을 합니다.
- 대규모 웹/모바일 서비스: 쿠팡, 배달의민족, 카카오톡과 같은 대규모 서비스들은 수십, 수백 개의 마이크로서비스로 구성되어 있습니다. 이 서비스들은 API Gateway를 통해 클라이언트 요청을 효율적으로 처리하고, 안정적인 서비스를 제공합니다. 예를 들어, 모바일 앱 클라이언트와 웹 클라이언트에 다른 형태의 API를 제공해야 할 때, API Gateway에서 응답을 변환하여 제공할 수 있습니다.
- 클라우드 환경의 마이크로서비스: AWS, Azure, Google Cloud와 같은 클라우드 플랫폼은 자체적인 API Gateway 서비스를 제공합니다 (예: AWS API Gateway, Azure API Management, Google Cloud API Gateway). 이 서비스들은 서버리스(Serverless) 함수(Lambda, Functions)나 컨테이너 기반 서비스(ECS, EKS, AKS, GKE)와 연동되어 마이크로서비스를 쉽게 배포하고 관리할 수 있도록 돕습니다.
- 레거시 시스템 통합: 기존의 모놀리식 또는 레거시 시스템을 점진적으로 마이크로서비스로 전환할 때, API Gateway는 레거시