← YouthDeveloper / 개발 가이드
FIELD GUIDE / CLOUDFLARE-WORKERS

Cloudflare Workers로 작은 API 만들기

정적 웹사이트에 서버 기능을 연결하는 구조, API 설계, 검증과 오류 처리의 기본 원칙을 정리했습니다.

YOUTHDEVELOPER EDITORIAL · 2026-11-13 · 9분 읽기

1. 정적 페이지와 서버 API의 역할

GitHub Pages는 HTML, CSS, JavaScript를 전달하는 데 적합하지만 서버 비밀 키를 안전하게 보관하거나 데이터베이스 작업을 직접 수행하지는 않습니다. 브라우저에서 서버 기능이 필요할 때는 별도의 API가 필요합니다. Cloudflare Workers는 요청을 받아 검증하고 응답을 돌려주는 서버 측 코드를 실행하는 방식 중 하나입니다.

2. 요청과 응답을 먼저 설계합니다

API를 만들기 전에 주소, HTTP 메서드, 입력 데이터, 응답 형식, 오류 코드를 정의합니다. 예를 들어 게시물 목록 조회는 GET, 새 게시물 등록은 POST로 구분할 수 있습니다. 성공 응답과 실패 응답의 JSON 구조를 일관되게 유지하면 프런트엔드에서 오류를 처리하기 쉬워집니다.

3. 브라우저 입력을 신뢰하지 않습니다

클라이언트에서 필수 입력값을 검사하더라도 서버에서 같은 검증을 다시 해야 합니다. 이용자는 개발자 도구나 직접 만든 요청으로 화면의 검사를 건너뛸 수 있기 때문입니다. 문자열 길이, 허용 문자, 요청 크기, 사용자 권한을 서버에서 확인하고, 데이터베이스 쿼리는 매개변수화된 방식으로 처리해야 합니다.

4. CORS는 접근 제어와 다릅니다

CORS는 브라우저가 다른 출처의 응답을 JavaScript에 공개할 수 있는지 결정하는 정책입니다. 허용 출처를 명확히 지정하고 필요한 메서드와 헤더만 허용해야 합니다. CORS 설정만으로 API를 보호할 수는 없습니다. curl이나 서버 간 요청은 브라우저의 CORS 제한을 받지 않으므로 인증과 권한 검사는 별도로 구현해야 합니다.

5. 비밀 정보와 관리자 권한

API 키와 관리자 비밀번호는 Worker의 환경변수 또는 Secret 기능에 보관하고 브라우저 코드나 공개 저장소에 넣지 않습니다. 관리자 작업은 서버가 인증 토큰을 검증한 뒤 수행해야 합니다. 토큰을 URL 쿼리 문자열이나 로그에 남기지 말고, 필요 이상의 권한을 부여하지 않는 것이 좋습니다.

6. 운영 중 관찰할 지표

오류율, 응답 시간, 요청 수, 데이터베이스 실패, 인증 실패를 확인할 수 있어야 합니다. 오류 응답에는 사용자가 이해할 수 있는 설명을 제공하되 내부 스택이나 비밀 정보는 노출하지 않습니다. 배포 전에는 정상 입력뿐 아니라 빈 값, 너무 긴 값, 잘못된 형식, 권한이 없는 요청도 시험합니다.

7. API 경로와 응답 형식을 일관되게 만들기

기능별 주소와 메서드를 정해 두면 프런트엔드와 서버를 따로 수정할 때 혼란이 줄어듭니다. 예를 들어 GET /api/items는 목록 조회, POST /api/items는 새 항목 등록처럼 역할을 분리합니다. 성공 응답은 필요한 데이터만 반환하고, 실패 응답에는 일관된 error 코드와 이용자가 이해할 수 있는 message를 담습니다. 내부 환경변수, SQL 문장, 스택 추적은 응답에 포함하지 않습니다.

요청 본문은 크기 제한을 두고 JSON 파싱 실패, 필수 값 누락, 문자열 길이 초과, 허용되지 않은 값 등을 각각 처리합니다. 브라우저 화면의 required 속성이나 JavaScript 검사는 편의 기능일 뿐이며, 서버 검증이 최종 기준입니다.

8. 데이터베이스 연결 전후의 점검

D1이나 다른 데이터베이스를 연결한다면 테이블 구조와 데이터 보관 목적부터 문서화합니다. 사용자별 데이터에는 소유자 식별 정보가 필요하며, 읽기·수정·삭제 요청마다 요청한 이용자가 해당 데이터에 접근할 권한이 있는지 확인합니다. 검색 조건과 정렬 값은 허용 목록으로 제한하고, SQL은 매개변수 바인딩을 사용합니다.

운영 환경에 반영하기 전에 빈 데이터베이스, 정상 데이터, 중복 등록, 잘못된 ID, 권한 없는 접근, 동시에 들어오는 요청을 시험합니다. 백업과 복구가 필요한 데이터인지, 삭제 요청을 어떻게 처리할지도 미리 결정합니다.

9. 배포 후 관찰과 장애 대응

API가 실패했을 때 브라우저에 표시되는 오류와 서버 로그를 함께 확인할 수 있도록 요청 식별자를 활용하면 원인을 찾기 쉽습니다. 단, 요청 식별자에 이메일·토큰·메시지 본문 같은 개인정보를 넣지 않습니다. 로그 접근 권한을 제한하고 필요한 기간이 지나면 정리합니다.

환경변수 이름 변경, 데이터베이스 마이그레이션, CORS 허용 출처 변경은 배포 전후 모두 확인해야 합니다. 장애가 발생하면 마지막 변경 사항, Worker 로그, 데이터베이스 상태, 브라우저 Network 탭 순서로 범위를 좁히고, 복구 후 같은 문제가 재발하지 않도록 회귀 테스트를 추가합니다.

참고 자료: Cloudflare Workers 공식 문서 · Cloudflare D1 공식 문서

광고