Правильная обработка ошибок в REST API WordPress

При создании REST API эндпоинтов в WordPress часто упускается важный момент — грамотная обработка ошибок. Без корректной обработки ошибок API может возвращать неинформативные ответы или вовсе некорректные коды состояния HTTP, что затрудняет отладку и ухудшает опыт пользователей и разработчиков, работающих с вашим API.

Почему правильная обработка ошибок в WP REST API важна

REST API должен возвращать понятные и стандартизированные ответы при возникновении ошибок. Это помогает:

• Клиенту API быстро понять причину проблемы и принять меры.
• Упростить отладку и поддержку кода.
• Повысить безопасность, не раскрывая лишнюю информацию.
• Соблюдать стандарты HTTP и REST.

В WordPress для этого существует класс WP_Error, который нужно использовать в своих обработчиках.

Использование WP_Error для обработки ошибок

WP_Error — это удобный класс для генерации и возврата ошибок, который понимает WP REST API и автоматически преобразует объект в корректный JSON-ответ с нужным HTTP статусом.

Вот простой пример функции-обработчика, которая возвращает ошибку при отсутствии обязательного параметра:

function wpapi_restapi_handle_request(\WP_REST_Request $request) {
    $param = $request->get_param('my_param');
    if (empty($param)) {
        return new WP_Error(
            'wpapi_missing_param',
            'Параметр my_param обязателен',
            array('status' => 400)
        );
    }
    // Дальнейшая обработка
    return array('success' => true);
}

Обратите внимание на третий параметр — массив с ключом status, который задаёт HTTP-код ответа (здесь 400 — ошибка клиента).

Создание универсальной функции обработки ошибок в WPAPI

Чтобы не дублировать код, можно создать вспомогательную функцию для генерации ошибок с правильным префиксом и параметрами:

function wpapi_generate_error($code, $message, $status = 400) {
    return new WP_Error(
        'wpapi_' . $code,
        $message,
        array('status' => $status)
    );
}

Пример использования:

if (!$user = get_user_by('id', $user_id)) {
    return wpapi_generate_error('user_not_found', 'Пользователь не найден', 404);
}

Обработка ошибок в разных сценариях REST API

Валидация входных данных

Валидация параметров — частая причина ошибок. Вместо возврата простого false или null, возвращайте WP_Error с подробным сообщением и HTTP кодом 400.

Полезно детализировать ошибки, если несколько параметров неверны. Например, можно вернуть массив ошибок с ключами параметров.

Обработка ошибок при взаимодействии с базой

Если запрос к базе данных или внешнему сервису не удался, возвращайте ошибку с кодом 500 или 503, если сервис временно недоступен.

Не раскрывайте подробностей SQL или внутренней структуры. Используйте общее сообщение типа «Внутренняя ошибка сервера».

Проверка прав доступа

Если пользователь не авторизован или не имеет прав, возвращайте ошибку с кодом 401 (Unauthorized) или 403 (Forbidden). Это важный момент для безопасности.

Пример:

if (!current_user_can('edit_posts')) {
    return wpapi_generate_error('forbidden', 'Доступ запрещён', 403);
}

Пример комплексного обработчика с ошибками

function wpapi_restapi_process_data(\WP_REST_Request $request) {
    $data = $request->get_param('data');
    if (empty($data)) {
        return wpapi_generate_error('missing_data', 'Параметр data обязателен', 400);
    }

    if (!current_user_can('edit_posts')) {
        return wpapi_generate_error('forbidden', 'Недостаточно прав', 403);
    }

    global $wpdb;
    $table = $wpdb->prefix . 'custom_table';
    $result = $wpdb->insert($table, array('data' => sanitize_text_field($data)));

    if ($result === false) {
        return wpapi_generate_error('db_error', 'Ошибка при сохранении данных', 500);
    }

    return array('success' => true, 'id' => $wpdb->insert_id);
}

Дополнительные рекомендации по обработке ошибок в WPAPI

Логирование ошибок

Для отладки полезно логировать ошибки в файл или систему мониторинга. Например, используя функции error_log() или плагины типа Clearfy Pro с расширенными настройками логирования.

Международная поддержка сообщений

Для мультиязычных сайтов используйте функции локализации __() и _e() для сообщений ошибок, чтобы обеспечить удобство пользователей.

Документирование ошибок в API

Обязательно опишите возможные ошибки в документации вашего API, чтобы разработчики знали, какие коды и сообщения ожидать.

Заключение

Обработка ошибок в REST API WordPress с помощью WP_Error — это обязательный элемент качественной разработки. Это улучшает стабильность, безопасность и удобство использования API. Рекомендуется всегда возвращать корректные коды HTTP и информативные сообщения, а также использовать вспомогательные функции для упрощения кода.

Если вы хотите расширить возможности API и добавить дополнительные инструменты для работы с ошибками, рассмотрите плагины и решения на WPSHOP.RU.