Cachear el contenido cargado de Docs
Antylogic carga el fichero empaquetado de contenido de Docs una vez por proceso del backend para las peticiones GET de Docs que no son de assets, y reutiliza ese bundle en memoria mientras la fecha de modificación del fichero fuente no avance.
En este artículo
Antylogic sirve la documentación pública y la de la app desde un fichero articles.json empaquetado. Cuando una petición GET normal de Docs llega al backend, el servicio de contenido de Docs carga ese bundle en memoria y lo usa tanto para el índice de Docs como para las respuestas de detalle de artículo.
Los operadores ven el resultado como el índice y las páginas de artículo de Docs cargándose desde el mismo bundle de documentación publicado. El acierto de caché no es visible en la interfaz, así que la validación debe usar peticiones GET de índice y de detalle, no comprobaciones HEAD ni rutas de assets.
Antes de empezar
- Las rutas de Docs del backend están registradas y en ejecución.
- DOCS_CONTENT_PATH resuelve al directorio del contenido empaquetado de Docs o directamente a un fichero JSON de contenido.
- El fichero de contenido de Docs desplegado es legible y se decodifica correctamente. En este repositorio la fuente empaquetada es backend/docs-content/articles.json.
- Para la Docs autenticada de la app, el operador ha iniciado sesión como usuario demo en Grupo Marea Demo / Marea Gran Via con preferencias en español es-ES.
- Usa una petición GET que no sea de assets. Las peticiones HEAD y las rutas /assets/... se saltan el cargador del bundle de artículos.
Instrucciones
- 1.
Confirma que el bundle de Docs está disponible
Antes de comprobar Docs en la superficie pública o en la app, confirma que el backend desplegado puede leer el bundle de contenido de Docs. Si DOCS_CONTENT_PATH apunta a un directorio, el backend espera articles.json dentro. Si DOCS_CONTENT_PATH apunta directamente a un fichero .json, se usa ese fichero. Si falta el contenido se devuelve una respuesta service-unavailable de docs-not-configured, y si es ilegible o el JSON es inválido se devuelve un error interno docs-not-available.
- 2.
Abre un índice de Docs que no sea de assets
Abre GET /api/public/docs o la superficie autenticada GET /api/app/docs. El primer GET correcto que no sea de assets tras el arranque del backend carga el bundle de Docs en la caché local del proceso. La Docs pública no requiere autenticación de la app; la Docs de la app se gestiona dentro del envoltorio de rutas autenticadas.
- 3.
Abre el detalle de un artículo desde la misma superficie
Desde el índice de Docs, abre el detalle de un artículo. Para el plan de capturas de ES, usa GET /api/app/docs/accesos/es-access-users-create-location-internal. Cuando la fecha de modificación del fichero fuente no ha avanzado, la respuesta de detalle se construye a partir del mismo bundle cargado que usó el índice.
- 4.
Sabe cuándo se sirve contenido nuevo
Cuando articles.json se sustituye por otro con una fecha de modificación posterior, el siguiente GET de Docs que no sea de assets recarga el bundle y reemplaza el contenido cacheado para ese proceso del backend. Si el fichero cambia con la misma fecha de modificación o una anterior, el proceso sigue sirviendo el bundle cacheado hasta que se reinicie o el fichero reciba una fecha posterior.
- 5.
Evita las rutas de bypass para comprobar la caché
No uses HEAD /api/public/docs, HEAD /api/app/docs ni GET /api/*/docs/assets/{path} para verificar la carga del bundle. HEAD responde antes de cargar el bundle y las peticiones de assets se sirven antes de que se ejecute docsContentService.load.
Validaciones y límites
- handleDocs solo acepta GET y HEAD; el resto de métodos se rechazan antes de cargar contenido.
- docsContentService.load hace stat del fichero de contenido resuelto antes de comprobar la caché o leer el JSON.
- La condición de acierto de caché se basa en que la fecha de modificación actual del fichero no sea posterior a la fecha cacheada.
- La Docs pública y la autenticada comparten la misma instancia de docsContentService creada durante el registro de rutas.
- Locale, plataforma, tema, filtrado por consulta, búsqueda de artículo y resolución de URLs de media ocurren después de cargar el bundle compartido y no crean cachés de contenido separadas.
- La caché es local al proceso y no se distribuye entre instancias del backend.
- No se encontró ningún test dedicado en el repositorio para la invalidación de caché por mtime.
Resultado esperado
Los operadores pueden validar que el índice y las páginas de detalle de Docs están disponibles desde el mismo bundle publicado, entendiendo que el comportamiento real de recarga lo controlan el proceso del backend y la fecha de modificación del fichero de contenido.