питон либ луна питонлиб солнце progerlib цветок

Thema wechseln

Anmelden Registrierung
🦀 Rust

Netzwerk- und HTTP-API-Programmierung in Rust: Eine ausführliche Anleitung

Lektion 33 / 35 • Vollständige Lektüre-Theorie

Что это такое и зачем? (аналогия из реальной жизни)

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

Работа с сетью и HTTP API — это ровно то же самое, только в мире программирования. Ваша программа — это посетитель кафе. Она хочет получить какие-то данные (например, список сегодняшних фильмов в кинотеатре или прогноз погоды). Она не лезет напрямую в базу данных кинотеатра — это невозможно и небезопасно. Вместо этого она отправляет запрос (как заказ официанту) на специальный адрес в интернете — API (Application Programming Interface, программный интерфейс приложения). Сервер, который владеет этими данными, получает запрос, обрабатывает его и отправляет обратно ответ — обычно в формате JSON (универсальный язык для обмена данными, похожий на словарь в Python).

Важно: HTTP — это протокол, то есть набор правил, по которым общаются программы в интернете. API — это конкретный "вход" в программу на сервере, который умеет принимать запросы и отдавать данные.

Зачем это нужно в реальной жизни? Представьте, что вы пишете приложение-погоду. Вы не можете сами измерить температуру во всём мире. Но вы можете обратиться к API сервиса погоды (например, OpenWeatherMap), отправить ему название города, и он пришлёт вам температуру, влажность и скорость ветра. Всё это происходит за доли секунды.

В Rust работа с сетью особенно важна, потому что этот язык часто используют для создания высоконагруженных серверов и микросервисов — программ, которые должны обрабатывать тысячи запросов в секунду без сбоев. Rust даёт нам скорость C/C++, но при этом безопасность памяти, что критически важно для сетевых приложений.

Теория: как это работает изнутри

Чтобы понять, как работает HTTP, нужно разобрать его на составные части. Весь процесс можно разделить на четыре этапа:

1. URL — адрес, по которому мы стучимся

URL (Uniform Resource Locator) — это адрес ресурса в интернете. Он состоит из нескольких частей:

  • Протокол: http:// или https:// (защищённая версия с шифрованием)
  • Домен: example.com — имя сервера
  • Порт: :80 (для HTTP) или :443 (для HTTPS) — "дверь", в которую стучимся. Если порт не указан, используется стандартный.
  • Путь: /api/v1/users — указывает на конкретный ресурс на сервере
  • Параметры запроса (query string): ?city=Moscow&units=metric — дополнительные данные, которые передаются в строке запроса

2. HTTP-методы — глаголы, описывающие действие

Когда вы отправляете запрос, вы должны сказать серверу, что именно вы хотите сделать. Для этого существуют HTTP-методы. Самые популярные:

Метод Действие Аналогия в жизни
GET Получить данные Посмотреть меню ресторана
POST Создать новый ресурс Сделать заказ
PUT Полностью заменить ресурс Переписать заново список покупок
PATCH Частично изменить ресурс Исправить одну строчку в заказе
DELETE Удалить ресурс Отменить заказ

3. Заголовки (Headers) — метаданные запроса

Заголовки — это дополнительная информация, которая передаётся вместе с запросом или ответом. Например:

  • User-Agent — кто отправляет запрос (браузер, ваша программа)
  • Content-Type — формат данных, которые вы отправляете (например, application/json)
  • Authorization — токен для доступа к защищённым данным
  • Accept — какой формат ответа вы ожидаете

4. Тело запроса и ответа (Body)

В теле запроса (для POST, PUT, PATCH) вы передаёте данные, которые хотите отправить на сервер. В теле ответа сервер присылает вам то, что вы просили. Чаще всего это JSON — текстовый формат, который выглядит как вложенные словари и списки.

5. Коды ответа — результат операции

Сервер всегда отвечает числовым кодом, который говорит о результате операции:

Код Категория Примеры
200-299 Успех 200 OK — всё хорошо; 201 Created — создано
300-399 Перенаправление 301 Moved Permanently — адрес изменился
400-499 Ошибка клиента 400 Bad Request — вы отправили что-то не то; 404 Not Found — ресурс не найден; 401 Unauthorized — нужен токен
500-599 Ошибка сервера 500 Internal Server Error — сломалось на сервере

Синтаксис в Rust: все формы и варианты

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

Чтобы начать работу, добавьте в файл Cargo.toml зависимость:

[dependencies]
reqwest = { version = "0.12", features = ["json"] }
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
serde_json = "1"
Важно: tokio — это асинхронный рантайм для Rust. Без него асинхронные функции работать не будут. serde — это библиотека для сериализации (превращения данных в JSON и обратно).

Основные структуры и методы reqwest

Тип/Метод Описание
reqwest::Client::new() Создаёт HTTP-клиента. Клиента лучше создавать один раз и переиспользовать.
client.get(url) Создаёт GET-запрос
client.post(url) Создаёт POST-запрос
.header(name, value) Добавляет заголовок к запросу
.json(&data) Отправляет данные в формате JSON в теле запроса
.query(¶ms) Добавляет параметры в строку запроса (для GET)
.send().await Отправляет запрос и ждёт ответ
.text().await Получает тело ответа как строку
.json::<T>().await Парсит тело ответа в структуру типа T
.status() Возвращает код статуса ответа

Примеры кода — от простого к сложному

Пример 1: Простой GET-запрос (получение HTML страницы)

// Пример 1: Простейший GET-запрос
// Импортируем всё необходимое
use reqwest;

// Асинхронная функция main — точка входа
#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    // Создаём HTTP-клиента
    let client = reqwest::Client::new();
    
    // Отправляем GET-запрос на сайт example.com
    // .send() отправляет запрос, .await ждёт ответ
    let response = client
        .get("https://httpbin.org/get")  // httpbin — сервис для тестирования запросов
        .send()
        .await?;  // ? — если ошибка, функция вернёт её
    
    // Получаем тело ответа как текст
    let body = response.text().await?;
    
    // Печатаем результат
    println!("Ответ сервера:
{}", body);
    
    Ok(())
}

Объяснение: Мы создали клиента, отправили GET-запрос на тестовый сервер httpbin, который просто возвращает нам обратно всё, что мы ему отправили. await нужен, потому что запрос асинхронный — программа не блокируется, пока ждёт ответ. ? — это оператор распространения ошибки: если запрос не удался, функция завершится с ошибкой.

Пример 2: Обработка кода статуса и заголовков

// Пример 2: Проверяем код ответа и читаем заголовки
use reqwest;

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = reqwest::Client::new();
    
    let response = client
        .get("https://httpbin.org/status/404")  // Этот URL вернёт 404
        .send()
        .await?;
    
    // Получаем код статуса
    let status_code = response.status();
    println!("Код статуса: {}", status_code);
    
    // Проверяем, успешен ли запрос
    if status_code.is_success() {
        println!("Запрос выполнен успешно!");
    } else if status_code.is_client_error() {
        println!("Ошибка клиента (4xx)");
    } else if status_code.is_server_error() {
        println!("Ошибка сервера (5xx)");
    }
    
    // Читаем заголовок Content-Type из ответа
    if let Some(content_type) = response.headers().get("content-type") {
        println!("Тип содержимого: {:?}", content_type);
    }
    
    // Получаем тело ответа (даже если это ошибка, тело может содержать пояснение)
    let body = response.text().await?;
    println!("Тело ответа: {}", body);
    
    Ok(())
}

Объяснение: Не все запросы возвращают 200 OK. Мы научились проверять код статуса с помощью методов is_success(), is_client_error() и is_server_error(). Также мы прочитали заголовок content-type, который говорит нам, в каком формате пришли данные.

Пример 3: GET-запрос с параметрами в строке

// Пример 3: Передаём параметры в GET-запросе
use reqwest;
use std::collections::HashMap;

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = reqwest::Client::new();
    
    // Создаём словарь с параметрами запроса
    let mut params = HashMap::new();
    params.insert("name", "Алиса");
    params.insert("age", "25");
    
    // Отправляем GET-запрос с параметрами
    // httpbin.org/get?name=Алиса&age=25
    let response = client
        .get("https://httpbin.org/get")
        .query(¶ms)  // Добавляем параметры
        .send()
        .await?;
    
    let body = response.text().await?;
    println!("{}", body);
    
    Ok(())
}

Объяснение: Метод .query() принимает ссылку на коллекцию пар ключ-значение. Он сам превратит их в строку вида ?name=Алиса&age=25 и добавит к URL. Это удобно, когда нужно передать много параметров.

Пример 4: POST-запрос с JSON-телом

// Пример 4: Отправляем данные на сервер с помощью POST
use reqwest;
use serde::{Serialize, Deserialize};

// Определяем структуру для данных, которые будем отправлять
// Serialize — позволяет превратить структуру в JSON
// Deserialize — позволяет превратить JSON обратно в структуру
#[derive(Debug, Serialize, Deserialize)]
struct User {
    name: String,
    email: String,
    age: u8,
}

// Структура для ответа от сервера
#[derive(Debug, Deserialize)]
struct ApiResponse {
    json: User,  // httpbin возвращает то, что мы отправили, в поле "json"
}

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = reqwest::Client::new();
    
    // Создаём пользователя
    let new_user = User {
        name: "Иван Петров".to_string(),
        email: "ivan@example.com".to_string(),
        age: 30,
    };
    
    // Отправляем POST-запрос
    // .json() автоматически сериализует структуру в JSON
    // и устанавливает заголовок Content-Type: application/json
    let response = client
        .post("https://httpbin.org/post")
        .json(&new_user)
        .send()
        .await?;
    
    // Парсим ответ обратно в структуру ApiResponse
    let response_data: ApiResponse = response.json().await?;
    
    println!("Сервер подтвердил получение:");
    println!("Имя: {}", response_data.json.name);
    println!("Email: {}", response_data.json.email);
    println!("Возраст: {}", response_data.json.age);
    
    Ok(())
}

Объяснение: Это самый важный пример. Мы используем библиотеку serde для автоматического превращения Rust-структуры в JSON и обратно. Атрибуты #[derive(Serialize, Deserialize)] добавляют нашей структуре методы для сериализации. Метод .json() делает всю работу за нас — не нужно вручную создавать строку JSON.

Пример 5: Добавление заголовков и авторизация

// Пример 5: Работа с заголовками и токеном авторизации
use reqwest;

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = reqwest::Client::new();
    
    // Предположим, у нас есть секретный токен для доступа к API
    let auth_token = "my_secret_token_12345";
    
    // Отправляем запрос с кастомными заголовками
    let response = client
        .get("https://httpbin.org/headers")  // Этот URL возвращает все заголовки запроса
        .header("Authorization", format!("Bearer {}", auth_token))
        .header("X-Custom-Header", "my_value")
        .header("User-Agent", "RustApp/1.0")
        .send()
        .await?;
    
    let body = response.text().await?;
    println!("Заголовки, которые мы отправили:
{}", body);
    
    Ok(())
}

Объяснение: Многие API требуют авторизации. Обычно это делается через заголовок Authorization со значением Bearer <токен>. Метод .header() позволяет добавить любой заголовок. Также мы установили User-Agent — хороший тон указывать, какая программа делает запрос.

Пример 6: Обработка ошибок и повторные попытки

// Пример 6: Надёжный запрос с обработкой ошибок
use reqwest;
use std::time::Duration;

#[tokio::main]
async fn main() {
    // Создаём клиента с таймаутом — если сервер не ответит за 5 секунд, будет ошибка
    let client = reqwest::Client::builder()
        .timeout(Duration::from_secs(5))
        .build()
        .expect("Не удалось создать HTTP-клиента");
    
    // Пытаемся выполнить запрос до 3 раз
    let max_retries = 3;
    let mut attempt = 0;
    
    loop {
        attempt += 1;
        println!("Попытка {} из {}", attempt, max_retries);
        
        // Отправляем запрос
        let result = client
            .get("https://httpbin.org/delay/3")  // Этот URL отвечает с задержкой 3 секунды
            .send()
            .await;
        
        // Обрабатываем результат
        match result {
            Ok(response) => {
                if response.status().is_success() {
                    let body = response.text().await.unwrap_or_default();
                    println!("Успех! Ответ: {}", body);
                    break;  // Выходим из цикла
                } else {
                    println!("Ошибка сервера: {}", response.status());
                }
            }
            Err(e) => {
                println!("Ошибка соединения: {}", e);
            }
        }
        
        // Если попытки закончились, выходим с ошибкой
        if attempt >= max_retries {
            println!("Не удалось получить ответ после {} попыток", max_retries);
            break;
        }
        
        // Ждём 1 секунду перед следующей попыткой
        println!("Ждём 1 секунду...");
        tokio::time::sleep(Duration::from_secs(1)).await;
    }
}

Объяснение: В реальном мире сети нестабильны. Мы создали клиента с таймаутом (если сервер не отвечает 5 секунд — ошибка). Затем мы делаем до 3 попыток с паузой в 1 секунду. Конструкция match позволяет обработать и успех, и ошибку. Это называется retry pattern (шаблон повторных попыток).

Пример 7: Работа с реальным API (JSONPlaceholder)

// Пример 7: Получаем список постов с реального API
use reqwest;
use serde::Deserialize;

// Структура для одного поста
#[derive(Debug, Deserialize)]
struct Post {
    userId: u32,
    id: u32,
    title: String,
    body: String,
}

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
    let client = reqwest::Client::new();
    
    // JSONPlaceholder — бесплатный API для тестирования
    // Получаем список постов
    let response = client
        .get("https://jsonplaceholder.typicode.com/posts")
        .send()
        .await?;
    
    // Парсим ответ как вектор постов
    // .json::<Vec<Post>>() — говорим Rust, что ожидаем список структур Post
    let posts: Vec<Post> = response.json().await?;
    
    println!("Получено {} постов", posts.len());
    println!("Первый пост:");
    println!("  Заголовок: {}", posts[0].title);
    println!("  Текст: {}", posts[0].body);
    
    // Отправляем новый пост (POST-запрос)
    let new_post = Post {
        userId: 1,
        id: 0,  // Сервер сам назначит ID
        title: "Мой первый пост из Rust".to_string(),
        body: "Этот пост был создан с помощью reqwest!".to_string(),
    };
    
    let create_response = client
        .post("https://jsonplaceholder.typicode.com/posts")
        .json(&new_post)
        .send()
        .await?;
    
    let created_post: Post = create_response.json().await?;
    println!("Создан новый пост с ID: {}", created_post.id);
    
    Ok(())
}

Объяснение: Это пример работы с реальным API. Мы получаем список постов и парсим его в вектор структур. Затем создаём новый пост с помощью POST-запроса. Обратите внимание: мы используем один и тот же клиент для нескольких запросов — это эффективно, потому что клиент поддерживает пул соединений.

Сравнение с Python: чем похоже и чем отличается

Если вы знакомы с Python и библиотекой requests, то многое покажется вам знакомым. Но есть и важные отличия.

Аспект Python (requests) Rust (reqwest)
Синхронность По умолчанию синхронный (блокирующий) По умолчанию асинхронный (неблокирующий), нужен .await
Создание клиента requests.get() — создаётся каждый раз Client::new() — лучше создать один раз и переиспользовать
Параметры запроса params={"key": "value"} .query(¶ms)
JSON response.json() возвращает словарь response.json::<T>() требует указать тип T
Обработка ошибок response.raise_for_status() Проверка response.status().is_success() или match
Типизация Динамическая (словари, списки) Статическая (нужны структуры с Deserialize)
Производительность Хорошая для скриптов Отличная, нулевая стоимость абстракций

Главное отличие: В Python вы пишете response = requests.get(url) и программа ждёт. В Rust вы пишете response = client.get(url).send().await? — это асинхронно, программа может делать другие дела, пока ждёт ответ. Rust также заставляет вас явно обрабатывать все возможные ошибки (через Result и Option), в то время как Python может просто выбросить исключение.

Совет: Если вы привыкли к Python, вам может показаться, что Rust требует слишком много кода для простых вещей. Но это плата за безопасность и производительность. Со временем вы привыкнете и оцените, что компилятор отлавливает ошибки ещё до запуска программы.

Типичные ошибки и подводные камни

1. Забыли добавить await

Самая частая ошибка новичков. Если вы напишете client.get(url).send() без .await, вы получите не ответ, а Future — обещание выполнить запрос в будущем. Компилятор скажет что-то вроде future cannot be sent between threads safely. Всегда ставьте .await после .send().

2. Не указали тип при парсинге JSON

Если вы напишете response.json().await? без указания типа, компилятор не сможет понять, во что парсить. Всегда указывайте тип: response.json::<MyStruct>().await? или let data: MyStruct = response.json().await?;.

3. Игнорирование кодов ошибок

Многие новички просто вызывают .text().await? не проверяя статус. Но если сервер вернул 404, тело ответа может быть пустым или содержать сообщение об ошибке. Всегда проверяйте response.status().is_success() перед тем, как читать тело.

4. Создание нового клиента для каждого запроса

Создание Client::new() — не бесплатная операция. Клиент создаёт пул соединений, настраивает TLS и т.д. Создавайте клиента один раз и передавайте его во все функции, которым нужны HTTP-запросы.

5. Забыли про таймауты

По умолчанию у reqwest нет таймаута. Если сервер зависнет, ваша программа будет ждать вечно. Всегда устанавливайте таймаут через Client::builder().timeout(Duration::from_secs(10)).

6. Проблемы с кодировкой

Rust работает с UTF-8 строками. Если сервер возвращает данные в другой кодировке (например, Windows-1251), вы получите ошибку. Используйте response.bytes().await? для получения сырых байтов и затем конвертируйте их вручную.

7. Паника при ошибке

Использование .unwrap() или .expect() в продакшене — плохая практика. Если запрос не удался, программа упадёт. Всегда используйте match или оператор ? для graceful обработки ошибок.

Лучшие практики и советы профессионалов

1. Используйте единый клиент

Создайте клиента один раз в начале программы и передавайте его через аргументы функций или храните в глобальной переменной (например, с помощью once_cell или lazy_static).

2. Настройте повторные попытки

Сеть ненадёжна. Используйте библиотеку reqwest-retry или напишите свой простой retry-механизм, как в примере 6. Обычно достаточно 3 попыток с экспоненциальной задержкой.

3. Логируйте запросы

В продакшене всегда включайте логирование. Используйте крейт tracing или log. Логируйте URL, метод, код ответа и время выполнения. Это поможет отлаживать проблемы.

4. Ограничивайте размер ответа

Злоумышленник может отправить вам гигантский ответ, чтобы исчерпать память. Используйте .content_length_limit() при создании клиента.

5. Используйте типизированные структуры для API

Всегда создавайте структуры для запросов и ответов. Это делает код самодокументируемым и позволяет компилятору проверять корректность данных. Используйте #[serde(rename_all = "camelCase")], если API использует camelCase, а вы предпочитаете snake_case.

6. Не доверяйте данным из сети

Всегда проверяйте, что пришло от сервера. Если вы ожидаете число, проверьте, что это действительно число. Используйте serde с валидацией (например, крейт validator).

7. Используйте HTTPS

Никогда не отправляйте пароли и токены по незащищённому соединению. Всегда используйте https://. reqwest по умолчанию поддерживает HTTPS.

Вопросы для самопроверки

  1. Что такое HTTP API простыми словами?
    Ответ: Это "официант" между вашей программой и сервером. Вы отправляете запрос, сервер обрабатывает его и присылает ответ.
  2. Какие HTTP-методы вы знаете и за что они отвечают?
    Ответ: GET (получить), POST (создать), PUT (заменить), PATCH (изменить частично), DELETE (удалить).
  3. Что означает код ответа 404?
    Ответ: Not Found — ресурс по указанному адресу не найден. Это ошибка клиента (4xx).
  4. Зачем нужен крейт serde при работе с JSON?
    Ответ: serde автоматически превращает Rust-структуры в JSON (сериализация) и обратно (десериализация). Это избавляет от ручного парсинга строк.
  5. ← Vorherige Multithreading und Asynchronität in Rust: Eine aus Weiter → Code-Testen in Rust: Eine ausführliche Anleitung