Обработка ошибок загрузки

В прикладной разработке на базе OpenLayers основной поток данных поступает асинхронно: тайлы картографических сервисов, векторные объекты из GeoJSON/WFS, растровые изображения, данные с удалённых API. Любая из этих операций подвержена сбоям сети, ограничениям сервера, некорректным ответам и проблемам декодирования. Механизм обработки ошибок в OpenLayers распределён по уровням источников данных и событий слоя, что позволяет детально контролировать состояние загрузки и реагировать на сбои без блокировки рендеринга карты.

Архитектура загрузки данных и точки возникновения ошибок

Загрузка данных в OpenLayers разделяется на несколько независимых потоков:

  • загрузка тайлов (ol/source/XYZ, ol/source/TileWMS, ol/source/OSM)
  • загрузка изображений (ol/source/ImageStatic, ol/source/ImageWMS)
  • загрузка векторных данных (ol/source/Vector)
  • запросы через стратегии (bbox, tile, cluster, пользовательские стратегии)

Каждый поток имеет собственный жизненный цикл запроса и набор событий, отражающих стадии:

  • инициирование запроса
  • успешное получение данных
  • ошибка загрузки
  • повторная попытка (если реализована логика повторов)

Ошибки фиксируются на уровне источника (source), но часто транслируются на слой (layer), что позволяет централизованно реагировать на сбои.

Обработка ошибок тайловых слоёв

Тайловые источники являются наиболее чувствительными к нестабильности сети. Основные события:

  • tileloadstart
  • tileloadend
  • tileloaderror

Пример регистрации обработчика ошибок:

import TileLayer from 'ol/layer/Tile.js';
import XYZ from 'ol/source/XYZ.js';

const layer = new TileLayer({
  source: new XYZ({
    url: 'https://tile-server/{z}/{x}/{y}.png'
  })
});

layer.getSource().on('tileloaderror', function (event) {
  const tile = event.tile;
  const coord = tile.getTileCoord();
  const url = tile.getKey();

  console.error('Ошибка загрузки тайла:', coord, url);
});

Каждое событие содержит объект тайла, из которого можно извлечь:

  • координаты тайла
  • URL запроса
  • текущее состояние загрузки

Распространённой практикой является визуальное замещение повреждённых тайлов. OpenLayers позволяет задавать кастомное поведение через tileLoadFunction:

import XYZ from 'ol/source/XYZ.js';

const source = new XYZ({
  url: 'https://tile-server/{z}/{x}/{y}.png',
  tileLoadFunction: function (imageTile, src) {
    const img = imageTile.getImage();

    img.oner ror = function () {
      img.src = '/fallback-tile.png';
    };

    img.src = src;
  }
});

Подобная стратегия позволяет скрыть артефакты отсутствующих данных, сохраняя целостность визуализации.

Ошибки загрузки векторных данных

Векторные источники используют асинхронные загрузчики форматов (GeoJSON, KML, GPX). Ошибки возникают при:

  • некорректном JSON/XML
  • несоответствии формата
  • сетевых сбоях
  • нарушении CORS-политики

Основные события:

  • featuresloadstart
  • featuresloadend
  • featuresloaderror

Пример обработки:

import VectorSource from 'ol/source/Vector.js';

const source = new VectorSource({
  url: 'https://example.com/data.geojson',
  format: new GeoJSON()
});

source.on('featuresloaderror', function (event) {
  console.error('Ошибка загрузки векторных объектов');
});

В случае критических ошибок возможно переключение на резервный источник:

source.on('featuresloaderror', function () {
  source.setUrl('https://backup-server/data.geojson');
  source.refresh();
});

Контроль ошибок через загрузочные стратегии

При работе с большими наборами данных используется стратегия подгрузки:

  • bbox
  • tile
  • кастомные стратегии

Ошибки часто возникают на уровне частичных запросов, когда часть данных загружается успешно, а часть — нет.

Пример с bbox стратегией:

import VectorSource from 'ol/source/Vector.js';
import {bbox as bboxStrategy} from 'ol/loadingstrategy.js';

const source = new VectorSource({
  loader: function (extent, resolution, projection) {
    const url = `https://server/data?bbox=${extent.join(',')}`;

    fetch(url)
      .then(response => response.json())
      .then(data => {
        // обработка данных
      })
      .catch(() => {
        console.error('Ошибка загрузки bbox-данных');
      });
  },
  strategy: bboxStrategy
});

Здесь обработка ошибок переносится на уровень fetch, поскольку OpenLayers не всегда оборачивает пользовательские загрузчики.

Ошибки изображений в ImageLayer

Растровые источники (ImageWMS, ImageStatic) генерируют события:

  • imageloadstart
  • imageloadend
  • imageloaderror

Пример обработки:

import ImageLayer from 'ol/layer/Image.js';
import ImageWMS from 'ol/source/ImageWMS.js';

const layer = new ImageLayer({
  source: new ImageWMS({
    url: 'https://geoserver/wms',
    params: { LAYERS: 'layer_name' }
  })
});

layer.getSource().on('imageloaderror', function () {
  console.warn('Ошибка загрузки WMS-изображения');
});

Особенность WMS-запросов заключается в том, что ошибка может возвращать HTTP 200 с сообщением об ошибке внутри изображения (например, XML Exception Report). В таких случаях требуется дополнительная проверка содержимого через кастомный imageLoadFunction.

Кастомизация imageLoadFunction для обработки ошибок

import ImageWMS from 'ol/source/ImageWMS.js';

const source = new ImageWMS({
  url: 'https://geoserver/wms',
  params: { LAYERS: 'layer' },
  imageLoadFunction: function (image, src) {
    const img = image.getImage();

    img.onl oad = function () {
      const width = img.naturalWidth;
      const height = img.naturalHeight;

      if (width === 0 || height === 0) {
        console.error('Некорректное изображение');
      }
    };

    img.oner ror = function () {
      console.error('Ошибка загрузки изображения WMS');
    };

    img.src = src;
  }
});

Такая логика позволяет выявлять скрытые ошибки серверов картографических сервисов.

Ошибки при загрузке через fetch и CORS

При использовании пользовательских загрузчиков через fetch наиболее частыми проблемами являются:

  • блокировка CORS
  • таймаут запроса
  • отказ сервера (4xx, 5xx)
  • некорректный MIME-type

Пример расширенной обработки:

fetch('https://api.example.com/data')
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error ${response.status}`);
    }
    return response.json();
  })
  .then(data => {
    // обработка данных
  })
  .catch(error => {
    console.error('Ошибка сетевого запроса:', error);
  });

В OpenLayers такие запросы часто инкапсулируются в loader, поэтому контроль ошибок должен реализовываться на уровне источника.

Повторные попытки загрузки и деградация качества данных

При нестабильных сетях применяется стратегия повторных запросов. Типовой подход:

  • ограничение числа попыток
  • экспоненциальная задержка
  • переключение на резервный сервер
function fetchWithRetry(url, retries = 3) {
  return fetch(url).catch(err => {
    if (retries > 0) {
      return new Promise(resolve =>
        setTimeout(() => resolve(fetchWithRetry(url, retries - 1)), 1000)
      );
    }
    throw err;
  });
}

В контексте OpenLayers такая логика интегрируется в loader или tileLoadFunction.

Логирование и централизованный контроль ошибок

Для сложных картографических приложений применяется централизованная система логирования:

  • сбор ошибок источников (source)
  • агрегация событий слоя (layer)
  • передача в внешние системы мониторинга
function logMapError(type, payload) {
  console.log(`[MAP ERROR] ${type}`, payload);
}

layer.getSource().on('tileloaderror', e => {
  logMapError('tile', e.tile.getTileCoord());
});

layer.getSource().on('featuresloaderror', () => {
  logMapError('vector', 'vector load failed');
});

Подобный подход позволяет анализировать качество данных и стабильность внешних сервисов.

Состояния загрузки и синхронизация интерфейса

Ошибки загрузки тесно связаны с состояниями:

  • loading
  • loaded
  • error

Для синхронизации интерфейса часто используется счётчик активных запросов:

let pending = 0;

function inc() {
  pending++;
}

function dec() {
  pending--;
}

source.on('tileloadstart', inc);
source.on('tileloadend', dec);
source.on('tileloaderror', dec);

При pending > 0 интерфейс может отображать индикатор загрузки, а при ошибках — уведомления или fallback-слои.

Особенности ошибок при кэшировании и прокси

Использование HTTP-кэша, CDN и прокси-серверов создаёт дополнительные сценарии:

  • устаревшие тайлы
  • неконсистентные данные между слоями
  • ошибки 304, интерпретируемые как успешные ответы

OpenLayers не различает логически устаревшие данные, поэтому контроль целостности переносится на уровень URL-версий:

const source = new XYZ({
  url: 'https://tileserver/{z}/{x}/{y}.png?v=2'
});

Версионирование URL снижает вероятность некорректного кэширования.

Ошибки декодирования и форматов данных

При загрузке векторных данных возможны ошибки парсинга:

  • некорректный JSON
  • повреждённый XML
  • несоответствие схемы координат
import GeoJSON from 'ol/format/GeoJSON.js';

const format = new GeoJSON();

try {
  const features = format.readFeatures(invalidData);
} catch (e) {
  console.error('Ошибка декодирования GeoJSON', e);
}

Векторный слой при этом может частично игнорировать повреждённые объекты, что требует дополнительной валидации входных данных.

Системная модель устойчивости загрузки

Механизм обработки ошибок в OpenLayers формирует многоуровневую модель:

  • уровень источника данных (source)
  • уровень слоя (layer)
  • уровень сетевого транспорта (fetch, image, tile)
  • уровень приложения (логирование, fallback, UI)

Каждый уровень может независимо реагировать на сбои, обеспечивая устойчивость карты даже при частичной деградации внешних сервисов.

Оглавление