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
- 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/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
Concurrency invariant
mutation 경로는 한 곳에서 아래 순서로 lock을 획득합니다.
User FOR UPDATE
-> Lesson FOR UPDATE
-> R1~R8 검증
-> INSERT / cancel
RegistrationLockManagerTest가 User -> Lesson 호출 순서를 직접 검증하고, ArchitectureTest가 신청 서비스에서 LessonRepository를 직접 우회하지 못하도록 고정합니다.
Master data policy
현재 API에는 Semester/Subject/Professor/Lesson/User를 수정하는 마스터 CRUD가 없습니다. 신청 transaction은 User → Lesson을 락 쿼리로 처음 읽는 것을 전제로 하므로, 런타임 마스터 수정 기능을 추가할 때는 같은 transaction 안에서 어떤 값을 최신으로 보장할지 다시 설계해야 합니다.
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 계약
-
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에 저장됩니다.