Filtering, Sorting, Sparse Fieldset — Query 도구상자

# 흔한 query 면 네 가지 — 한 endpoint 에서

# Filtering (equality + IN list + range)
curl 'https://api.example.com/users?role=admin&status=active,pending&created_at_gte=2026-01-01'

# Sorting (multi-field, descending 에 sign-prefix)
curl 'https://api.example.com/users?sort=-created_at,name'

# Sparse fieldset (각 항목 trim)
curl 'https://api.example.com/users?fields=id,display_name,avatar_url'

# 관련 include (N+1 회피)
curl 'https://api.example.com/users/42?include=orders,profile'

# 위에 pagination (Lesson 3.5)
curl 'https://api.example.com/users?cursor=usr_abc&limit=20&sort=-created_at&fields=id,name'

# FastAPI — 모든 면 네 가지 validation 과 함께 연결
from fastapi import FastAPI, Query, HTTPException
from typing import Annotated

app = FastAPI()

ALLOWED_SORT_FIELDS = {'created_at', 'updated_at', 'name'}
ALLOWED_FIELDS = {'id', 'name', 'email', 'role', 'created_at'}
ALLOWED_INCLUDES = {'orders', 'profile'}

@app.get('/users')
async def list_users(
    role: str | None = None,                          # filter
    status: str | None = None,                        # filter (comma-sep IN)
    created_at_gte: str | None = None,                # filter (range)
    sort: str = '-created_at',                        # sign prefix 가진 sort
    fields: str | None = None,                        # sparse fieldset
    include: str | None = None,                       # 관련
    limit: int = Query(20, ge=1, le=100),
    cursor: str | None = None,
):
    # Sort 필드 validate
    sort_fields = [s.lstrip('-+') for s in sort.split(',')]
    invalid = set(sort_fields) - ALLOWED_SORT_FIELDS
    if invalid:
        raise HTTPException(400, detail=f'sort: 잘못된 필드 {invalid}, 허용: {ALLOWED_SORT_FIELDS}')

    # Field whitelist validate
    if fields:
        requested = set(fields.split(','))
        if not requested.issubset(ALLOWED_FIELDS):
            raise HTTPException(400, detail=f'fields: {requested - ALLOWED_FIELDS} 허용 안 됨')

    # Include validate
    if include:
        wanted = set(include.split(','))
        if not wanted.issubset(ALLOWED_INCLUDES):
            raise HTTPException(400, detail=f'include: {wanted - ALLOWED_INCLUDES} 미지원')

    # ... 그 다음 query 빌드, fetch, 필드 projection 적용, include eager-load
    return await fetch_users(
        filters={'role': role, 'status': status, 'created_at_gte': created_at_gte},
        sort=sort_fields,
        fields=requested if fields else ALLOWED_FIELDS,
        includes=wanted if include else set(),
        limit=limit,
        cursor=cursor,
    )

# Query parameter 가 GET 넘었을 때 — POST + JSON body 로 전환
from fastapi import FastAPI

app = FastAPI()

# 중첩 boolean 로직 가진 복잡 search — query string 엔 너무 많음
@app.post('/users/search')
async def search_users(query: dict):
    """
    POST /users/search
    {
      "where": {
        "or": [
          {"status": "active"},
          {"and": [{"role": "admin"}, {"last_login_gte": "2026-05-01"}]}
        ]
      },
      "sort": [{"field": "created_at", "dir": "desc"}],
      "fields": ["id", "display_name", "role"],
      "include": ["orders"],
      "limit": 20
    }
    """
    # State 안 바꾸는 body 가진 POST 가 기술적으로 un-RESTful (POST 가 safe 아니어야).
    # 일탈 문서화; 8KB URL 보다 나음.
    return await complex_query(query)