URL 설계

URL 설계는 백엔드 개발의 첫 번째 단계입니다. 사용자가 어떤 주소로 접속하면 어떤 화면이 나오는지를 정하는 것이죠. 잘 설계된 URL은 직관적이고, 확장하기 쉬우며, AI도 이해하기 쉽습니다. 다만 이 책에서 URL 설계는 여러분이 손으로 그리는 문서가 아닙니다. Code 탭에 시켜서 받아 보고, 화면이 빠졌거나 많은지 눈으로 확인하는 검토 대상입니다. 이번 챕터에서는 URL이 무엇인지, 어떤 원칙으로 만들어지는지, 그리고 Claude에게 어떻게 시키고 무엇을 확인하는지를 다룹니다.

1. URL이란

URL(Uniform Resource Locator)은 웹에서 특정 자원의 위치를 나타내는 주소입니다. 쉽게 말해 "이 주소로 오면 이것을 보여줄게"라는 약속입니다.

https://example.com/blog/posts/1

위 URL을 분해하면 다음과 같습니다.

https://: 통신 방식 (프로토콜)
example.com: 서버 주소 (도메인)
/blog/posts/1: 서버 내 자원의 경로 (설계 대상)

백엔드 개발에서 URL 설계란 바로 이 '경로' 부분을 어떻게 구성할지 정하는 것입니다. 5장에서 도메인을 다뤘으니 앞 두 부분은 이미 익숙하실 것입니다.

2. RESTful URL 설계 원칙

REST(Representational State Transfer)는 웹 API를 설계하는 대표적인 방법론입니다. 복잡한 이론은 생략하고, 꼭 알아야 할 핵심 원칙만 설명하겠습니다. 이 원칙을 몰라도 괜찮아요. Claude가 알아서 이 원칙대로 설계하니까요. 다만 어떤 원칙들이 있는지 알아두면 Claude가 만든 URL 목록을 봤을 때 "이상한데?"를 알아차릴 수 있습니다.

2.1 명사를 사용하세요

URL에는 동사가 아닌 명사를 사용합니다. 행동(동사)은 HTTP 메서드로 표현합니다.

# 좋은 예
GET /posts          # 게시글 목록 조회
GET /posts/1        # 1번 게시글 조회
POST /posts         # 게시글 생성
PUT /posts/1        # 1번 게시글 수정
DELETE /posts/1     # 1번 게시글 삭제

# 나쁜 예
GET /getPosts
POST /createPost
POST /deletePost/1

여기서 GET, POST, PUT, DELETE는 HTTP 메서드입니다. 각각 '조회', '생성', '수정', '삭제'를 의미합니다. 더 세부적인 내용은 이 책에서 다루지 않습니다.

이렇게 간단하게 설명하는 이유는, 우리는 '화면' 단위로만 생각하더라도 AI가 RESTful하게 설계해주기 때문입니다. AI에게 URL 설계를 요청할 때, HTTP 메서드까지 함께 요청하지 않아도 됩니다. 그런 메서드가 오히려 SW를 배우지 않은 사람에게는 혼란을 줄 수 있기 때문에, 처음에는 화면 목록에만 집중하는 것이 좋습니다.

2.2 복수형을 사용하세요

자원의 이름은 복수형으로 작성합니다. /post보다 /posts가 일관성 있고 직관적입니다.

/users              # 사용자들
/products           # 상품들
/orders             # 주문들
/comments           # 댓글들

2.3 계층 구조를 표현하세요

자원 간의 관계는 URL 경로로 표현합니다.

/users/1/posts          # 1번 사용자의 게시글들
/posts/1/comments       # 1번 게시글의 댓글들
/shops/1/products       # 1번 상점의 상품들

2.4 소문자와 하이픈을 사용하세요

URL은 소문자로 작성하고, 단어 사이는 하이픈(-)으로 연결합니다.

# 좋은 예
/user-profiles
/product-categories

# 나쁜 예
/userProfiles
/User_Profiles

3. Claude에게 URL 설계 시키기

AI를 활용하면 URL 설계를 빠르게 시작할 수 있습니다. 아래 프롬프트를 참고하세요. 여기서 RESTful URL 설계 원칙을 반영해달라고 요청하지 않았는데요. AI가 이미 그 원칙들을 준수하여 URL을 설계하기 때문입니다. GET, POST 같은 HTTP 메서드도 함께 설계해달라고 요청하지 않았는데, AI가 자연스럽게 함께 제안합니다.

3.1 기본 프롬프트

Code 탭에서 작업 폴더를 지정하고 아래처럼 요청합니다. 설계 결과를 파일로 남겨 달라고 한 것이 포인트입니다. 대화창에만 남으면 다음에 찾기 어렵습니다.

나는 [서비스 종류]를 만들려고 해.
주요 기능은 다음과 같아:
- [기능 1]
- [기능 2]
- [기능 3]

Django 기반으로 URL을 설계해줘.
이번 단계에서는 화면 단위의 URL만 설계하고, 아직 코드는 만들지 마.
결과는 표로 정리해서 설계.md 파일로 저장해줘.

3.2 블로그 서비스 예시

나는 개인 블로그를 만들려고 해.
주요 기능은 다음과 같아:
- 게시글 작성, 수정, 삭제
- 게시글 목록 보기
- 게시글 상세 보기
- 카테고리별 게시글 필터링
- 댓글 작성, 삭제

Django 기반으로 URL을 설계해줘.
이번 단계에서는 화면 단위의 URL만 설계하고, 아직 코드는 만들지 마.
결과는 표로 정리해서 설계.md 파일로 저장해줘.

AI는 다음과 같은 설계를 제안할 것입니다.

URL	기능
`/posts/`	게시글 목록 화면
`/posts/<int:id>/`	게시글 상세 화면
`/posts/new/`	게시글 작성 화면
`/posts/<int:id>/edit/`	게시글 수정 화면
`/categories/`	카테고리 목록 화면
`/categories/<int:id>/posts/`	특정 카테고리의 게시글 목록 화면

3.3 무엇을 확인하나

이 표를 받았을 때 여러분이 할 일은 코드를 검토하는 것이 아니라 화면 목록을 검토하는 것입니다. 아래 세 가지만 보면 됩니다.

빠진 화면이 있는가: 위 표에는 댓글 화면이 없습니다. 댓글은 게시글 상세 화면 안에 들어가는지, 따로 화면이 필요한지 물어보면 됩니다. "댓글은 어디서 쓰는 거야?"라고 되물으세요.
필요 없는 화면이 있는가: 요청하지 않은 화면이 끼어 있다면 지워 달라고 합니다. 화면 하나가 늘어나면 그만큼 관리할 것이 늘어납니다.
이름이 내 말과 같은가: 여러분은 '글'이라고 부르는데 Claude는 articles와 posts를 섞어 쓰고 있다면 하나로 통일해 달라고 합니다. 이름이 흔들리면 나중에 수정을 요청할 때 서로 다른 것을 가리키게 됩니다.

3.4 쇼핑몰 서비스 예시

나는 간단한 쇼핑몰을 만들려고 해.
주요 기능은 다음과 같아:
- 상품 등록, 수정, 삭제 (관리자)
- 상품 목록 보기
- 상품 상세 보기
- 장바구니 담기, 빼기
- 주문하기
- 주문 내역 보기

Django 기반으로 URL을 설계해줘.
이번 단계에서는 화면 단위의 URL만 설계하고, 아직 코드는 만들지 마.
결과는 표로 정리해서 설계.md 파일로 저장해줘.

4. URL 설계 시각화

URL 설계는 시각적으로 정리하면 전체 구조를 한눈에 파악할 수 있습니다. Mermaid 다이어그램을 활용하면 좋습니다. Code 탭에 "설계.md의 URL 구조를 Mermaid 다이어그램으로도 그려서 같은 파일에 넣어줘"라고 하면 됩니다. AI를 위한 것이 아닙니다. 여러분을 위한 것입니다. 표보다 그림이 빠진 화면을 찾기 쉽습니다.

4.1 블로그 URL 구조

4.2 쇼핑몰 URL 구조

5. Django URL 패턴 이해하기

Claude가 만든 표에는 <int:id>나 <slug:slug> 같은 표현이 보입니다. 이것은 Django의 URL 패턴 문법으로, "이 자리에 특정 타입의 값이 들어온다"는 의미입니다. 각 패턴이 무엇을 의미하는지 알아두면 표를 읽을 수 있습니다. 첫 번째가 타입이며, 두 번째가 이름입니다.

5.1 자주 사용하는 URL 패턴

패턴	설명	URL 예시
`<int:id>`	정수(숫자)를 받습니다	`/posts/1/`, `/posts/42/`
`<int:pk>`	정수를 받습니다 (pk는 primary key의 약자)	`/users/1/`, `/products/100/`
`<slug:slug>`	영문, 숫자, 하이픈으로 된 문자열을 받습니다	`/posts/my-first-post/`
`<str:username>`	일반 문자열을 받습니다	`/users/hong/`, `/users/kim/`

5.2 패턴 읽는 방법

패턴은 <타입:이름> 형식입니다.

타입: 어떤 종류의 값을 받을지 (int, slug, str 등)
이름: 그 값을 부르는 이름 (id, pk, slug 등)

/posts/<int:id>/edit/

위 URL은 "posts 다음에 숫자가 오고, 그 숫자를 id라고 부르겠다. 그 뒤에 edit이 온다"라는 의미입니다. 실제로는 /posts/1/edit/, /posts/99/edit/ 같은 주소와 매칭됩니다.

5.3 실제 예시로 이해하기

/posts/                     → 게시글 목록 (고정된 경로)
/posts/<int:id>/            → 특정 게시글 (숫자에 따라 다른 게시글)
/posts/new/                 → 게시글 작성 (고정된 경로)
/posts/<int:id>/edit/       → 특정 게시글 수정 (숫자에 따라 다른 게시글)
/categories/<int:id>/posts/ → 특정 카테고리의 게시글들

new나 edit처럼 고정된 단어는 그대로 쓰고, 변하는 값(게시글 번호, 카테고리 번호 등)은 <int:id> 같은 패턴으로 표현합니다. 여기까지 읽을 수 있으면 URL 표를 검토하는 데 부족함이 없습니다.