Paginación desde repoGenerico: un solo contrato

01 / EL PROBLEMA

¿Para qué sirve?

Si cada pantalla inventa su paginación, los clientes reciben formatos, límites y errores distintos. El equipo necesita un punto común que también guíe el código generado con IA.

02 / COMPRENDER

El concepto, explicado

La consulta paginada es una funcionalidad de repoGenerico, no una función nueva que deba copiarse a cada app. Primero se elige la base: BaseListView para DataTables o presentación HTML/JSON, BaseListQueryView para JSON paginado simple y BaseListAllView solo para conjuntos completos acotados.

El flujo común valida parámetros, obtiene el queryset autorizado, cuenta el conjunto permitido, aplica búsqueda, cuenta coincidencias, ordena, pagina y serializa únicamente la página. La aplicación aporta modelo, serializer, permisos, búsqueda y campos; no vuelve a escribir Paginator en cada Query.

El máximo compartido examinado es 100. El adaptador convencional usa page y per_page. DataTables usa start, length, draw y search[value], y se identifica mediante X-DataTables-Request: true. La columna enviada por el navegador se resuelve con datatables_columns, nunca se acepta como expresión ORM arbitraria.

recordsTotal cuenta el conjunto autorizado antes de buscar y recordsFiltered las coincidencias después de buscar. Si cuentas todos los clientes antes de filtrar autorización, el número puede revelar información aunque las filas no se muestren.

La versión de la academia usa un contrato JSON reducido y devuelve 400 ante orden inválido; la base de tablas examinada recurre al orden por defecto. No son contratos idénticos. Para un proyecto concreto acuerda una sola política y pruébala: no cambies de comportamiento por lo que proponga una herramienta de generación.

El orden necesita un desempate único cuando hay valores repetidos. Añadir id o pk en la base es una mejora explícita que debe probarse; no debe asumirse que ya está en todas las implementaciones. Incluso un orden estable puede cambiar entre peticiones si llegan datos nuevos; si se requiere una vista consistente, evalúa snapshot o paginación por cursor.

get_page normaliza páginas fuera del rango. Para DataTables, convertir start a número de página supone offsets alineados con length: 20/10 corresponde a página 3. Un start de 15 no representa lo mismo que la página 2 de tamaño 10. Decide rechazar offsets no alineados o usar slicing validado en el adaptador común, sin resolverlo de forma distinta en cada tabla.

Elegir y conservar el contrato

DECISIONES DE LA BIBLIOTECA COMPARTIDA

03 / CONSTRUIR

Implementación paso a paso

1. Identificar si la pantalla necesita JSON simple, DataTables o una lista acotada completa.
2. Heredar la base correspondiente y declarar modelo, serializer y permisos.
3. Restringir get_queryset antes de contar; optimizar relaciones necesarias.
4. Personalizar búsqueda y orden mediante hooks, sin copiar get.
5. Verificar máximo de página, valores inválidos, conjunto vacío, orden y contadores.
6. Cambiar el núcleo compartido solo con una prueba que cubra sus consumidores.

"""Vistas genéricas sobre ORM, para la academia pública."""
from django.core.paginator import Paginator
from rest_framework.views import APIView
from rest_framework.response import Response
class BaseListQueryView(APIView):
    model=None
    serializer_class=None
    allowed_ordering=('number',)
    def get_queryset(self):return self.model.objects.all()
    def apply_search(self,queryset,search):return queryset
    def get(self,request):
        try:
            page=int(request.query_params.get('page',1))
            size=int(request.query_params.get('per_page',10))
        except (TypeError,ValueError):return Response({'success':False,'error':'Paginación inválida.'},status=400)
        if page<1 or not 1<=size<=100:return Response({'success':False,'error':'page >= 1; per_page entre 1 y 100.'},status=400)
        ordering=request.query_params.get('ordering','number')
        if ordering.lstrip('-') not in self.allowed_ordering:return Response({'success':False,'error':'Orden no permitido.'},status=400)
        queryset=self.apply_search(self.get_queryset(),request.query_params.get('search','')[:200]).order_by(ordering)
        paginator=Paginator(queryset,size)
        result=paginator.get_page(page)
        return Response({'success':True,'results':self.serializer_class(result.object_list,many=True).data,'total_count':paginator.count,'current_page':result.number,'total_pages':paginator.num_pages})


# Consumidor REAL: academy/views/queries/catalog.py
from django.db.models import Q
from repoGenerico.views_base import BaseListQueryView
from academy.models import Lesson
from academy.serializers import LessonSerializer
class CatalogQuery(BaseListQueryView):
    model=Lesson
    serializer_class=LessonSerializer
    def apply_search(self,queryset,search):
        return queryset.filter(Q(title__icontains=search)|Q(concept__icontains=search)) if search else queryset

Cómo leer el ejemplo

• Este código sí existe en la academia y sirve /api/catalogo/.
• CatalogQuery hereda get y solo implementa la búsqueda particular.
• La validación y Paginator viven en repoGenerico; cada app no crea otra variante.
• Esta base es JSON simple: no afirma implementar DataTables ni toda la familia CRUD.

06 / VERIFICAR

Cómo sabes que funciona

• Las subclases no duplican Paginator ni el handler.
• El contrato de cada modo está documentado.
• Los conteos no atraviesan el alcance autorizado.
• Una misma prueba de parámetros se aplica a varios consumidores.

Para profundizar

Documentación oficial para comprobar configuración, permisos y condiciones vigentes. Revisión del tema: 2026-10-12.

• DRF: vistas genéricas y clases propias ↗
• DRF: paginación reutilizable ↗