Django - Project Basic Condition

참고 사이트

django test

@extend_schema

---

api 기능 구현 🔴

---

순서

• 1. ERD / 모델(Model) 먼저 확정
• 2. makemigrations / migrate
• 3. Serializer 생성 (입력용 / 출력용)
• 4. View(APIView) 설계
• 5. URL 연결
• 6. 실제 이미지 업로드 테스트
• 7. 필요 시 GET/PUT/DELETE API도 확장

---

기능 개발 순서

• 1. Spec API 작성

  • API 명세서에 작성된 Request, Response, API Endpoint 에 따라 Spec API를 작성

• 2. Spec API PR 및 Merge

  • Spec API 작성이 완료되었다면 원격 브랜치에 푸시한 후 Develop 을 Base Branch 로
    • PR을 작성 PR 작성시 템플릿 양식에 맞게 작성 ( 미준수 시 재작성 요청 )
    • PR 작성 완료 전 Reviewer 에 반드시 백엔드 코치, 담당 조교를 추가
  • PR 작성이 완료되면 조교 또는 코치의 PR Review 이후에 피드백이 반영되면 머지 진행

• 3. Spec API에 기능 추가

  • Spec API 작성이 완료되면 해당 Spec API 기능 로직을 추가하여 개발
  • 본 기능 개발 시 Request Data에 대한 Validation을 추가하고 비즈니스 로직에 따라
    • 적절한 로직을 수행한 후 응답을 반환
  • 기능 개발은 반드시 적절한 Test Code와 함께 작성되어야 하며,
    • Test Code의 수율은 Coverage 80%를 충족해야 함

• 4. 기능 추가 PR 및 Merge

  • 기능 추가가 완료되면 2번에서 진행한대로 PR 을 작성한 후 피드백 또는 머지를 기다림

---

기능 개발 주의 ⚠️

• 1. PR 작성 시 반드시 Base Branch 는 Develop으로 설정
• 2. 기능 작성 중 기존 API 명세서와 달라진 점이 있다면 명세서에 즉시 반영
• 3. @extend_schema 데코레이터를 활용하여 해당 API 에 대한
  • 구체적인 설명, Request, Response 데이터에 대해서 명확히 작성
• 4. PR이 머지되기까지 손놓고 대기하지 않고 최신 develop 브랜치로부터 분기하여
  • 새로은 Feature 브랜치를 생성한 후 다른 API에 대한 작업을 수행
• 5. API 작성 전, 후에 해결되지 않은 사항이나 헷갈리는 부분에 대해서는
  • 담당 코치, 조교에게 즉시 질문하여 해결
• 6. 기능 개발 시 발생하는 오류들에 대해서는 해결방법을 찾아보고 해결이 완료되면
  • Trouble Shooting 문서 작성 습관화

---

개발 순서

• Spec API로 API 스펙 확정

  • 프론트와 “요청/응답은 이렇게 갈 거야”를 합의
  • URL, 필드, 응답형식 확정
  • Swagger 문서 생성됨
  • 프론트는 mock API 기반으로 화면 개발 시작 가능

• 실제 API 구현 시작

  • ModelSerializer + create()로 DB 저장 구현
  • presigned URL 처리 구현 (mainproject기준)
  • QuestionImage 저장 로직 구현 (mainproject기준)
  • QuestionAIAnswer 생성 로직 구현 (mainproject기준)

• 기능 테스트(Unit Test / API Test)

  • 실제 기능이 동작하는지 검증
  • DB에 정상 저장되는지
  • 이미지 URL이 정상 저장되는지
  • 권한 체크 작동하는지

---

백엔드 PR 작성 유의사항

• 1개의 PR은 하나의 기능에 대해서 작성합니다.
  • 여러개의 기능을 하나의 PR에 담을 경우 리뷰어가 PR에 대해서 이해하기 힘들뿐 아니라
  • 코드 양이 많기 때문에 가독성이 떨어집니다.
    • PR은 반드시 PR 템플릿을 준수하여 작성합니다.
• 커밋은 최대한 자주 하되 Commit Template 을 적용하여 작성합니다.
  • ex 1) ✨Feat: 유저 모델 작성
  • ex 2) ✨Feat: 유저 회원가입 시리얼라이저 작성
  • ex 3) ✨Feat: 유저 회원가입 APIView 작성
  • ex 4) ✨Feat: 유저 회원가입 APIView URL 엔드포인트 매핑
• 커밋 템플릿 적용방법: 아래의 커맨드를 코드 에디터의 터미널에 입력합니다.
  • git config --local commit.template ./.github/commit_template.txt

---

Onboarding 🔴

1. 프로젝트 세팅

• 1-1. 프로젝트 루트 디렉터리 생성
• 1-2. Git init & Git pull
• 1-3. .env 추가하기
• 1-4. 가상환경 설정 및 의존성 패키지 설치
• 1-5. Docker 설치
• 1-6. Docker 와 Docker Compose 를 활용하여 로컬 환경에서 서버 실행하기

---

팀 별 업무 진행 방식

• 주제

  • 오즈코딩스쿨 LMS에 필요한 부가 기능을 구현 → 커뮤니티, 쪽지시험, 질의응답 등의 기능
  • 익스턴십 진행 간 조교 또는 코치진을 통해 문서를 전달받고 문서에 따라 기능을 구현

---

API 명세서, 테이블 명세서 문서 작성 순서

• Spec API

  • 실제 API처럼 동작하지만, 진짜 백엔드나 서버 없이 가짜 응답을 제공하는 테스트용 API
• 1. API 설계 시 사용자 요구사항 정의서와 디자인 피그마들을 참고하여 기능에 대해서 고민해보고 설계
• 2. API 설계가 완료되면 API 명세서 노션 템플릿을 활용하여 API 명세서를 작성
• 3. API 명세서가 작성이 완료 → 사전에 제공된 ERD를 참고하여 ORM을 사용하여 데이터베이스 모델링 구현
• 4. 모델링까지 완료되면 테이블 명세서 스프레드 시트에 해당 내용을 작성

---

프로젝트 구조 설명 🔴

• Django App Directory 생성 규칙 (oz_externship 기준)

├── .github/                # 깃허브 설정 파일 ( 커밋템플릿, 이슈템플릿, pr 템플릿, CI / CD 등 )
│   ├── COMMIT_TEMPLATE/    # 하위에 커밋 템플릿을 정의
│   ├── ISSUE_TEMPLATE/     # 하위에 이슈템플릿을 정의
│   └── workflows/          # 하위에 CI / CD 스크립트를 정의
│       ├── checks.yml/     # develop 또는 main 브랜치에 Push 또는 PR Merge 시 데이터 베이스 연결 확인, 코드 포매팅 체크, 테스트 통과 여부를 검사하는 스크립트
│       ├── dev_deploy.yml/ # develop 브랜치에 Push시 개발 서버에 배포 자동화를 구현한 스크립트
│       └── prod_deploy.yml/ # develop 브랜치에 Push시 개발 서버에 배포 자동화를 구현한 스크립트
├── config/                 
│   ├── __init__.py
│   ├── settings/
│   │   ├── base.py         # 프로젝트 전역 공통 설정 파일
│   │   ├── dev.py          # 개발 서버 프로젝트 전역 설정 파일
│   │   ├── local.py        # 로컬 환경 프로젝트 전역 설정 파일
│   │   └── prod.py         # 프로덕션 환경 프로젝트 전역 설정 파일
│   ├── asgi.py
│   ├── urls.py
│   └── wsgi.py
├── apps/                   # 앱 디렉토리 (앱별로 디렉토리를 나눔)
│   ├── core/               # 공통 앱 (공통으로 사용되는 utils, base 모델, commands 정의)
│   │   ├── commands/       # 장고 커맨드 등록 폴더
│   │   ├── utils/          # 프로젝트 전역에서 공통으로 사용되는 유틸 함수를 정의하는 폴더
│   │   ├── tests/          # core 내에 정의된 util 메서드 혹은 클래스에 대한 테스트들을 구현하는 폴더
│   │   └── models.py       # 모든 앱에서 공통으로 사용되는 base 모델 정의 (ex. TimeStampModel)
│   ├── app_name1/
│   │   ├── migrations/     # 마이그레이션 파일
│   │   ├── services/       # 앱에서 사용되는 서비스 로직을 구현하는 폴더 / 서비스 로직
│   │   ├── tests/          # 앱에서 사용되는 테스트들을 구현하는 폴더
│   │   ├── models/         # 앱에서 사용되는 모델들을 정의하는 폴더
│   │   ├── urls/           # 앱 전용 URL 라우팅을 정의하는 폴더
│   │   ├── serializers/    # 시리얼 라이저 모음 폴더
│   │   ├── views/          # CBV, FBV 를 구현하는 폴더 / HTTP 호출 관련
│   │   └── apps.py         # 앱 설정
│   ├── app_name2/          # 다른 앱
│   │   ├── migrations/     # 마이그레이션 파일
│   │   ├── services/       # 앱에서 사용되는 서비스 로직을 구현하는 폴더 / 서비스 로직
│   │   ├── tests/          # 앱에서 사용되는 테스트들을 구현하는 폴더
│   │   ├── models/         # 앱에서 사용되는 모델들을 정의하는 폴더
│   │   ├── urls/           # 앱 전용 URL 라우팅을 정의하는 폴더
│   │   ├── serializers/    # 시리얼 라이저 모음 폴더
│   │   ├── views/          # CBV, FBV 를 구현하는 폴더
│   │   └── apps.py         # 앱 설정
│   └── ...
├── envs/                   # 환경변수 파일들
│   ├── .local.env          # 로컬 환경에서 서버 구동 및 테스트 시 필요한 환경변수
│   ├── .dev.env            # 개발 서버 환경에서 서버 구동 및 테스트 시 필요한 환경변수
│   └── .prod.env           # 배포 환경에서 서버 구동 및 테스트 시 필요한 환경변수
├── resources/              # 초기 설정 파일 및 스크립트, nginx, docker, kubernetes 의 yaml 파일
│   ├── nginx/
│   │   ├── Dockerfile       # nginx 이미지 빌드 도커 파일
│   │   └── nginx.local.conf # 로컬 환경에서 테스트 용 nginx 설정 파일
│   │   └── nginx.dev.conf   # 개발 서버 환경에서 테스트 용 nginx 설정 파일
│   │   └── nginx.prod.conf  # 프로덕션 서버 환경에서 테스트 용 nginx 설정 파일
│   └── scripts/             # 필요한 shell scripts를 모아두는 디렉터리 (test, formatter, create_dummy 등)
│       ├── code_formatting.sh   # black, isort 코드 포매팅 실행 스크립트
│       └── test.sh              # mypy 타입 검사 수행 및 전체 테스트코드 실행 시 사용되는 스크립트
├── manage.py                  # Django 실행 파일
├── poetry.lock                # poetry 의존성 패키지 설치 정보
├── pyproject.toml             # poetry 의존성 패키지 목록 및 설정
├── dockerfile                 # 도커 이미지 빌드 파일
├── docker-compose.local.yml   # 로컬 환경 테스트 용 도커 컨테이너 정의 파일
└── README.md                  # 프로젝트 소개서

• 앱은 각 도메인 별로 구분하여 생성하며, app name은 snake case 를 적용

• 기능 별 구분 도메인 → App name

  • 사용자 및 권한 관리 → users | 인증 및 로그인 → auth | 강의 → lectures
  • 스터디 그룹 → studies | 그룹 스케줄 → schedules | 학습 기록 → study_notes
  • 구인 공고 → recruitments | 공고 지원 → applicaitons | 채팅 → chat
  • 알림 → notificaitons

---

Code Formatting 🔴

• 현재 세팅된 프로젝트에서는 black, isort, mypy를 사용하여 코드 포매팅과 타입 어노테이션 준수를 확인
  • 이를 통해 코드의 정적 품질 관리 체계를 구축 가능

mypy

• mypy는 정적 타입 검사기

• Python 코드에서 타입 힌트를 이용해 오류를 사전에 잡는 도구

• 사용하는 이유

  • 런타임 전에 타입 관련 오류를 잡을 수 있음
  • 협업 시 함수 인자나 리턴 타입의 명시로 코드 가독성 향상
  • 코드 리팩토링 시 타입 안정성 확보

  def add(x: int, y: int) -> int:
      return x + y
  
  add("1", "2")  # mypy는 여기서 오류 발생 (str 대신 int가 필요)

  • stubs를 사용하여 동적 타입도 처리 가능

isort

• import 정렬 도구

• Python 코드에서 import 구문을 자동으로 정렬해주는 도구

• 사용하는 이유

  • import 순서를 일관되게 유지
  • 중복 import나 잘못된 순서 방지
  • 팀 협업 시 merge conflict 줄일 수 있음

  - 1. 자동 정렬 전
  import sys
  import os
  from django.conf import settings
  import datetime
  
  - 2. 자동 정렬 후 
  import datetime
  import os
  import sys
  
  from django.conf import settings

black

• 자동 코드 포매터

• Python 코드를 PEP8 스타일 가이드에 맞게 자동으로 정리해주는 도구

• 사용하는 이유

  • 코드 스타일 논쟁 제거 (포맷팅을 자동화)
  • 일관된 코드 스타일 유지
  • PR 리뷰에서 스타일 관련 지적 줄이기

  - 1. 정리 전
  def hello(name): print("Hello, " + name)
  
  - 2. 정리 후(black 적용)
  def hello(name):
      print("Hello, " + name)

CI / CD 파이프라인

• PR시 자동으로 black, isort, mypy를 이용하여 코드 포맷과 타입 어노테이션을 검사
• 기능 개발이 완료되고 Push 하기 전
  • 반드시 프로젝트 루트디렉터리/resources/scripts 디렉터리에 위치한
  • code_formatting.sh 파일을 실행하여 코드 포맷을 일관되게 유지하고,
  • mypy 정적 타입 검사를 통해 올바른 타입을 명시했는지 체크 필요

---