2026-09-16 14:20:39 +09:00

course-registration

Spring Boot 4.1.1 / Java 21 기반 수강신청 API입니다. 핵심은 CRUD 개수보다 수강신청 거부 규칙(R1~R8)과 동시 신청 시 정원·학점·시간표 정확성을 지키는 것입니다.

Scope

  • 수강신청(Create)
  • 내 신청 / 강의 목록·상세(Read)
  • 수강취소(Delete, soft cancel)
  • 신청 수정(Update) 없음 — 취소 후 재신청
  • 마스터 데이터 CRUD 없음
  • 인증/JWT 없음
  • k6 부하 테스트는 후속 범위

상세 규칙은 docs/Requirements.md를 기준으로 합니다.

Local

profile은 자동 선택하지 않습니다. 런타임에서는 local/dev/prod 중 정확히 하나만 허용하고, 테스트에서는 test profile만 사용합니다.

SPRING_PROFILES_ACTIVE=local ./gradlew bootRun

profile이나 DB 설정이 빠진 상태로 조용히 H2를 사용하는 것을 막기 위해 공통 설정에는 기본 profile을 두지 않습니다.

Dev with PostgreSQL

cp .env.example .env
docker compose up --build

Compose는 host에 127.0.0.1로만 노출합니다.

docker compose down
docker compose down -v

Database schema

모든 profile의 Hibernate 설정은 ddl-auto=validate입니다. 스키마 변경은 Flyway migration으로만 관리합니다.

src/main/resources/db/migration/
  h2/
  postgresql/

주요 DB 방어선:

  • user_lessons: 유효 신청 (user_id, active_lesson_id) unique
  • 수강신청 조회용 인덱스
  • 학점/정원/학년/시간 범위 CHECK
  • lesson_schedules exact duplicate unique
  • optimistic @Version

Profiles

profile DB Schema Seeder Swagger
local H2 Flyway + validate ON ON
dev PostgreSQL Flyway + validate APP_SEED_ENABLED ON
prod PostgreSQL Flyway + validate OFF 기본 OFF

Seed dataset

seed 데이터는 Java 코드에 하드코딩하지 않습니다.

src/main/resources/seed/demo/
  semesters.tsv
  professors.tsv
  subjects.tsv
  users.tsv
  lessons.tsv
  schedules.tsv

데이터가 늘어나면 TSV 행을 추가합니다. DataSeeder는 파일을 읽고 관계를 조립하는 역할만 합니다.

demo 데이터셋의 학기/신청기간은 넓은 고정 범위로 TSV에 명시하므로 DB 볼륨을 오래 유지해도 부팅 시점에 따라 만료되지 않습니다.

동시에 여러 인스턴스가 seed를 시도해도 seed_locks row를 FOR UPDATE로 잠근 뒤 실행하므로 중복 seed를 직렬화합니다.

API

POST   /api/v1/users/{userId}/registrations
GET    /api/v1/users/{userId}/registrations?semesterId={semesterId}
DELETE /api/v1/users/{userId}/registrations/{registrationId}
GET    /api/v1/lessons?semesterId={id}&subjectId={id}&page=0&size=20
GET    /api/v1/lessons/{lessonId}

Idempotent registration

POST는 선택적으로 Idempotency-Key 헤더를 받습니다.

Idempotency-Key: registration-request-001
  • 보존 기간은 24시간이다.
  • TTL 안에서 같은 사용자 + 같은 key + 같은 lesson 재시도 → 최초 201 결과 재사용
  • 최초 신청을 이후 취소했더라도 TTL 안의 같은 key 재시도는 새 신청을 만들지 않고 최초 POST 결과를 replay
  • TTL 안에서 같은 사용자 + 같은 key + 다른 lesson → 409 IDEMPOTENCY_KEY_REUSED
  • 만료 행은 주기적으로 정리하고, 만료된 key는 새 요청에서 다시 사용할 수 있다.
  • DELETE는 이미 취소된 건을 다시 취소해도 204

Architecture

런타임 경계는 다음 방향으로만 의존합니다.

Web Controller / DTO / FailureHttpMapper
  -> Application UseCase / Query
    -> Domain Policy / ordered RegistrationRule
      -> Application Port
        -> Infrastructure JPA Adapter
          -> Spring Data Repository

application action은 RegisterCourseUseCase, CancelRegistrationUseCase, GetRegistrationsQuery, GetLessonsQuery, GetLessonQuery, CleanupIdempotencyUseCase로 분리합니다.

수강신청 정책은 RegistrationContext를 입력으로 받고 RegistrationPolicy가 R1~R8의 관측 가능한 우선순서를 명시적인 ordered rule list로 유지합니다. Application은 Spring Data JPA repository, @Lock, Page, projection 구현을 알지 않습니다.

실패도 의미에 따라 분리합니다.

  • ApplicationFailure: resource not found / business rejection / authorization / request validation / retryable infrastructure
  • SystemInvariantViolation: 중복 활성 학기, 필수 시간표 누락 등 사용자 재시도로 해결되지 않는 invariant 위반
  • HTTP status는 RegistrationErrorCode가 아니라 Web의 FailureHttpMapper가 결정
  • business rejection은 ERROR stacktrace를 남기지 않고 metric으로 집계
  • retryable failure는 WARN, system invariant와 unexpected failure는 ERROR

Concurrency invariant

mutation 경로는 한 곳에서 아래 순서로 lock을 획득합니다.

User FOR UPDATE
  -> Lesson FOR UPDATE
    -> R1~R8 검증
      -> INSERT / cancel

JpaRegistrationContextLoader가 User → Lesson 순서로 실제 row lock을 획득합니다. 해당 context loader 테스트가 순서를 직접 검증하고, ArchitectureTest는 application/domain/web이 persistence 경계를 우회하지 못하도록 고정합니다.

Master data policy

현재 API에는 Semester/Subject/Professor/Lesson/User를 수정하는 마스터 CRUD가 없습니다. 신청 transaction은 User → Lesson을 락 쿼리로 처음 읽는 것을 전제로 합니다.

운영 규칙은 수강신청 기간 동안 판정에 사용되는 master policy data를 수정하지 않는다입니다. 대상은 최소한 Subject.credit, Semester.maxCredits, Semester.registrationStartAt/registrationEndAt, Lesson.capacity/minGrade/allowedRole, LessonSchedule입니다. 향후 관리자 수정 기능을 추가할 때는 이 freeze 규칙과 일관된 snapshot 보장 방식을 함께 재설계해야 합니다.

ID는 현재 Java에서 String UUID, DB에서 VARCHAR(36)을 유지합니다. PostgreSQL native uuid 전환은 API/JPA 타입과 H2/PostgreSQL migration을 함께 바꾸는 별도 스키마 변경으로 분리합니다.

Local seed IDs

Semester
00000000-0000-0000-0000-000000000001

1학년 학생
30000000-0000-0000-0000-000000000001

2학년 학생
30000000-0000-0000-0000-000000000002

대학원생
30000000-0000-0000-0000-000000000003

자료구조 01분반
40000000-0000-0000-0000-000000000001

자료구조 02분반
40000000-0000-0000-0000-000000000002

운영체제
40000000-0000-0000-0000-000000000003

정원 1명 강의
40000000-0000-0000-0000-000000000004

최소 3학년 강의
40000000-0000-0000-0000-000000000005

대학원생 전용 강의
40000000-0000-0000-0000-000000000006

시간 경계 테스트 강의
40000000-0000-0000-0000-000000000007

Test structure

src/test/java/com/study/course_registration/
  controller/
  service/
  repository/
  entity/
  architecture/
  support/
    fixture/
    http/

support/Scenario의 흐름을 계층에 관계없이 재사용합니다.

given(fixture)
  -> when(action) / whenRunning(action)
  -> then(assertions) / thenRejectedWith

fixture는 support/fixture에 모읍니다.

  • DomainFixtures: 순수 도메인 객체
  • DatabaseFixture: DB에 저장된 테스트 데이터셋
  • TestFixtureConfig: 고정 Clock
  • PostgresIntegrationTest: PostgreSQL Testcontainers 기반 통합 테스트

주요 테스트:

  • controller HTTP status/JSON 계약

  • application UseCase/Query 신청·취소·조회

  • repository 학기 scope/집계/DB unique

  • domain entity invariant

  • R1~R8 우선순위/경계값

  • N+1 방지 쿼리 수 상한

  • PostgreSQL 동시성

    • 정원 1 / 동시 10명
    • 정원 30 / 동시 50명
    • 동일 학생 학점 경쟁
    • 동일 학생 시간표 경쟁
    • 동일 학생 동일 강의 경쟁
  • Seeder 재실행

  • context loader의 User → Lesson 락 순서 / architecture rule

    ./gradlew test ./gradlew jacocoTestReport ./gradlew build

JaCoCo HTML은 build/reports/jacoco/test/html/index.html에서 확인합니다.

Postman

postman/
  course-registration.postman_collection.json
  local.postman_environment.json
  dev.postman_environment.json

Register lesson 성공 응답의 registrationId는 environment에 저장됩니다.

S
Description
No description provided
Readme
470 KiB
Languages
Java 99.8%
Dockerfile 0.2%