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은 자동 선택하지 않습니다.
SPRING_PROFILES_ACTIVE=local ./gradlew bootRun
- API: http://127.0.0.1:8080/api/v1
- Swagger UI: http://127.0.0.1:8080/swagger-ui.html
- OpenAPI: http://127.0.0.1:8080/v3/api-docs
- Health: http://127.0.0.1:8080/actuator/health
- Readiness: http://127.0.0.1:8080/actuator/health/readiness
- H2 console: http://127.0.0.1:8080/h2-console
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/local/
semesters.tsv
professors.tsv
subjects.tsv
users.tsv
lessons.tsv
schedules.tsv
데이터가 늘어나면 TSV 행을 추가합니다. DataSeeder는 파일을 읽고 관계를 조립하는 역할만 합니다.
local 데이터셋의 학기/신청기간은 넓은 고정 범위로 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
- 같은 사용자 + 같은 key + 같은 lesson 재시도 → 최초 201 결과 재사용
- 같은 사용자 + 같은 key + 다른 lesson → 409 IDEMPOTENCY_KEY_REUSED
- DELETE는 이미 취소된 건을 다시 취소해도 204
Concurrency invariant
mutation 경로는 한 곳에서 아래 순서로 lock을 획득합니다.
User FOR UPDATE
-> Lesson FOR UPDATE
-> R1~R8 검증
-> INSERT / cancel
RegistrationLockManagerTest가 User -> Lesson 호출 순서를 직접 검증하고, ArchitectureTest가 신청 서비스에서 LessonRepository를 직접 우회하지 못하도록 고정합니다.
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)
-> thenAccepted / thenRejectedWith
fixture는 support/fixture에 모읍니다.
- DomainFixtures: 순수 도메인 객체
- DatabaseFixture: DB에 저장된 테스트 데이터셋
- TestFixtureConfig: 고정 Clock
- PostgresIntegrationTest: PostgreSQL Testcontainers 기반 통합 테스트
주요 테스트:
-
controller HTTP status/JSON 계약
-
service 신청/취소/조회
-
repository 학기 scope/집계/DB unique
-
domain entity invariant
-
R1~R8 우선순위/경계값
-
N+1 방지 쿼리 수 상한
-
PostgreSQL 동시성
- 정원 1 / 동시 10명
- 정원 30 / 동시 50명
- 동일 학생 학점 경쟁
- 동일 학생 시간표 경쟁
- 동일 학생 동일 강의 경쟁
-
Seeder 재실행
-
락 순서 / 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에 저장됩니다.