perf(core): 대용량 목록 상한 총 건수·커서 계약 신설 및 요청당 반복 실행 비용 정리
공개 이슈 gnuboard/g7 이 지목한 병목은 "같은 일을 반복 실행한다" 축이다. 응답·행의 무게를 다룬 · 과 겹치지 않는다. 공통 계약 — 총 건수 상한과 페이지 이동 범위는 별개 결정이다. 묶으면 필요 없이 기능이 깎인다. 총 건수만 상한을 받고(파생 테이블 COUNT), "다음" 이동은 per_page + 1 실측으로 끝까지 열어 둔다. 계산이 불가능해지는 것은 마지막 페이지 번호 하나뿐이며 그 사실은 last_page: null 이 알린다. 최신순처럼 실제 컬럼으로 정렬하는 목록은 커서로 전환해 깊이와 무관하게 일정 속도로 이동한다. 관련도순은 계산값 정렬이라 커서 키로 쓸 수 없어 offset 을 유지한다. 계약의 입구는 표준 paginate 와 같은 폭이어야 한다. 관계·쿼리 빌더를 받지 못하면 그 좁은 만큼이 그대로 운영 500 이 되고, 실제로 관리자 알림 목록에서 그렇게 터졌다. 응답 조립도 컬렉션마다 손으로 하면 형태가 늘어나는 순간 없는 값을 부르거나 새 필드를 흘리므로, 형태 판정을 paginationMeta 한 곳에 모았다. 표준 paginate 응답은 필드 단위로 이전과 동일하다. 요청당 반복 비용 — 훅 구독마다 남기던 로그 400줄, 요청당 스무 번 넘던 설정 파일 재읽기, 이미 캐시된 목록의 DB 재조회를 없앴다. 권한 판정은 요청 스코프 메모를 두어 화면 요소마다 나가던 조회를 한 번으로 줄였고, 크로스 요청 캐시는 두지 않아 권한 변경이 종전처럼 다음 요청에 반영된다. 검색 질의는 활성 엔진이 만든다. 저장소가 구체 엔진을 지목하면 플러그인이 등록한 엔진은 호출될 기회 자체를 잃고 오류 없이 다른 방식으로 동작한다. 해석기를 두어 활성 엔진에 위임하고, 전문검색이 없는 DBMS 의 부분일치 폴백도 드라이버명 하드코딩 대신 선언형 config 로 옮겼다. 총 건수가 잘린 목록에서 순번을 역산하면 0 과 음수가 나온다. 지어내지 않고 null 을 돌려주며, 그 원칙을 last_page 와 동일하게 적용했다.
This commit is contained in:
1 parent
97ab99b7cd
commit
2ae1972a3b
101 files changed
+6160
-322
No files matched your search
+3
-2
@@ -9,7 +9,7 @@
|
||||
|
||||
| 카테고리 | 문서 수 | 링크 상태 |
|
||||
|----------|---------|----------|
|
||||
| [백엔드](backend/) | 34개 | 정상 |
|
||||
| [백엔드](backend/) | 35개 | 정상 |
|
||||
| [프론트엔드](frontend/) | 51개 | 정상 |
|
||||
| [확장 시스템](extension/) | 31개 | 정상 |
|
||||
| 공통 | 20개 | 정상 |
|
||||
@@ -125,7 +125,7 @@ G7 이 제공하는 REST API 의 엔드포인트별 요청 파라미터·응답
|
||||
<!-- AUTO-GENERATED-START: docs-readme-full-list -->
|
||||
## 카테고리별 전체 문서 목록
|
||||
|
||||
### 백엔드 (34개)
|
||||
### 백엔드 (35개)
|
||||
|
||||
| 문서 | 제목 |
|
||||
|------|------|
|
||||
@@ -152,6 +152,7 @@ G7 이 제공하는 REST API 의 엔드포인트별 요청 파라미터·응답
|
||||
| [language-pack-service.md](backend/language-pack-service.md) | LanguagePackService (백엔드 Service 레이어) |
|
||||
| [middleware.md](backend/middleware.md) | 미들웨어 등록 규칙 |
|
||||
| [notification-system.md](backend/notification-system.md) | 알림 시스템 (Notification System) |
|
||||
| [pagination.md](backend/pagination.md) | 대용량 목록 페이지네이션 (Pagination) |
|
||||
| [README.md](backend/README.md) | 백엔드 개발 가이드 |
|
||||
| [response-helper.md](backend/response-helper.md) | API 응답 규칙 (ResponseHelper) |
|
||||
| [routing.md](backend/routing.md) | 라우트 네이밍 및 경로 |
|
||||
|
||||
@@ -53,6 +53,7 @@
|
||||
| [language-pack-service.md](language-pack-service.md) | LanguagePackService (백엔드 Service 레이어) | LanguagePackService 가 install/activate/deactiva... |
|
||||
| [middleware.md](middleware.md) | 미들웨어 등록 규칙 | 인증 필요 미들웨어 → 전역 등록 금지! |
|
||||
| [notification-system.md](notification-system.md) | 알림 시스템 (Notification System) | GenericNotification 범용 클래스 1개로 모든 알림 처리 (개별 클래스... |
|
||||
| [pagination.md](pagination.md) | 대용량 목록 페이지네이션 (Pagination) | 총 건수만 상한을 받는다 — 상한 이하면 정확, 초과면 "이상"(total_relat... |
|
||||
| [response-helper.md](response-helper.md) | API 응답 규칙 (ResponseHelper) | 모든 API 응답은 ResponseHelper 사용 |
|
||||
| [routing.md](routing.md) | 라우트 네이밍 및 경로 | 모든 라우트는 name() 필수: ->name('api.users.index') |
|
||||
| [search-system.md](search-system.md) | Scout 검색 엔진 시스템 (Search System) | Laravel Scout + DatabaseFulltextEngine: MySQL F... |
|
||||
|
||||
@@ -80,6 +80,33 @@ Authorization: Bearer {YOUR_TOKEN}
|
||||
}
|
||||
```
|
||||
|
||||
#### 총 건수 정확도 (대용량 목록)
|
||||
|
||||
매칭이 아주 많을 수 있는 목록(검색 등)은 총 건수를 상한까지만 셉니다. 그런 목록은 위 필드에
|
||||
더해 정확도를 함께 내보내며, 세지 않은 값을 정확한 것처럼 말하지 않습니다.
|
||||
|
||||
| 필드 | 타입 | 의미 |
|
||||
| --- | --- | --- |
|
||||
| `total_relation` | string | `exact`(정확) 또는 `at_least`(그 이상) |
|
||||
| `total_is_exact` | boolean | 총 건수가 정확한지 여부 |
|
||||
| `result_cap` | integer\|null | 집계에 적용된 상한 (무제한이면 `null`) |
|
||||
|
||||
상한을 넘긴 경우 동작은 이렇습니다.
|
||||
|
||||
- `total` 은 상한값이며 **그 이상**이라는 뜻입니다 (화면은 "10,000건 이상" 으로 표기)
|
||||
- `last_page` 는 **`null`** 입니다 — 총 건수를 알아야 계산되는 유일한 값이라 계산할 수 없습니다
|
||||
- `has_more_pages` 는 그대로 정확합니다. 다음 페이지 이동은 끝까지 열려 있습니다
|
||||
|
||||
즉 상한에 걸려도 막히는 것은 마지막 페이지 점프 하나뿐입니다.
|
||||
|
||||
#### 단순형·커서형 응답
|
||||
|
||||
총 건수를 아예 세지 않는 목록(`simplePaginate`)은 `total` 과 `last_page` 를 **내보내지 않습니다**.
|
||||
커서 방식 목록은 대신 `next_cursor` / `prev_cursor` 를 실어 보냅니다. 없는 필드를 0 이나 1 로
|
||||
채우지 않으므로, 화면은 필드 존재 여부로 목록의 종류를 구분할 수 있습니다.
|
||||
|
||||
> 상한·커서 규약 상세: [pagination.md](../pagination.md)
|
||||
|
||||
일부 목록은 `data.abilities` 에 컬렉션 레벨 권한(`can_create`, `can_delete` 등)을 함께 반환합니다.
|
||||
화면의 버튼 노출 여부를 이 값으로 판정하세요.
|
||||
|
||||
|
||||
@@ -39,6 +39,7 @@
|
||||
| per_page | query | integer | 아니오 | min 1, max 100 | 페이지당 항목 수 |
|
||||
| sort_by | query | string | 아니오 | — | 정렬 기준 필드명 |
|
||||
| sort_order | query | string | 아니오 | — | 정렬 방향 (asc 오름차순 / desc 내림차순) |
|
||||
| cursor | query | string | 아니오 | max 500 | 이어보기 커서. 주면 페이지 번호 대신 키셋 방식으로 응답합니다 (기록이 많이 쌓인 사이트에서 뒤쪽 페이지가 느려지지 않음). 형식이 깨진 값은 오류 없이 첫 페이지로 해석됩니다 |
|
||||
|
||||
> 이 엔드포인트는 확장이 파라미터를 추가할 수 있습니다 (`core.activity_log.index_validation_rules`).
|
||||
|
||||
@@ -169,6 +170,27 @@ HTTP/1.1 200
|
||||
}
|
||||
```
|
||||
|
||||
**커서 방식 응답 (cursor 파라미터를 준 경우)**
|
||||
|
||||
페이지 번호 대신 앞뒤 커서를 싣습니다. 총 건수를 세지 않으므로 `total` 과 `last_page` 는 없습니다.
|
||||
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"data": [],
|
||||
"pagination": {
|
||||
"per_page": 25,
|
||||
"next_cursor": "eyJpZCI6MTIzLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
|
||||
"prev_cursor": null,
|
||||
"has_more_pages": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
총 건수가 상한을 넘겨 정확히 세지 못한 경우(페이지 번호 방식)에는 `pagination` 에 `total_relation`·`total_is_exact`·`result_cap` 이 함께 실리고 `last_page` 가 `null` 이 됩니다. 상세는 [pagination.md](../pagination.md).
|
||||
|
||||
**에러 응답**
|
||||
|
||||
| 상태코드 | 의미 | 발생 조건 |
|
||||
|
||||
@@ -30,8 +30,9 @@
|
||||
| q | query | string | 아니오 | min 2, max 200 | 검색어 (부분 일치) |
|
||||
| type | query | string | 아니오 | — | 유형 필터 (해당 유형의 항목만 조회) |
|
||||
| sort | query | string | 아니오 | `relevance`, `latest`, `oldest`, `views`, `popular`, `price_asc`, `price_desc` | 정렬 기준 (필드명, `-` 접두 시 내림차순) |
|
||||
| page | query | integer | 아니오 | min 1 | 조회할 페이지 번호 (1부터 시작) |
|
||||
| page | query | integer | 아니오 | min 1, max = 목록 한계값 설정 | 조회할 페이지 번호 (1부터 시작). 상한은 관리자 > 환경설정 > 고급의 «페이지 번호 상한» 이며 남용 차단용입니다 — 정상 탐색은 `has_more_pages` 로 계속 열려 있습니다 |
|
||||
| per_page | query | integer | 아니오 | min 1, max 100 | 페이지당 항목 수 |
|
||||
| cursor | query | string | 아니오 | max 500 | 커서(키셋) 페이지 이동용 커서. 응답의 `next_cursor` / `prev_cursor` 를 그대로 돌려보냅니다. 특정 탭을 볼 때만 유효하며(전체 탭은 무시), 실제 컬럼 기준 정렬(`latest`·`oldest`·`views`·`popular`·`price_asc`·`price_desc`)에서만 적용됩니다. 관련도순은 계산값 정렬이라 커서를 쓸 수 없어 `page` 기반 이동을 유지합니다. 형식이 깨진 값은 오류 없이 첫 페이지로 처리됩니다 |
|
||||
| board_slug | query | string | 아니오 | max 100 | 검색 범위를 특정 게시판으로 한정 (게시판 모듈이 `core.search.index_validation_rules` 훅으로 추가하는 파라미터, 해당 slug의 게시판 글만 검색) |
|
||||
| category_id | query | integer | 아니오 | — | category 식별자 |
|
||||
|
||||
@@ -50,7 +51,22 @@ _단건 응답: `data` 객체의 필드._
|
||||
| 필드 | 타입 | 실측 예시값 | 용도/설명 |
|
||||
| --- | --- | --- | --- |
|
||||
| q | string | `` | 실제 검색에 사용된 검색어 (요청 `q` 를 trim 하여 에코, 검색어가 비어 있으면 빈 문자열) |
|
||||
| total | integer | `0` | 전체 개수 (집계) |
|
||||
| total | integer | `0` | 전체 개수 (집계). 상한을 넘기면 상한값이며 «그 이상» 을 뜻합니다 |
|
||||
| total_relation | string | `exact` | 총 건수 정확도 (`exact` 정확 / `at_least` 그 이상) |
|
||||
| total_is_exact | boolean | `true` | 총 건수가 정확한지 여부. `false` 면 화면이 "N건 이상" 으로 표기합니다 |
|
||||
| result_cap | integer\|null | `10000` | 총 건수 집계에 적용된 상한 (무제한이면 `null`) |
|
||||
| all_count | integer | `0` | 전체 탭 기준 합계 (탭 배지 표기용) |
|
||||
| all_count_is_exact | boolean | `true` | 전체 합계가 정확한지 여부. 카테고리 중 하나라도 상한에 걸리면 `false` 입니다 |
|
||||
| last_page | integer\|null | `1` | 특정 탭 조회 시의 마지막 페이지. **총 건수가 부정확하면 `null`** |
|
||||
| has_more_pages | boolean | `false` | 다음 페이지 존재 여부 (총 건수를 몰라도 정확) |
|
||||
| next_cursor | string\|null | `null` | 다음 페이지 커서. 커서 방식으로 응답했을 때만 채워지며, `page` 방식 응답에서는 `null` 입니다 |
|
||||
| prev_cursor | string\|null | `null` | 이전 페이지 커서. 위와 같습니다 |
|
||||
| counts_are_exact | object | `{}` | 카테고리별 총 건수 정확도 (`{"posts": true, "products": false}`). 탭 배지가 카테고리마다 그려지므로 정확도도 카테고리마다 제공됩니다 — 정확하지 않은 배지는 화면에서 "이상" 으로 표기됩니다 |
|
||||
|
||||
카테고리(탭) 중 하나라도 상한에 걸리면 합계도 정확하지 않습니다 — 정확한 카테고리 몇 개를
|
||||
더해 봐야 전체가 정확해지지 않기 때문입니다. 그 경우 `total_is_exact` 는 `false` 가 됩니다.
|
||||
|
||||
> 상한·페이지 이동 규약 상세: [pagination.md](../pagination.md)
|
||||
|
||||
**응답 예시**
|
||||
|
||||
@@ -64,7 +80,10 @@ HTTP/1.1 200
|
||||
"message": "검색어를 입력해주세요.",
|
||||
"data": {
|
||||
"q": "",
|
||||
"total": 0
|
||||
"total": 0,
|
||||
"total_relation": "exact",
|
||||
"total_is_exact": true,
|
||||
"result_cap": 10000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -4,6 +4,22 @@
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 목록 한계값 (`advanced` 탭)
|
||||
|
||||
대용량 목록에서 총 건수를 세는 범위와 직접 요청할 수 있는 페이지 번호의 상한입니다.
|
||||
저장 경로는 다른 고급 설정과 같은 `advanced` 탭이며, 저장소에는 `pagination` 카테고리로 남습니다.
|
||||
|
||||
| 필드 | 타입 | 범위 | 의미 |
|
||||
| --- | --- | --- | --- |
|
||||
| `advanced.pagination_result_cap` | integer | 0 ~ 1,000,000 | 총 건수를 정확히 세는 상한. 0 이면 항상 전부 셉니다 |
|
||||
| `advanced.pagination_max_page` | integer | 0 ~ 100,000 | 주소로 직접 요청할 수 있는 최대 페이지 번호. 0 이면 제한하지 않습니다 |
|
||||
|
||||
경계값은 설정 응답의 `_meta.limits` 로 함께 내려오며(`advanced_pagination_result_cap_min` 등),
|
||||
화면 입력 칸의 min/max 와 저장 검증이 같은 값을 공유합니다.
|
||||
|
||||
상한을 넘긴 목록의 응답 형태는 [pagination.md](../pagination.md) 를 참고하세요.
|
||||
|
||||
## TL;DR (5초 요약)
|
||||
|
||||
```text
|
||||
|
||||
@@ -29,16 +29,30 @@
|
||||
|
||||
## 파일 구조 개요
|
||||
|
||||
`config/core.php`는 3개 최상위 키로 구성됩니다:
|
||||
`config/core.php`는 최상위 키로 구성되며, 이 문서는 그중 권한·역할·메뉴를 다룹니다.
|
||||
나머지 키는 각자의 규정 문서가 소유합니다.
|
||||
|
||||
```php
|
||||
return [
|
||||
'permissions' => [...], // 코어 권한 정의
|
||||
'roles' => [...], // 코어 역할 정의
|
||||
'menus' => [...], // 코어 메뉴 정의
|
||||
// 이 문서가 다루는 범위
|
||||
'permissions' => [...], // 코어 권한 정의
|
||||
'roles' => [...], // 코어 역할 정의
|
||||
'menus' => [...], // 코어 메뉴 정의
|
||||
|
||||
// 다른 문서가 소유하는 키
|
||||
'settings_limits' => [...], // 관리자 환경설정 입력 한계값
|
||||
'pagination' => [...], // 목록 한계값 기본값 → pagination.md
|
||||
'search' => [...], // DBMS 별 부분일치 연산자 → search-system.md
|
||||
'notification_definitions' => [...], // 알림 정의 → notification-system.md
|
||||
'identity_policies' => [...], // 본인인증 정책 → identity-policies.md
|
||||
'identity_messages' => [...], // 본인인증 메시지 → identity-messages.md
|
||||
'identity_purposes' => [...], // 본인인증 목적 → identity-policies.md
|
||||
];
|
||||
```
|
||||
|
||||
키를 새로 추가할 때는 그 키를 설명하는 규정 문서를 함께 지정하고 이 목록에 한 줄을 더합니다.
|
||||
목록이 실제 구조와 어긋나면 "여기 없으니 없는 값" 으로 읽혀 중복 키가 생깁니다.
|
||||
|
||||
> **변경 이력 (7.0.0-beta.2)**: `mail_templates` 키는 알림 시스템 통합(#146)으로 제거되었습니다. 코어 메일 템플릿은 `notification_definitions` + `notification_templates` 로 이전되었으며, `database/seeders/NotificationDefinitionSeeder` 가 시드 데이터를 직접 보유합니다.
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,344 @@
|
||||
# 대용량 목록 페이지네이션 (Pagination)
|
||||
|
||||
> **관련 문서**: [Service-Repository 패턴](./service-repository.md) | [API 리소스](./api-resources.md) | [검색 시스템](./search-system.md)
|
||||
|
||||
---
|
||||
|
||||
## TL;DR (5초 요약)
|
||||
|
||||
```text
|
||||
1. 총 건수만 상한을 받는다 — 상한 이하면 정확, 초과면 "이상"(total_relation=at_least)
|
||||
2. "다음" 이동은 상한과 무관하게 끝까지 열려 있다 (per_page + 1 실측)
|
||||
3. 계산이 불가능해지는 것은 마지막 페이지 번호 하나뿐 → last_page = null
|
||||
4. 최신순 등 실제 컬럼 정렬은 커서(키셋)로 전환 가능, 관련도순은 offset 유지
|
||||
5. 한계값은 관리자 환경설정 > 고급이 SSoT — 확장은 필터 훅으로만 조정
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 목차
|
||||
|
||||
- [왜 상한을 두는가](#왜-상한을-두는가)
|
||||
- [상한과 페이지 이동의 관계](#상한과-페이지-이동의-관계)
|
||||
- [구성 요소](#구성-요소)
|
||||
- [저장소에서 쓰는 법](#저장소에서-쓰는-법)
|
||||
- [상한 없는 전량 조회](#상한-없는-전량-조회)
|
||||
- [건수만 필요할 때](#건수만-필요할-때)
|
||||
- [응답 계약](#응답-계약)
|
||||
- [커서(키셋) 페이지네이션](#커서키셋-페이지네이션)
|
||||
- [한계값 설정](#한계값-설정)
|
||||
- [화면 쪽 규약](#화면-쪽-규약)
|
||||
- [체크리스트](#체크리스트)
|
||||
|
||||
---
|
||||
|
||||
## 왜 상한을 두는가
|
||||
|
||||
목록 화면은 보통 한 페이지 분량만 보여 주면서 총 건수를 함께 표시한다. 그 총 건수를 구하는
|
||||
`COUNT(*)` 는 조건에 맞는 행을 **전부** 세야 하므로, 매칭이 많을수록 한 페이지를 그리는 데
|
||||
드는 비용이 커진다. 검색처럼 매칭이 수십만 건에 이를 수 있는 목록에서는 페이지 조회보다
|
||||
건수 집계가 더 비싸지는 역전이 일어난다.
|
||||
|
||||
한편 사용자가 총 건수에서 실제로 얻는 정보는 "많다/적다" 와 "마지막 페이지가 어디쯤인가"
|
||||
정도다. 12,842건과 "10,000건 이상" 은 실질적으로 같은 정보를 준다. 그래서 **세는 범위에만
|
||||
상한을 두고**, 상한을 넘으면 정확한 수 대신 하한을 보고한다.
|
||||
|
||||
### 상한이 줄여 주지 못하는 것 — FULLTEXT 술어
|
||||
|
||||
상한은 **세는 행 수**를 줄인다. 그러나 조건을 만족하는 행을 찾는 일 자체는 줄이지 못한다.
|
||||
FULLTEXT(`MATCH ... AGAINST`) 검색에서 이 차이가 크게 드러난다.
|
||||
|
||||
30만 행 전부가 한 토큰에 매칭되는 조건으로 실측한 결과다.
|
||||
|
||||
| 쿼리 | 소요 |
|
||||
|------|------|
|
||||
| 상한 COUNT (`LIMIT 10001` 로 감싼 파생 테이블) | 588.96초 |
|
||||
| 상한 없는 COUNT | 560.48초 |
|
||||
| 페이지 조회 (`LIMIT 21`) | 594.76초 |
|
||||
|
||||
세 경우가 사실상 같다. InnoDB 전문 검색은 매칭 집합을 먼저 구성하고 그 뒤에 `LIMIT` 을
|
||||
적용하므로, 몇 건을 돌려주든 매칭 집합을 만드는 비용은 동일하게 든다. 같은 조건에서
|
||||
실행계획을 보면 상한 COUNT 는 파생 테이블로 감싸는 과정에서 FULLTEXT 인덱스 사용
|
||||
계획을 잃고 전체 스캔이 되기도 한다.
|
||||
|
||||
따라서 검색 목록에서 상한이 주는 이득은 **PHP 메모리·전송량·중복 실행 제거**이며,
|
||||
데이터베이스가 매칭을 찾는 시간은 상한으로 해결되지 않는다. 이 축이 문제라면 전용 검색
|
||||
엔진(`core.search.engine_drivers` 훅으로 교체)을 쓰는 것이 남은 경로다.
|
||||
|
||||
토큰 결합을 OR 에서 AND 로 바꿔 매칭 집합 자체를 줄이는 안은 **채택하지 않는다**. 입력한
|
||||
단어 중 하나만 든 문서가 결과에서 통째로 사라지는 손실이 성능 이득보다 크다고 판단했다
|
||||
(한글은 ngram 파서가 2글자 단위로 토큰을 쪼개 축소 폭이 특히 크다). 상세는
|
||||
[search-system.md "검색어 토큰은 OR 로 결합한다"](search-system.md) 참조.
|
||||
|
||||
측정 한계도 함께 적는다. 위 수치는 한 토큰이 전 행에 걸리도록 만든 인위적 조건이고,
|
||||
단일 개발 장비 기준이다. 매칭이 적은 일반적인 검색어에는 해당하지 않는다.
|
||||
`innodb_ft_result_cache_limit` 에 대한 메모리 증가분은 기준선을 확보하지 못해 확정하지
|
||||
못했다 — 확정된 것은 위 시간 축뿐이다.
|
||||
|
||||
---
|
||||
|
||||
## 상한과 페이지 이동의 관계
|
||||
|
||||
총 건수 상한과 페이지 이동 범위는 **별개 결정**이다. 묶으면 필요 없이 기능이 깎인다.
|
||||
|
||||
| 항목 | 상한을 넘었을 때 |
|
||||
|---|---|
|
||||
| 총 건수 | "N건 이상" 으로 표기 (`total_relation = at_least`) |
|
||||
| 다음 페이지 이동 | **그대로 가능** — `per_page + 1` 조회로 정확히 판정 |
|
||||
| 이전 페이지 이동 | 그대로 가능 |
|
||||
| 마지막 페이지 점프 | **감춤** — 총 건수를 알아야 계산되는 유일한 값 |
|
||||
|
||||
마지막 페이지 점프를 감추는 것은 기능 축소가 아니라 **계산 불가 사실의 정직한 표시**다.
|
||||
그 버튼은 대량 매칭에서 초대형 OFFSET 을 실행하므로, 눌러도 정상 응답이 오지 않는 경우가 많다.
|
||||
|
||||
---
|
||||
|
||||
## 구성 요소
|
||||
|
||||
| 구성 요소 | 위치 | 역할 |
|
||||
|---|---|---|
|
||||
| `TotalRelation` | `app/Enums/TotalRelation.php` | 총 건수 정확도 (`Exact` / `AtLeast`) |
|
||||
| `BoundedPaginator` | `app/Support/Query/BoundedPaginator.php` | `per_page + 1` 조회 + 상한 파생 테이블 COUNT |
|
||||
| `BoundedPage` | `app/Support/Query/BoundedPage.php` | 페이지 결과. 표준 페이지네이터 인터페이스를 그대로 만족 |
|
||||
| `KeysetPaginator` | `app/Support/Query/KeysetPaginator.php` | 커서 인코딩/디코딩 표준 |
|
||||
| `PaginationLimits` | `app/Support/Query/PaginationLimits.php` | 한계값 해석 (설정 → 필터 훅) |
|
||||
| `BoundedTotalAware` | `app/Contracts/Pagination/BoundedTotalAware.php` | 정확도를 밝히는 페이지 결과 계약 |
|
||||
|
||||
`BoundedPage` 는 `LengthAwarePaginator` 를 상속한다. 기존 컬렉션·리소스·컨트롤러가 전부
|
||||
페이지네이터 인터페이스에 맞춰져 있으므로, 별도 타입을 새로 정의하면 소비 지점마다 언랩
|
||||
코드가 생긴다. 상속하면 기존 코드가 그대로 받고 정확도 메타까지 자동으로 얻는다.
|
||||
|
||||
---
|
||||
|
||||
## 저장소에서 쓰는 법
|
||||
|
||||
```php
|
||||
use App\Support\Query\BoundedPaginator;
|
||||
use App\Support\Query\PaginationLimits;
|
||||
|
||||
public function searchByKeyword(string $keyword, int $perPage = 10, int $page = 1): BoundedPage
|
||||
{
|
||||
$query = $this->model->newQuery()
|
||||
->where('published', true)
|
||||
->orderBy('created_at', 'desc')
|
||||
// 전순서 보장 — 정렬 컬럼이 비고유면 페이지 경계에서 행이 겹치거나 샌다
|
||||
->orderBy('id', 'desc');
|
||||
|
||||
return BoundedPaginator::paginate(
|
||||
$query,
|
||||
perPage: $perPage,
|
||||
page: $page,
|
||||
resultCap: PaginationLimits::resultCap('search'),
|
||||
// 목록이 실제로 쓰는 컬럼만 명시 (프루닝)
|
||||
columns: ['id', 'slug', 'title', 'created_at'],
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
건수만 필요한 경우(탭 배지 등)는 조회 없이 집계만 한다.
|
||||
|
||||
```php
|
||||
[$total, $relation] = BoundedPaginator::countWithCap($query, PaginationLimits::resultCap('search'));
|
||||
```
|
||||
|
||||
`GROUP BY` 가 걸린 쿼리도 파생 테이블 안에서 그룹이 만들어지므로 **그룹 수**가 그대로 센다.
|
||||
표준 `count()` 가 그룹별 건수를 돌려주는 문제가 없다.
|
||||
|
||||
### 받는 입력은 표준 `paginate()` 와 같다
|
||||
|
||||
Eloquent 빌더뿐 아니라 쿼리 빌더(`DB::table(...)`)와 **관계**(`$user->notifications()`)도
|
||||
그대로 넘길 수 있다.
|
||||
|
||||
```php
|
||||
// 관계를 그대로 넘겨도 된다 — 소속 조건은 그 밑 빌더에 이미 들어가 있어 보존된다
|
||||
BoundedPaginator::paginate($user->notifications(), perPage: 15, resultCap: $cap);
|
||||
```
|
||||
|
||||
이 폭은 **좁히면 안 된다.** 이 계약은 기존 `->paginate()` 호출을 대체하려고 만든 것이라,
|
||||
받는 형태가 표준보다 좁으면 바꾸는 것만으로 멀쩡하던 목록이 죽는다. 관계에서 `->paginate()`
|
||||
가 되는 이유는 관계가 빌더로 호출을 전달해 주기 때문인데, 정적 메서드는 그 전달을 받지
|
||||
못하므로 계약이 직접 이해해야 한다.
|
||||
|
||||
`PaginatesWithDeferredJoin` 은 빌더와 관계를 받는다. 이쪽은 모델의 키 컬럼과 eager load 를
|
||||
다루므로 Eloquent 가 전제이며, 쿼리 빌더는 받지 않는다.
|
||||
|
||||
### 하지 말 것
|
||||
|
||||
| ❌ 금지 | ✅ 올바른 사용 |
|
||||
|---|---|
|
||||
| 같은 술어로 `count()` 한 번, `get()` 한 번 | `BoundedPaginator::paginate()` 한 번 |
|
||||
| `paginate(PHP_INT_MAX)` 후 PHP `array_slice` | 실제 `page`/`per_page` 를 저장소까지 하달 |
|
||||
| `forPage($page, $perPage + 1)` | offset 은 `per_page` 기준으로 따로 계산 |
|
||||
| 총 건수를 모르는데 `last_page` 를 1 로 채움 | `null` 로 내보내 화면이 감추게 한다 |
|
||||
| 정렬 마지막이 비고유 컬럼 | 기본키를 덧붙여 전순서 보장 |
|
||||
| 컬렉션에서 `'pagination' => [...]` 를 손으로 조립 | `...$this->paginationMeta()` — 형태를 스스로 판정한다 |
|
||||
|
||||
---
|
||||
|
||||
## 상한 없는 전량 조회
|
||||
|
||||
`->get()` / `->pluck()` 자체가 문제인 것은 아니다. 문제는 **결과 크기가 데이터 증가에
|
||||
비례해 커지는데 아무 상한도 없는** 경우다. 그런 조회는 개발 데이터에서 늘 빠르고, 운영
|
||||
데이터가 쌓인 뒤에야 메모리와 응답 시간을 함께 무너뜨린다. 예외도 경고도 없이 느려지기만
|
||||
하므로 테스트로는 드러나지 않는다.
|
||||
|
||||
한 문장 안에 결과 크기를 묶는 근거가 하나는 있어야 한다.
|
||||
|
||||
| 상황 | 쓸 것 |
|
||||
|---|---|
|
||||
| 화면에 목록으로 보여 준다 | `BoundedPaginator::paginate()` / `paginateWithDeferredJoin()` |
|
||||
| 전량을 순회해 처리한다 | `chunkById()` / `lazyById()` (키셋 — OFFSET 밀림이 없다) |
|
||||
| 몇 건만 필요하다 | `limit()` / `take()` |
|
||||
| 이미 좁혀진 키 집합이다 | `whereIn($key, $ids)` / `find()` |
|
||||
|
||||
행 수가 사용량이 아니라 **운영자의 등록 수**에 묶이는 설정성 테이블(역할·언어팩·정책 등)은
|
||||
예외다. 그 경우 근거를 코드에 남긴다.
|
||||
|
||||
```php
|
||||
// audit:allow query-unbounded-get reason: 역할은 운영자가 정의한 수만큼만 존재한다 (회원 수와 무관)
|
||||
return Role::where('is_active', true)->orderBy('id')->get();
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 건수만 필요할 때
|
||||
|
||||
목록을 조회하지 않고 건수만 필요한 자리(탭 배지, 요약 수치)는 `BoundedPaginator::count()`
|
||||
를 쓴다. `int` 하나만 돌려주면 **상한에 걸려 잘린 값과 정확히 센 값이 구분되지 않는다** —
|
||||
잘린 10,000 이 "정확히 10,000 건" 으로 화면에 나가는 것은 오류로 드러나지 않고 그냥 틀린
|
||||
숫자로만 보인다.
|
||||
|
||||
```php
|
||||
$count = BoundedPaginator::count($query, PaginationLimits::resultCap('search'));
|
||||
|
||||
return $count->toArray();
|
||||
// ['total' => 10000, 'total_relation' => 'at_least', 'total_is_exact' => false, 'result_cap' => 10000]
|
||||
```
|
||||
|
||||
여러 카테고리의 건수를 합칠 때는 **하나라도 부정확하면 합계도 부정확**하다. 정확한
|
||||
카테고리 몇 개를 더해 봐야 전체가 정확해지지 않는다. 반대로 특정 탭 하나만 보는
|
||||
중이라면 그 카테고리의 정확도만 본다 — 다른 카테고리가 잘렸다는 이유로 정확한 값을
|
||||
"이상" 이라고 말하지 않는다.
|
||||
|
||||
---
|
||||
|
||||
## 응답 계약
|
||||
|
||||
`BaseApiCollection::paginationMeta()` 가 페이지 결과의 형태를 스스로 판정해 그 형태가 실제로
|
||||
아는 값만 내보낸다. 모르는 값을 0 이나 1 로 채우면 화면이 그것을 사실로 읽는다.
|
||||
|
||||
| 형태 | 예 | `total` | `last_page` | 추가 필드 |
|
||||
|---|---|---|---|---|
|
||||
| 전체건수형 | `paginate()` | 정확 | 정확 | — |
|
||||
| 상한형 | `BoundedPage` | 정확 또는 하한 | 하한이면 `null` | `total_relation` `total_is_exact` `result_cap` |
|
||||
| 단순형 | `simplePaginate()` | 없음 | 없음 | — |
|
||||
| 커서형 | `cursorPaginate()` | 없음 | 없음 | `next_cursor` `prev_cursor` |
|
||||
|
||||
표준 `paginate()` 를 쓰는 기존 컬렉션의 응답은 필드 단위로 이전과 완전히 같다.
|
||||
|
||||
컬렉션이 이 블록을 손으로 조립하면 두 가지가 함께 깨진다. 커서 결과에는 `total()` 과
|
||||
`lastPage()` 가 없어 **그 요청만 500** 이 되고, 상한형에서는 정확도 필드가 빠져 잘린 건수가
|
||||
정확한 값처럼 화면에 나간다. 둘 다 표준 `paginate()` 만 쓰던 시절에는 드러나지 않던 형태라,
|
||||
목록 하나를 상한형이나 커서형으로 바꾸는 순간 처음 나타난다.
|
||||
|
||||
```json
|
||||
{
|
||||
"pagination": {
|
||||
"current_page": 3,
|
||||
"per_page": 20,
|
||||
"from": 41,
|
||||
"to": 60,
|
||||
"has_more_pages": true,
|
||||
"last_page": null,
|
||||
"total": 10000,
|
||||
"total_relation": "at_least",
|
||||
"total_is_exact": false,
|
||||
"result_cap": 10000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 커서(키셋) 페이지네이션
|
||||
|
||||
OFFSET 방식은 건너뛸 행을 실제로 읽어야 해서 페이지가 깊어질수록 느려진다. 커서 방식은
|
||||
직전 페이지 마지막 행의 정렬 키를 WHERE 절 경계로 삼으므로 깊이와 무관하게 일정하다.
|
||||
|
||||
```php
|
||||
use App\Support\Query\KeysetPaginator;
|
||||
|
||||
$page = KeysetPaginator::paginate(
|
||||
$query,
|
||||
perPage: 20,
|
||||
sortKeys: [['created_at', 'desc']],
|
||||
uniqueKey: 'id',
|
||||
cursor: $request->query(KeysetPaginator::CURSOR_PARAM),
|
||||
);
|
||||
```
|
||||
|
||||
### 관련도순에는 적용할 수 없다
|
||||
|
||||
커서는 정렬 키를 WHERE 절 경계로 쓴다. 따라서 정렬 키가 **실제 컬럼**이어야 한다.
|
||||
FULLTEXT 관련도 점수(`_ft_score`)는 행마다 계산되는 값이고 컬럼이 아니므로 경계로 쓸 수 없다.
|
||||
|
||||
`sort=relevance` 는 이 제약 때문에 OFFSET 을 유지한다. 판정은
|
||||
`KeysetPaginator::supports($sortKeys, $columnWhitelist)` 가 담당하며, 허용 컬럼 목록 밖의
|
||||
정렬 키가 하나라도 있으면 `false` 를 돌려준다.
|
||||
|
||||
깨진 커서 문자열은 예외 대신 첫 페이지로 처리한다. 사용자가 주소를 손으로 고쳤다는 이유로
|
||||
목록 화면이 오류를 띄우게 두지 않는다.
|
||||
|
||||
---
|
||||
|
||||
## 한계값 설정
|
||||
|
||||
| 설정 | 기본값 | 의미 |
|
||||
|---|---|---|
|
||||
| `pagination.result_cap` | 10000 | 총 건수를 정확히 세는 상한 (0 = 무제한) |
|
||||
| `pagination.max_page` | 1000 | 직접 요청할 수 있는 페이지 번호 상한 (0 = 무제한) |
|
||||
|
||||
해석 순서는 **관리자 환경설정 > 고급 → `config/core.php` 기본값 → 확장 필터 훅** 이다.
|
||||
해석은 `PaginationLimits` 한 곳에서만 하며, 확장은 값을 리터럴로 다시 적지 않고 훅으로 조정한다.
|
||||
|
||||
```php
|
||||
HookManager::addFilter('core.pagination.filter_result_cap', function (int $cap, ?string $context) {
|
||||
return $context === 'search' ? 50000 : $cap;
|
||||
});
|
||||
```
|
||||
|
||||
`max_page` 는 남용 차단용이다. 정상 탐색은 `has_more_pages` 와 커서로 계속 열려 있고,
|
||||
이 값은 임의의 큰 페이지 번호를 직접 던져 초대형 OFFSET 을 만드는 것만 막는다.
|
||||
|
||||
---
|
||||
|
||||
## 화면 쪽 규약
|
||||
|
||||
`Pagination` 컴포넌트는 세 가지 입력으로 동작한다.
|
||||
|
||||
| Prop | 의미 |
|
||||
|---|---|
|
||||
| `totalPages` | 마지막 페이지. **`null` 이면 페이지 번호 목록과 마지막 페이지 점프가 사라진다** |
|
||||
| `hasMorePages` | 다음 페이지 존재 여부. 총 건수를 몰라도 정확하다 |
|
||||
| `showFirst` / `showLast` | 첫/마지막 버튼을 따로 제어 (미지정 시 `showFirstLast` 를 따름) |
|
||||
|
||||
총 건수 표기는 정확도에 따라 문구가 갈린다.
|
||||
|
||||
```text
|
||||
정확: 총 1,234건
|
||||
하한: 총 10,000건 이상 (+ 검색어를 더 구체적으로 입력하면 정확한 건수를 볼 수 있다는 안내)
|
||||
```
|
||||
|
||||
세지 않은 값을 정확한 것처럼 말하지 않는다.
|
||||
|
||||
---
|
||||
|
||||
## 체크리스트
|
||||
|
||||
- [ ] 목록 조회가 같은 술어를 `count()` + `get()` 으로 두 번 실행하지 않는가
|
||||
- [ ] `paginate()` 에 조회 컬럼을 명시했는가 (`['*']` 방치 금지)
|
||||
- [ ] 정렬 마지막에 기본키를 덧붙여 전순서를 보장했는가
|
||||
- [ ] 총 건수를 모를 때 `last_page` 를 `null` 로 내보내는가
|
||||
- [ ] 화면이 `total_is_exact` 를 보고 문구를 바꾸는가
|
||||
- [ ] 상한값을 리터럴로 적지 않고 `PaginationLimits` 를 거치는가
|
||||
- [ ] 커서를 쓴다면 정렬 키가 전부 실제 컬럼인가
|
||||
@@ -24,10 +24,11 @@
|
||||
2. [FulltextSearchable 인터페이스](#fulltextsearchable-인터페이스)
|
||||
3. [검색 엔진 드라이버](#검색-엔진-드라이버)
|
||||
4. [확장 포인트](#확장-포인트)
|
||||
5. [마이그레이션](#마이그레이션)
|
||||
6. [AsUnicodeJson 캐스트](#asunicodejson-캐스트)
|
||||
7. [환경설정](#환경설정)
|
||||
8. [관련 문서](#관련-문서)
|
||||
5. [검색 목록의 페이지 이동](#검색-목록의-페이지-이동)
|
||||
6. [마이그레이션](#마이그레이션)
|
||||
7. [AsUnicodeJson 캐스트](#asunicodejson-캐스트)
|
||||
8. [환경설정](#환경설정)
|
||||
9. [관련 문서](#관련-문서)
|
||||
|
||||
---
|
||||
|
||||
@@ -188,6 +189,93 @@ DBMS에 따라 자동 분기:
|
||||
- MySQL/MariaDB: `WHERE MATCH(\`content\`) AGAINST(? IN BOOLEAN MODE)`
|
||||
- 그 외: `WHERE content LIKE '%keyword%'`
|
||||
|
||||
### 키워드 술어는 활성 엔진이 만든다
|
||||
|
||||
Scout 의 `Model::search()` 는 "엔진이 결과를 돌려준다" 모델입니다. 그래서 결과를 받은 뒤 그 ID
|
||||
로 DB 를 다시 조회해야 하고, 매칭이 많으면 ID 전량을 메모리에 올려 무제한 `IN (...)` 을 만들게
|
||||
됩니다. 페이지네이션·조인·필터를 DB 에 남긴 채 키워드 조건만 얹으려면 **엔진에게 술어를 달라고
|
||||
요청할 통로**가 따로 필요합니다.
|
||||
|
||||
그 통로가 `App\Search\Contracts\KeywordPredicateProvider` 이고, 해석은
|
||||
`App\Search\KeywordSearch` 가 단독으로 수행합니다.
|
||||
|
||||
```php
|
||||
use App\Search\KeywordSearch;
|
||||
|
||||
// 컬럼들을 하나의 조건으로 함께 평가 (복합 인덱스가 있는 테이블)
|
||||
KeywordSearch::apply($query, ['title', 'content'], $keyword);
|
||||
|
||||
// 컬럼마다 따로 평가해 OR 로 묶기 (컬럼별 단일 인덱스만 있는 테이블)
|
||||
KeywordSearch::applyAny($query, ['name', 'description'], $keyword);
|
||||
```
|
||||
|
||||
**저장소는 구체 엔진 클래스를 지목하지 않습니다.** 지목하는 순간 플러그인이 등록한 검색 엔진은
|
||||
호출될 기회 자체를 잃고, 오류도 경고도 없이 그 사이트의 검색만 조용히 다른 방식으로 동작합니다.
|
||||
|
||||
활성 엔진이 이 계약을 구현하지 않으면 부분일치로 내려가며, 그 사실이 기록에 남습니다 — 폴백은
|
||||
정상 동작처럼 보이므로 기록하지 않으면 "검색이 느리고 관련도가 이상하다" 는 증상만 남습니다.
|
||||
|
||||
#### 페이지네이션은 DB 가, 상한은 엔진이
|
||||
|
||||
엔진에게 페이지 번호를 넘기지 않습니다. 엔진이 자기 순서로 한 페이지 분량만 돌려주면, 그 뒤에
|
||||
적용되는 DB 필터(분류·전시상태·조인)에 일부가 탈락해 페이지가 비고, DB 정렬과 엔진의 관련도
|
||||
순서가 달라 페이지 경계도 어긋나기 때문입니다.
|
||||
|
||||
엔진이 책임지는 것은 **"얼마까지 돌려줄 것인가"** 하나이며, 그 값은 `KeywordSearchContext` 로
|
||||
전달됩니다. 외부 검색 서버를 쓰는 엔진은 자기 서버에서 키 집합을 받아 조건으로 붙이는데,
|
||||
상한을 지키지 않으면 매칭이 큰 검색어에서 그 집합 자체가 메모리 폭발이 됩니다.
|
||||
|
||||
```php
|
||||
KeywordSearch::applyAny($query, ['name', 'description'], $keyword, 'and', 'search');
|
||||
// ↑ 상한 해석 컨텍스트
|
||||
```
|
||||
|
||||
상한은 목록 총 건수 상한(`PaginationLimits::resultCap()`)과 **같은 값**을 씁니다. 두 기준이
|
||||
갈라지면 "엔진이 돌려준 건수" 와 "화면이 보고하는 총 건수" 가 서로 다른 근거를 갖게 됩니다.
|
||||
상한에 걸려 잘린 경우 그 이상은 도달 불가이고 총 건수는 "이상" 으로 보고됩니다.
|
||||
|
||||
이 의무는 정적 검사로 강제할 수 없습니다 — 외부 엔진 코드는 이 저장소 밖입니다. 코어가 할 수
|
||||
있는 것은 **값을 손에 쥐어 주는 것**까지이며, 그 값이 실제로 도달하는지는 계약 테스트가
|
||||
고정합니다.
|
||||
|
||||
#### 전문검색을 제공하지 않는 DBMS
|
||||
|
||||
부분일치 경로는 임시방편이 아닙니다. 전문검색을 제공하지 않는 DBMS 로 설치된 사이트에서는
|
||||
**이것이 정상 검색 경로**이므로 이식성을 갖춥니다.
|
||||
|
||||
- 검색어의 `%` `_` `\` 를 escape 해 이용자가 입력한 글자 그대로 찾습니다.
|
||||
- "대소문자를 구분하지 않는 부분일치" 를 어떤 연산자로 쓰는지는 DBMS 마다 다릅니다. 그 표는
|
||||
`config('core.search.like_operators')` 에 **선언형으로** 있고, 표에 없는 드라이버는
|
||||
`like_operator_default` 를 씁니다. 코어 코드에는 드라이버명을 적지 않습니다 — 적으면
|
||||
DBMS 가 공식 지원 목록에 추가될 때마다 코어를 고쳐야 합니다.
|
||||
- 확장은 `core.search.like_operators` 필터 훅으로 새 DBMS 의 연산자를 선언합니다.
|
||||
|
||||
```php
|
||||
HookManager::addFilter('core.search.like_operators', function (array $operators) {
|
||||
$operators['somedb'] = 'imatch';
|
||||
|
||||
return $operators;
|
||||
});
|
||||
```
|
||||
|
||||
해당 DBMS 의 진짜 전문검색(예: PostgreSQL `tsvector`)은 그 엔진을 `core.search.engine_drivers`
|
||||
로 등록하고 `KeywordPredicateProvider` 를 구현하면 코어 수정 없이 이 경로를 그대로 탑니다.
|
||||
|
||||
### 검색어 토큰은 OR 로 결합한다 (확정)
|
||||
|
||||
`sanitizeBooleanModeKeyword()` 는 BOOLEAN MODE 연산자를 제거한 뒤 남은 토큰을 각각
|
||||
따옴표로 묶어 **공백으로 잇는다**. BOOLEAN MODE 에서 공백 결합은 OR 이므로, "빨간 운동화"
|
||||
는 "빨간" 이 든 행과 "운동화" 가 든 행을 **모두** 매치한다.
|
||||
|
||||
각 토큰에 `+` 를 붙여 AND 로 바꾸면 매칭 집합 자체가 줄어 대용량에서 검색 시간이 줄어들
|
||||
여지가 있다. 그럼에도 **OR 을 유지한다** — 이용자가 입력한 단어 중 하나만 든 문서가
|
||||
결과에서 통째로 사라지는 것은 성능과 맞바꿀 수 없는 손실이기 때문이다. 한글은 ngram 파서가
|
||||
2글자 단위로 토큰을 쪼개므로 AND 전환의 결과 축소 폭이 특히 크다.
|
||||
|
||||
성능 축이 문제가 되면 토큰 결합 방식이 아니라 전용 검색 엔진(`core.search.engine_drivers`
|
||||
훅으로 교체)으로 해결한다. 상한 COUNT 가 매칭 시간을 줄이지 못하는 이유와 실측치는
|
||||
[pagination.md](pagination.md) 참조.
|
||||
|
||||
---
|
||||
|
||||
## 확장 포인트
|
||||
@@ -481,8 +569,77 @@ SCOUT_QUEUE=false
|
||||
|
||||
---
|
||||
|
||||
## 검색 목록의 페이지 이동
|
||||
|
||||
검색 결과는 컬렉션 리소스를 거치지 않고 리스너가 배열을 만들어 넘긴다. 그 조립과 판정을
|
||||
도메인마다 손으로 하면 검색 모듈 수만큼 같은 코드가 복제되고, 나중에 필드가 하나 늘 때
|
||||
어떤 화면은 받고 어떤 화면은 못 받는다. **코어가 계약을 소유하고 확장은 선언만 한다.**
|
||||
|
||||
| 코어가 소유하는 것 | 위치 |
|
||||
|---|---|
|
||||
| 커서 적용 가능 여부 판정 | `App\Search\SearchPagePolicy` |
|
||||
| 카테고리 응답 페이로드 조립 | `App\Search\SearchCategoryPayload` |
|
||||
| 커서 인코딩·디코딩 | `App\Support\Query\KeysetPaginator` |
|
||||
|
||||
확장이 선언하는 것은 **정렬 이름이 어떤 실제 컬럼인가** 둘뿐이다.
|
||||
|
||||
```php
|
||||
/** 정렬 이름 → [실제 컬럼, 방향]. 여기에 없는 이름은 커서를 쓰지 않는다. */
|
||||
public const SEARCH_SORT_MAP = [
|
||||
'latest' => ['created_at', 'desc'],
|
||||
'oldest' => ['created_at', 'asc'],
|
||||
];
|
||||
|
||||
/** 커서 경계로 쓸 수 있는 실제 컬럼 */
|
||||
public const SEARCH_CURSOR_COLUMNS = ['created_at'];
|
||||
```
|
||||
|
||||
서비스는 규칙을 다시 쓰지 않고 코어에 판정을 위임한다. 적용할 수 없는 정렬이면 `null` 을
|
||||
돌려주고, 호출자는 기존 offset 경로를 그대로 쓴다.
|
||||
|
||||
```php
|
||||
$sortKeys = SearchPagePolicy::sortKeys($sort, self::SEARCH_SORT_MAP);
|
||||
|
||||
if (! SearchPagePolicy::usesCursor($cursor, $sortKeys, self::SEARCH_CURSOR_COLUMNS)) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return $this->repository->searchByKeywordWithCursor($keyword, $sortKeys, $perPage, $cursor);
|
||||
```
|
||||
|
||||
### 관련도순에는 커서를 쓸 수 없다
|
||||
|
||||
커서는 정렬 키를 WHERE 절 경계로 삼으므로 정렬 키가 **실제 컬럼**이어야 한다. 관련도순은
|
||||
전문 검색 점수라는 계산값으로 정렬하므로 경계로 쓸 수 없고, 그 정렬에서는 offset 을
|
||||
유지한다. 이 판정은 선언에 그 이름이 없는 것으로 자연히 이루어진다.
|
||||
|
||||
### 응답 키 집합은 세 형태가 모두 같다
|
||||
|
||||
offset·커서·건수전용 세 응답은 채워지는 값만 다르고 키 구성은 동일하다. 화면이 분기 없이
|
||||
같은 키를 읽을 수 있어야 하기 때문이다.
|
||||
|
||||
| 키 | offset | 커서 | 건수전용 |
|
||||
|---|---|---|---|
|
||||
| `total` / `total_relation` / `total_is_exact` / `result_cap` | 채움 | 채움(별도 집계) | 채움 |
|
||||
| `last_page` | 상한 초과 시 `null` | 언제나 `null` | `null` |
|
||||
| `has_more_pages` | 실측 | 실측 | `false` |
|
||||
| `next_cursor` / `prev_cursor` | `null` | 채움 | `null` |
|
||||
| `items` | 채움 | 채움 | 빈 배열 |
|
||||
|
||||
커서 응답에 `last_page` 가 없는 것은 결함이 아니라 **커서 방식에 마지막 페이지 번호라는
|
||||
개념이 없기 때문**이다. 화면은 그때 마지막 페이지 점프만 감추고 "다음" 이동은 유지한다.
|
||||
|
||||
### 탭 배지에도 정확도가 따라간다
|
||||
|
||||
배지는 숫자 하나만 그리므로, 상한에 걸려 잘린 값이 정확한 것처럼 나가도 오류로 드러나지
|
||||
않고 그냥 틀린 숫자로만 보인다. 코어가 카테고리별 정확도를 `counts_are_exact` 로 일괄
|
||||
제공하며, 화면은 정확하지 않은 배지에 "이상" 표시를 붙인다.
|
||||
|
||||
---
|
||||
|
||||
## 관련 문서
|
||||
|
||||
- [대용량 목록 페이지네이션](pagination.md) - 상한 COUNT·커서 적용 기준
|
||||
- [Service-Repository 패턴](service-repository.md) - Repository에서 whereFulltext() 사용
|
||||
- [훅 시스템](../extension/hooks.md) - core.search.engine_drivers 필터 훅
|
||||
- [데이터베이스 가이드](../database-guide.md) - 마이그레이션 규칙
|
||||
|
||||
@@ -942,11 +942,25 @@ class OrderRepository implements OrderRepositoryInterface
|
||||
|
||||
`paginate` / `simplePaginate` / 캐시 total 주입은 인자로 구분한다 — inner 쿼리는 동일하고 COUNT 수행 여부와 반환 클래스만 달라진다.
|
||||
|
||||
| 호출자 상황 | `$simple` | `$total` | 반환 |
|
||||
| ------ | ------ | ------ | ------ |
|
||||
| 일반 목록 | `false` | `null` | `LengthAwarePaginator` (COUNT 1회) |
|
||||
| COUNT 를 피하고 다음 페이지 유무만 필요 | `true` | — | `Paginator` |
|
||||
| 총 건수를 이미 캐시해 둠 | `false` | 캐시값 | `LengthAwarePaginator` (COUNT 없음) |
|
||||
| 호출자 상황 | `$simple` | `$total` | `$resultCap` | 반환 |
|
||||
| ------ | ------ | ------ | ------ | ------ |
|
||||
| 일반 목록 | `false` | `null` | `null` | `LengthAwarePaginator` (COUNT 1회) |
|
||||
| COUNT 를 피하고 다음 페이지 유무만 필요 | `true` | — | — | `Paginator` |
|
||||
| 총 건수를 이미 캐시해 둠 | `false` | 캐시값 | `null` | `LengthAwarePaginator` (COUNT 없음) |
|
||||
| 계속 쌓이기만 하는 목록 (로그·회원 등) | `false` | `null` | 상한 | `BoundedPage` (상한 COUNT + `per_page + 1` 실측) |
|
||||
|
||||
상한을 지정하면 총 건수는 그 값까지만 세고, 다음 페이지 판정은 `per_page + 1` 실측으로 따로 한다. 계산이 불가능해지는 것은 마지막 페이지 번호 하나뿐이다. 상세는 [pagination.md](pagination.md).
|
||||
|
||||
```php
|
||||
return $this->paginateWithDeferredJoin(
|
||||
query: $query,
|
||||
columns: ['*'],
|
||||
sort: $sort,
|
||||
perPage: $perPage,
|
||||
relations: ['user:id,uuid,name,email'],
|
||||
resultCap: PaginationLimits::resultCap('admin.activity_logs'),
|
||||
);
|
||||
```
|
||||
|
||||
정렬 순서 복원은 `whereIn` + 같은 정렬 스펙 재적용으로 한다. 키 컬럼이 정렬에 포함돼 전순서가 성립하므로 결과가 inner 순서와 동일하다. MySQL 전용 `FIELD()` 는 쓰지 않는다. outer 에 존재하지 않는 표현식(집계·조인 서브쿼리)으로 정렬해 재현이 불가능한 경우에만 `$preserveIdOrder = true` 로 표준 SQL `CASE WHEN` 경로를 쓴다.
|
||||
|
||||
|
||||
+34
-2
@@ -8,7 +8,7 @@
|
||||
1. PHP 8.2+ 필수
|
||||
2. MySQL 8.0+ 또는 MariaDB 10.3+ (utf8mb4, utf8mb4_unicode_ci)
|
||||
3. PHP 필수 모듈 30개 (ctype, curl, gd, intl, redis, imagick 등)
|
||||
4. 디스크 용량: 최소 700MB / 권장 2GB+
|
||||
4. 하드웨어: 최소 2 vCPU·2GB / 권장 4 vCPU·8GB, 디스크 최소 700MB / 권장 2GB+
|
||||
5. 프로덕션: HTTPS 필수, Redis 권장, 큐 워커/스케줄러/Reverb 데몬 필요
|
||||
```
|
||||
|
||||
@@ -174,7 +174,39 @@ sudo chmod -R 755 storage bootstrap/cache vendor modules plugins templates
|
||||
|
||||
---
|
||||
|
||||
## 3. 디스크 용량
|
||||
## 3. 하드웨어 사양
|
||||
|
||||
### 3.1 CPU · 메모리
|
||||
|
||||
| 수준 | CPU | 메모리 | 상정 환경 |
|
||||
|------|-----|--------|----------|
|
||||
| 최소 | 2 vCPU | 2GB | 설치·기능 확인용. 동시 접속이 거의 없는 개발/검토 환경 |
|
||||
| 권장 | 4 vCPU | 8GB | 웹서버 + PHP-FPM + MySQL + Redis 를 한 대에 올린 소규모 운영 |
|
||||
| 분리 구성 | 웹 2 vCPU / DB 2 vCPU | 각 4GB 이상 | 트래픽이 늘면 DB 를 먼저 분리 |
|
||||
|
||||
메모리 배분은 어떤 구성 요소를 같은 서버에 올렸는지에 따라 달라진다. 한 대에 모두 올린
|
||||
경우 MySQL 의 `innodb_buffer_pool_size` 가 전체 메모리의 절반을 넘지 않도록 두고, PHP-FPM
|
||||
자식 프로세스 수 × `memory_limit` 가 남은 메모리를 넘지 않는지 확인한다.
|
||||
|
||||
위 수치는 코어와 번들 확장을 기본 설정으로 운영할 때의 출발점이다. 실제 필요량은 데이터
|
||||
규모·동시 접속·설치한 확장에 따라 달라지므로, 운영 전 대상 트래픽으로 직접 측정할 것을
|
||||
권한다(`php artisan g7:bench` 로 목록·화면·쓰기·배치 4축을 잰다).
|
||||
|
||||
**이 수치의 근거**
|
||||
|
||||
- **권장 4 vCPU · 8GB** — 사용자가 4 vCPU · 8GB 가상머신에서 수행한 운영 환경 측정 보고
|
||||
(`gnuboard/g7#82`)에서 코어와 번들 확장을 함께 올린 구성이 동작한 사양이다. 같은 보고에서
|
||||
대량 데이터의 검색·목록 조회는 이 사양에서도 메모리 압박이 관측되었으므로, "이 사양이면
|
||||
어떤 규모든 충분하다" 는 뜻이 아니라 **한 대 구성의 하한선**으로 읽어야 한다.
|
||||
- **최소 2 vCPU · 2GB** — 설치와 기능 확인이 가능한 수준으로, 위 보고의 측정 대상이 아니다.
|
||||
동시 접속이 있는 운영에는 적합하지 않다.
|
||||
- **분리 구성** — 위 보고에서 부하가 먼저 걸린 지점이 데이터베이스였다는 관측에 따른 순서
|
||||
제안이다. 분리 시점의 트래픽 임계값은 측정하지 않았다.
|
||||
|
||||
우리가 직접 측정한 범위는 쿼리 실행 횟수와 조회 구조이며, 특정 사양에서의 동시 접속 한계나
|
||||
응답 시간은 측정하지 않았다. 그 값이 필요하면 대상 환경에서 직접 재야 한다.
|
||||
|
||||
### 3.2 디스크 용량
|
||||
|
||||
| 수준 | 용량 | 포함 범위 |
|
||||
|------|------|----------|
|
||||
|
||||
Reference in new issue
Block a user