api-pagination-standard

name	api-pagination-standard
description	API 리스트 엔드포인트의 페이지네이션·필터링·정렬 구현을 분석하고, 통일된 표준 규격을 수립한다.
argument-hint	[API 코드베이스|리스트 엔드포인트|대상 디렉토리] (선택: 선호 방식)
user-invocable	true
disable-model-invocation	true
allowed-tools	Read, Grep, Glob

당신은 신중한 시니어 엔지니어다. $ARGUMENTS 를 대상으로 아래 작업을 수행하라.

목적

API의 리스트형 엔드포인트에서 사용되는 페이지네이션, 필터링, 정렬 방식을 분석하고 통일된 표준을 수립한다.
현행 구현의 불일치 지점을 식별하고, 클라이언트가 일관된 방식으로 데이터를 조회할 수 있도록 표준 스펙을 정의한다.
대용량 데이터 처리 효율성, 성능, 사용성의 균형을 고려한다.

입력

• API 코드베이스 디렉토리 또는 리스트 엔드포인트 파일 (필수)
• 기존 페이지네이션 규약 (선택)
• 예상 데이터 규모 (선택)
• 선호 방식 (offset / cursor / keyset) (선택)
• 정보가 부족하면 사용자에게 질의할 것

절차

1. 현행 구현 분석

   • Grep으로 page, limit, offset, cursor, per_page, skip, take 등 검색
   • 필터 구현 방식 분석 (query param / body / DSL)
   • 정렬 파라미터 (sort, order, order_by) 탐색
   • 응답 메타데이터 구조 수집
   • 엔드포인트 간 불일치 목록화

2. 페이지네이션 방식 결정

   • Offset / Cursor / Keyset 비교
   • 데이터 규모 및 실시간성 고려
   • 기본 페이지 크기 및 최대 제한 정의

3. 필터링 규격 설계

   • 파라미터 네이밍 규칙 정의
   • 지원 연산자 정의
   • 화이트리스트 기반 필드 제한
   • 잘못된 파라미터 처리 정책 정의

4. 정렬 규격 설계

   • 단일 및 복수 필드 정렬 문법 정의
   • 허용 필드 제한
   • 기본 정렬 정의
   • 인덱스 전략 고려

5. 응답 구조 표준화

   • meta 구조 통일
   • 방식별 응답 샘플 정의
   • total_count 반환 정책 정의
   • 빈 결과 처리 방식 정의

6. 이행 계획 수립

   • 기존 엔드포인트별 수정 필요 여부 판단
   • 우선순위 정의
   • 후방 호환 유지 전략 수립
   • 신규 엔드포인트 가이드라인 작성

출력 포맷

## 페이지네이션·필터·정렬 표준 규격서

### 현행 분석

#### 발견된 패턴

| 엔드포인트 | 페이지네이션 | 필터 | 정렬 | 통일 여부 |
|------------|--------------|-------|-------|------------|
| [PATH] | [limit/offset] | [query 기반] | [sort=] | 불일치 |

#### 불일치 항목

| 항목 | 패턴 A | 패턴 B | 대상 엔드포인트 |
|------|--------|--------|----------------|
| 페이지 크기 | limit | per_page | [/users, /orders] |

### 표준 규격

#### 페이지네이션

- **채택 방식**: Cursor 기반 (대규모 데이터 대응)
- **선정 이유**: 대용량 데이터에서 안정적이며 offset 성능 저하 방지
- **기본 페이지 크기**: 20
- **최대 페이지 크기**: 100

**요청 예시**

GET /api/v1/resources?page=2&per_page=20

**응답 구조**:
```json
{
  "data": [...],
  "meta": {
    "current_page": 2,
    "per_page": 20,
    "total_count": 150,
    "total_pages": 8
  },
  "links": {
    "first": "/api/v1/resources?page=1&per_page=20",
    "prev": "/api/v1/resources?page=1&per_page=20",
    "next": "/api/v1/resources?page=3&per_page=20",
    "last": "/api/v1/resources?page=8&per_page=20"
  }
}

필터링

• 파라미터 형식: [예시: filter[field]=value]
• 화이트리스트 기반 필드 제한
• 잘못된 필터 파라미터: 400 오류 반환
• 지원 연산자:

연산자	형식	예시	설명
등가	filter[field]=value	filter[status]=active	완전 일치
이상	filter[field][gte]=value	filter[price][gte]=1000	하한
이하	filter[field][lte]=value	filter[price][lte]=5000	상한
부분일치	filter[field][like]=value	filter[name][like]=kim	LIKE
다중값	filter[field]=a,b	filter[status]=active,pending	IN

정렬

• 형식: [예시: sort=field / sort=-field(내림차순)]
• 복수 필드: [예시: sort=status,-created_at]
• 기본 정렬: [예시: -created_at(새로운 순서)]
• 정렬 가능 필드 제한: 인덱스 필드만 허용

요청 예시:

GET /api/v1/resources?sort=-created_at,name&filter[status]=active&page=1&per_page=20

성능 고려 사항

항목	대응 전략	비고
COUNT 비용	total_count 기본 미포함	요청 시 옵션 제공
대량 offset	Cursor 방식 기본 적용	deep pagination 방지
인덱스 미정렬	허용 필드 제한	성능 보호

이행 계획

엔드포인트	현재 방식	변경 사항	우선순위	호환성 전략
/users	offset 기반	cursor 방식 도입	P1	기존 파라미터 3개월 유지
/orders	limit/per_page 혼용	limit 통일	P2	deprecated 경고

신규 엔드포인트 가이드라인

1. 리스트 API는 반드시 본 표준 준수
2. 필터 가능 필드는 문서에 명시
3. 기본 정렬 필수 정의
4. 최대 페이지 크기 초과 시 400 반환
5. total_count는 옵션 요청 시만 계산

## 안전 유의사항

- 문서 작성만 수행하고 구현 변경은 하지 않는다.
- SQL 인젝션 위험 패턴 발견 시 반드시 경고한다.
- 필터 대상에 민감 정보가 포함되지 않도록 주의한다.
- 대규모 데이터 전량 반환 가능 구조는 반드시 지적한다.
- total_count 계산이 성능에 미치는 영향 명시한다.

---

## 종료 조건

위 형식에 따른 표준 규격서를 출력하면 종료한다.  
페이지네이션·필터링·정렬 규칙이 명확히 정의되어 있고, 현행 구현과의 차이 및 이행 계획이 포함되어야 한다.  
실제 코드 수정은 사용자 지시를 기다린다.