요청 뒤에서 일하는 백엔드

새 용어 전에, 아는 것부터

이번 실습은 새 출발입니다. 18주차 문서 보관소나 React 프로젝트가 없어도 됩니다. 빈 csv-worker-lab 폴더에서 시작하세요.

“접수했어요”와 “끝났어요”는 다르다

확장 · W8 백엔드는 요청을 받아 업무 규칙을 적용하고 데이터를 처리하는 역할입니다. 서버는 HTML이나 JSON을 응답할 수 있지만, 오래 걸리는 처리를 요청을 받는 자리에서 전부 끝낼 필요는 없습니다.

큰 CSV를 집계하거나 리포트를 만들 때는 먼저 작업을 접수하고, 별도 프로그램인 백그라운드 Worker가 대기 중인 작업을 처리하게 할 수 있습니다. 이번에는 Worker의 로그를 보기 위해 터미널에서 직접 실행합니다. “백그라운드”는 접수 흐름과 처리를 나눈다는 뜻이지, 창을 닫아도 자동으로 실행된다는 뜻은 아닙니다.

실제 서비스에서는 API가 접수 담당이 될 수 있습니다. 사용자 요청 → API 접수 → 작업 큐 → Worker → 결과 저장 순서입니다. 오늘은 HTTP 서버 대신 접수 스크립트, 운영용 큐 대신 로컬 폴더를 사용해 역할을 눈으로 확인합니다.

도구 이름보다, 맡은 일을 구분하기

NEW Python·Java·JavaScript는 언어, FastAPI·Spring·NestJS는 프레임워크입니다. Node.js는 JavaScript를 브라우저 밖에서 실행하는 런타임입니다. 18주차에서 보충한 구분을 그대로 씁니다.

Python은 이후 데이터·RAG 실습에도 이어 쓸 수 있습니다. 여러 언어는 공통 기초를 공유하지만 타입·성능·라이브러리·운영 방식에도 차이가 있습니다. 문법만 다른 방언으로 이해하지는 마세요.

CSV 집계를 다섯 가지 기초로 읽기

업무 규칙과 MVC

NEW “헤더는 행 수에서 뺀다”, “공백만 있는 셀도 누락으로 친다” 같은 기준이 비즈니스 로직입니다. 업무 담당자와 개발자가 함께 정하고 AI에게 구체적으로 전달합니다.

MVC는 Model(데이터·규칙), View(표현), Controller(요청 흐름)으로 책임을 나누는 설계 방식입니다. 웹 앱에서는 데이터 처리, 화면, 요청 처리의 역할을 나눠 생각할 수 있습니다. 이번 작은 Worker는 MVC 구조를 구현하지 않으며 Worker가 곧 Controller인 것도 아닙니다. 핵심은 “접수·처리·기록의 책임을 설명할 수 있는가”입니다.

API와 데이터 약속은 그대로

복습 · W3 API는 프로그램이 기능을 사용하는 접점, REST는 자원 중심의 아키텍처 스타일, JSON은 데이터 표현 형식입니다. REST와 JSON은 같은 말이 아니며, REST가 스마트폰 때문에 생긴 것도 아닙니다.

예를 들어 문서 API의 같은 주소라도 GET은 읽고 POST는 추가합니다. 메서드와 경로를 함께 적어야 동작이 분명해집니다. 아래는 개념 복습용이며 이번 Worker 실습에 구현하는 주소는 아닙니다.

CRUD는 데이터 처리의 기본 묶음입니다. 작업 접수·취소처럼 다른 기능도 API로 제공할 수 있습니다. 오래 걸리는 작업을 HTTP로 접수한다면 202 Accepted와 작업 ID를 반환하고, 나중에 상태를 조회하는 방식도 가능합니다. “접수 성공”은 “처리 성공”과 다릅니다.

JSON은 API 밖에서도 쓴다

{
  "job_id": "발급된작업ID",
  "status": "pending",
  "source_file": "sample.csv",
  "submitted_at": "2026-09-21T00:00:00+00:00"
}

중괄호는 객체 하나, 대괄호는 목록입니다. JSON은 데이터베이스도 화면도 아닙니다. 이번에는 API 통신이 아니라 프로그램끼리 전달할 작업 설명과 결과를 파일로 저장할 때 사용합니다.

확장 · W17 Parse JSON으로 필요한 필드를 꺼냈던 것처럼 이번에는 Python의 json 모듈로 읽습니다. title·tags 대신 job_id·status·row_count를 보지만 데이터 형식은 같습니다.

Cursor에서 빈 폴더 열기

새 csv-worker-lab 폴더를 만들고 Cursor의 File → Open Folder로 엽니다. Terminal → New Terminal을 선택해 아래 명령을 실행하세요. 안내는 Windows PowerShell 기준입니다.

py --version

Python 3.10 이상이면 준비 끝입니다. py를 찾지 못하면 python --version을 확인하고 아래 모든 명령의 py를 python으로 바꿉니다. 둘 다 없다면 Python 설치 후 Cursor를 다시 열어 확인하세요. 패키지 설치·가상환경·외부 계정은 필요 없습니다.

개별 다운로드: submit.py · worker.py · sample.csv · 실행 안내. 세 실행 파일은 같은 폴더에 둡니다. 파일명 뒤에 .txt가 붙지 않았는지 확인하세요.

csv-worker-lab/
├─ submit.py           ← 접수하고 종료
├─ worker.py           ← 대기하면서 처리
├─ sample.csv          ← 샘플 입력
└─ jobs/               ← 실행하면 자동 생성
   ├─ inputs/          ← 접수 당시 CSV 복사본
   ├─ pending/         ← 대기 작업 JSON
   ├─ processing/      ← 처리 중 작업 JSON
   ├─ completed/       ← 완료 작업 기록
   ├─ failed/          ← 실패 기록과 원인
   └─ results/         ← 요약 리포트 JSON

참고 코드의 jobs 폴더는 스크립트가 있는 폴더를 기준으로 만듭니다. 터미널의 현재 위치가 다르더라도 기록 위치는 같지만, 실행 명령은 파일이 있는 폴더에서 입력해야 편합니다.

터미널 하나는 접수, 하나는 처리

1. Cursor Agent에 계획 요청하기

   복습 · W9·W10 새 폴더에서 아래 프롬프트를 보냅니다. submit.py와 worker.py의 역할을 확인한 뒤 “이 계획대로 만들어줘”라고 요청합니다. 참고 ZIP을 사용했다면 다음 단계로 넘어가세요.

   복사해서 Agent 채팅에 붙여넣기실습 프롬프트 복사

   이 빈 csv-worker-lab 폴더에서 CSV 요약 작업을 처리하는 실습을 만들어줘.
   먼저 파일 구조와 처리 계획을 보여주고, 내가 승인하면 구현해줘.
   
   Python 3.10 이상 표준 라이브러리만 사용해. pip 설치, 웹 서버, UI, DB는 필요 없어.
   파일은 submit.py, worker.py, sample.csv, README.md, .gitignore로 구성해.
   
   submit.py:
   - py submit.py sample.csv로 접수하고 종료.
   - 존재하는 .csv 파일인지 확인하고 고유 작업 ID 발급.
   - CSV를 jobs/inputs/작업ID.csv로 복사한 다음 jobs/pending/작업ID.json을 게시.
   - 접수 JSON: job_id, status=pending, source_file, submitted_at.
   - JSON은 임시 파일에 다 쓴 뒤 이름을 바꿔 Worker가 미완성 파일을 읽지 않게 해줘.
   
   worker.py:
   - py worker.py로 실행. 단일 Worker가 pending 작업을 접수 시각 순으로 하나씩 처리.
   - 대기 폴더는 1초마다 확인. Ctrl+C로 종료.
   - pending → processing → completed 또는 failed로 작업 JSON 이동.
   - 결과는 jobs/results/작업ID.json에 기록.
   - UTF-8 BOM도 읽고 첫 번째 비어 있지 않은 행은 헤더로 사용.
   - 헤더 이름이 비어 있거나 중복이면 실패.
   - 헤더를 제외한 row_count, columns, 열별 missing_values 집계.
   - 실제 빈 줄은 제외. 빈 셀과 공백만 있는 셀은 누락으로 계산.
   - 헤더만 있는 CSV는 0행, 빈 파일·열 개수 불일치·깨진 CSV는 실패.
   - 실패 사유를 남기고 다음 작업은 계속 처리.
   - 파일 저장 자체가 불가능하면 오류를 알리고 중단.
   - 접수 후 원본이 바뀌어도 해당 작업은 복사본으로 처리.
   - 결과와 작업 기록은 종료 후에도 남김. 자동 재시도·병렬 처리는 제외.
   - 재시작 시 남아 있는 processing 기록을 안내하되 자동 재처리하지 마.
   - 경로는 스크립트 폴더 기준으로 만들고 jobs/·__pycache__/는 Git에서 제외.
   
   sample.csv는 다음과 같이 만들어줘:
   project,owner,status
   Survey A,Mina,done
   Survey B,,pending
   Survey C,Joon,
   Survey D,"   ",done
   
   정상 결과는 4행, 누락값 project=0, owner=2, status=1.
   Cursor의 두 터미널에서 접수와 Worker를 각각 실행하는 방법을 README에 적어줘.

2. 터미널 1 · 작업 두 개 접수하기

   submit.py가 있는 폴더에서 아래 두 줄을 실행합니다. Worker는 아직 켜지 않습니다. 매번 다른 작업 ID가 출력되고, 파일 탐색기의 jobs/pending 안에 JSON 두 개가 생기면 성공입니다.

   터미널 1 · 입력 후 바로 명령줄로 돌아옴접수 명령 복사

   py submit.py sample.csv
   py submit.py sample.csv

   접수는 끝났지만 처리는 아직입니다. jobs/inputs에는 각 작업의 CSV 복사본이 있고, jobs/results는 비어 있어야 합니다.

3. 터미널 2 · Worker 시작하기

   Terminal → New Terminal로 터미널을 하나 더 만듭니다. 같은 폴더인지 확인하고 아래 명령을 실행합니다. Worker는 하나만 실행하세요.

   터미널 2 · 다음 작업을 기다리며 계속 실행Worker 명령 복사

   py worker.py

   터미널 로그 예시 · ID는 실행마다 다름

   [worker] 대기 중입니다. 다른 터미널에서 접수하세요. 종료: Ctrl+C
   [processing] 작업ID
   [completed] 작업ID -> jobs/results/작업ID.json

   대기했던 두 작업이 하나씩 처리됩니다. processing 폴더는 금방 비워질 수 있으므로 로그로도 확인하세요. 명령줄로 돌아오지 않고 멈춰 보이는 것은 다음 작업을 기다리는 정상 상태입니다.

4. Cursor에서 결과 파일 열기

   왼쪽 파일 탐색기에서 jobs → results → 작업ID.json을 엽니다. completed에는 작업 완료 기록, results에는 실제 집계 결과가 있습니다. sample.csv의 핵심 결과는 다음과 같아야 합니다.

   요약 리포트의 핵심 필드

   {
     "row_count": 4,
     "columns": ["project", "owner", "status"],
     "missing_values": {
       "project": 0,
       "owner": 2,
       "status": 1
     }
   }

   실제 결과에는 job_id·status·source_file·completed_at도 들어갑니다. 헤더는 데이터 행 수에서 빼고, Survey D의 공백만 있는 owner도 누락으로 셉니다.

5. Worker 실행 중에 새 작업 보내기

   터미널 목록에서 터미널 1로 돌아가 py submit.py sample.csv를 다시 실행합니다. 터미널 2에 새 처리 로그가 나오고 새 결과 파일이 생깁니다. 접수 프로그램을 실행할 때마다 Worker를 새로 켤 필요는 없습니다.

   종료는 터미널 2에서 Ctrl+C입니다. Worker를 끈 뒤 작업을 접수하면 pending에 남습니다. 다시 py worker.py를 실행하면 남아 있던 대기 작업을 처리하고 이전 결과도 유지됩니다.

성공과 실패를 모두 확인하기

Cursor에서 invalid.csv를 새로 만들고 다음 내용을 넣습니다. 헤더는 3열인데 데이터는 2열이라 Worker가 실패로 기록해야 합니다.

project,owner,status
Survey E,Mina

py submit.py invalid.csv
py submit.py sample.csv

invalid.csv 작업은 jobs/failed에 error를 남기고, 다음 sample.csv 작업은 완료되어야 합니다. 실패한 작업을 성공한 것처럼 처리하지 않는 것도 백엔드의 역할입니다.

막히면 이 순서로

① Python 명령이 되는지 → ② 현재 폴더에 두 .py 파일이 있는지 → ③ 접수 ID가 나왔는지 → ④ Worker 터미널이 실행 중인지 → ⑤ failed 기록의 error가 무엇인지 확인합니다.

교육용 파일 대기열의 범위 — Worker는 하나만 실행합니다. 파일 저장 자체가 안 되는 오류는 알리고 중단합니다. 운영 서비스에 필요한 병렬 처리·자동 재시도·중복 방지·접근 제어는 이번에 구현하지 않습니다. DB 없이도 파일은 남지만 여러 사용자의 검색·수정·권한을 관리하는 일은 별도 문제입니다.

다음 질문은 “누구의 작업인가?”

지금은 로컬 컴퓨터의 파일 접근 권한만 사용합니다. 앱의 로그인이나 작업 소유자 검사는 없습니다. 나중에 API로 접수와 결과 조회를 열면 누가 접수했는지, 누가 결과를 볼 수 있는지를 확인해야 합니다.

같은 Worker가 처리해도,
결과는 요청한 사람에게만 보여주려면?

HTTP 요청 자체가 이전 로그인 정보를 자동으로 이어주지는 않습니다. 20주차의 쿠키·세션·JWT는 요청에 사용자 정보를 연결하는 방법으로 이어집니다. 이번에 접수·조회 API를 이미 만들었다는 뜻은 아닙니다. API를 붙이는 단계가 먼저 필요합니다. 21주차에는 파일과 다른 DB의 검색·관리 방식을 다룹니다.

선택 과제

1. Worker를 끈 상태에서 작업을 접수하고 원본 CSV를 수정한 뒤 실행합니다. 접수 당시 복사본과 결과가 일치하는지 확인합니다.
2. 업무 규칙 하나를 추가해 보세요. 예: 전체 셀 중 누락값의 비율. 빈 데이터의 계산 기준도 먼저 정합니다.
3. Agent에 “작업 접수·CSV 집계·결과 기록을 담당하는 함수를 각각 설명해줘”라고 요청합니다.
4. 실습 코드는 개인 저장소에 기록하고 jobs/와 __pycache__/는 제외합니다. 교육자료 사이트에 파일을 올려도 Worker가 자동 실행되지는 않습니다.

공식 문서로 더 보기

• Cursor · Agent 개요
• VS Code · 통합 터미널 기본 사용법 — Cursor의 메뉴 구성은 버전에 따라 다를 수 있습니다.
• Python · csv 표준 라이브러리
• Python · json 표준 라이브러리
• Fielding · REST 아키텍처 스타일

← 18주차: 프론트엔드 뿌리 · 전체 학습 노트