Files
clean-architecture-backend-…/docs/mongodb/query-aggregation-guide.md
T
DongHyeonka 24eb1be36d docs(mongodb): MongoDB 운영 문서를 한국어로 옮기고 코드와 맞춘다
문제: docs/mongodb 아래 살아 있는 문서 14개가 영어였고(문서 검사 language
예외), 몇 가지 주장이 지금 코드와 달랐다.
- repository-adaptation.md가 registry의 leaf 수(19)와 Spring Boot 버전을 옮겨
  적었다(number 예외 두 줄).
- 같은 문서와 advanced/signoff/README.md가 scripts/verify-mongodb-platform.sh·
  verify-mongodb-advanced.sh를 2026-08-15에 지웠다고 했다. 두 스크립트는 지금도
  있고 lane을 돌린다.
- testkit을 `testkit` source set에 둔다고 했다. 지금은 `testFixtures`(ADR-BUILD-001)와
  `mongoProviderTestkit`이다. `…mongo.architecture`도 main이 아니라 testFixtures에 있다.
- ArchUnit 규칙 이름 `stableNeverDependsOnAdvanced`·`productionNeverDependsOnTestkit`은
  없다. 실제는 MongoModuleBoundaryTest의 `noStablePackageDependsOnAnAdvancedCapability`·
  `noProductionPackageDependsOnTheTestkit`이다.
- support-matrix.md의 Boot·Spring Data·driver·Micrometer·Testcontainers 버전이
  lockfile과 달랐다(예: driver 5.6.1 → 5.6.5).
- consumer-leaf-guide.md가 템플릿에 없는 Gradle 경로를 인라인 코드로 적었다
  (reference 예외).
- document-modeling-guide.md가 타입 metadata를 bson-mapping-guide §4로 가리켰다(§5).

고친 방법: 뜻을 그대로 옮기고 식별자·명령·경로·표 구조는 원문으로 둔다. 버전과
leaf 수는 숫자 대신 정본(src/gradle/libs.versions.toml, registry, gradle.lockfile,
container-images.properties)을 가리킨다. 서비스가 만들 leaf의 확인 명령은 다른
단계와 같이 코드 블록에 두고 템플릿에 없는 경로라고 밝힌다.

버린 대안: support-matrix 버전을 lockfile 값으로 고쳐 적기. 다음 업그레이드에서 다시
틀리고, 같은 시간에 도는 의존성 세션과 같은 줄을 고치게 된다.

위험·한계: 내용 감사는 하지 않았다. 번역하며 본 불일치만 고쳤다. 설계 번호(§, D-xx)는
그대로 두었다.

검증: python3 scripts/check-docs.py rc=0(이 폴더 language·reference·number 예외 줄 0).
docs/mongodb를 읽는 테스트는 주석뿐이다(`grep -rn 'docs/mongodb' src --include=*.java`
— package-info.java·MongoModuleBoundaryTest 주석). scripts/verify-mongodb-advanced.sh는
advanced 문서의 파일 존재만 본다.
2026-11-07 17:29:57 +09:00

6.0 KiB

Query와 aggregation 가이드

설계서 §17–§19, 결정 D-11. 모든 query와 모든 pipeline은 등록하고 상한을 둔 것이어야 한다. 자유 형식 JSON query와 상한 없는 pipeline은 명시적으로 지원하지 않는다(§3.4).

1. 등록한 연산

모든 실행은 MongoOperationContext를 가진다: MongoOperationName, DatabaseProfileName, CollectionProfileName, MongoOperationType, MongoOperationScope.

MongoOperationName은 [a-z][a-z0-9.-]{2,95}에 맞아야 한다. 이 이름이 예산 registry, 일관성 registry, metric tag, 로그 줄을 잇는 key다. 자유 형식이나 값을 끼워 넣은 이름은 넷을 한꺼번에 깨뜨린다. 그래서 생성할 때 패턴을 강제한다.

MongoOperationScope는 null 대신 UNSPECIFIED 표시값을 쓴다. 「호출자가 말하지 않았다」가 아래에서 터지는 NPE가 아니라 정책 계층이 거부할 수 있는 값이 된다.

2. Query 보호 장치

PolicyAwareMongoQueryBuilder는 MongoFieldDescriptor + MongoOperator 쌍으로 MongoQueryPolicy에 맞춰 query를 만든다. 정책이 거부하는 것:

  • collection 허용 목록에 없는 필드
  • 그 필드에 허용하지 않은 operator
  • index 없는 필드의 정렬
  • $where, 임의 JavaScript를 쓰는 $expr, 그리고 서버 쪽 평가 전반
  • 상한 없는 $regex

MongoRegexPolicy는 앞을 고정한 prefix 패턴을 요구하고 패턴 길이에 상한을 둔다. 앞을 고정하지 않은 regex는 index를 쓰는 척하는 collection 전체 scan이고, 사용자가 넣은 regex는 서비스 거부 공격의 재료다.

MongoSortDescriptor는 필드와 방향을 짝짓고 index manifest와 대조한다. 디스크로 넘칠 정렬은 운영이 아니라 검토에서 실패한다.

3. 연산 예산

MongoOperationBudget은 네 가지를 한꺼번에 제한한다.

상한 이유
maxTimeMS 아무도 기다리지 않는 query를 서버가 멈춘다.
결과 개수 상한 상한 없는 결과는 단계가 몇 개 더 붙은 OOM이다.
batch 크기 왕복 한 번의 메모리를 제한한다.
검사한 문서 수 상한 빠른 날에는 시간 상한만으로 숨겨지는 index 회귀를 잡는다.

MongoBudgetPolicyRegistry가 예산을 연산 이름에 묶는다. MongoBudgetEnforcer가 그것을 적용한다. 요청이 예산을 넘으면 실행 전에 MongoOperationRejectedException을 던지고, 서버가 상한을 집행하면 MongoTimeoutException이 난다.

4. Keyset 페이지 나누기

상한 없는 skip은 지원하지 않는다. skip(1_000_000)은 서버가 버릴 문서 백만 개를 훑게 한다. 그래서 1000쪽은 1쪽의 천 배가 든다.

MongoKeysetQueryBuilder는 이어 읽기 조건을 사전순으로 만든다. (a DESC, _id DESC) 정렬에서 (A, I) 다음부터 읽으면 이렇다.

(a < A) OR (a = A AND _id < I)

validate()는 유일한 동률 처리 기준이 없는 MongoKeysetSort를 거부한다. 기준이 없으면 정렬 값이 같은 두 문서가 페이지 경계에 걸쳐 하나가 빠지거나 두 번 나온다. 눈에 띄지 않고, 동시 요청이 있을 때만 생긴다.

MongoNullSortOrdering은 null의 위치를 명시한다. 필드 없음, null, 값 있음에 대한 MongoDB 자체 정렬 순서는 대부분이 짐작하는 것과 다르다.

Cursor는 인증한다

MongoKeysetCursorCodec은 cursor에 HMAC-SHA256 서명을 하고 MessageDigest.isEqual(일정 시간 비교)로 비교한다. 서명 없는 cursor는 client가 조종하는 query 조건이다. 호출자가 그것을 고쳐 받은 적 없는 범위를 읽을 수 있다. 고치거나 잘린 cursor는 MongoCursorException이 되고, 반쯤 해석한 이어 읽기 위치가 되지 않는다.

5. Aggregation 보호 장치

MongoAggregationPlan은 등록한 pipeline이다. MongoAggregationStageDescriptor의 순서 있는 목록이고 MongoAggregationProfile과 대조한다. PolicyAwareMongoAggregationExecutor는 등록한 plan만 돌린다.

MongoAggregationRisk가 stage마다 위험 등급을 매기고, profile이 허용 상한을 정한다.

위험 Stage 정책
low index 앞부분에 대한 $match, $limit, $project 늘 허용한다.
moderate $group, index 있는 $sort, 상한 있는 $unwind 예산 안에서 허용한다.
high $lookup, $graphLookup, $facet, index 없는 $sort profile의 명시적 승인이 필요하다.
forbidden admin plane 밖의 $out·$merge, $function, $accumulator 거부한다.

allowDiskUse는 실행 중 flag가 아니라 plan에 선언하는 속성이다. 디스크가 필요한 pipeline은 모양을 검토해야 하는 pipeline이다.

6. 지리 공간

MongoGeoQuery + MongoGeoPoint + MongoGeoDistance를 2dsphere index 위에서 쓴다. 거리는 구 위의 미터다(nearSphere와 maxDistance). 도(degree)는 쓰지 않는다. 경도 1도는 오슬로와 나이로비에서 거리가 다르다. 도로 적은 반경은 적도에서 멀어져야 드러나는 결함이다. SpringMongoGeospatialOperations가 Spring Data 연결이고, MongoGeospatialOperations가 port다.

7. Native capability gateway

등록한 연산에 정말 Stable API 밖의 것이 필요하면 driver를 바로 쓰지 않고 MongoNativeCapabilityGateway(PolicyAwareMongoNativeGateway)를 거친다. 허가 순서는 고정이다.

capability registered
→ database profile
→ collection allowlist
→ operation name present
→ timeout / maxTimeMS
→ consistency profile
→ result / batch limit
→ trace
→ log redaction
→ command category (MongoNativeCommandCategory)
→ D4 admin command refused
→ execute

ApprovedMongoNativeOperation이 등록 기록이고 MongoNativeOperationPolicy가 정책이다. admin plane 명령이 이 gateway에 오면 capability와 상관없이 거부한다. admin plane은 자기 credential과 자기 client를 쓴다 (security-observability.md).