Shikicrate

Rust клиент для Shikimori GraphQL API. Потому что парсить JSON руками — это прошлый век.

Что это вообще такое?

Нужен доступ к аниме, манге, персонажам и прочей японской культуре через Shikimori? Не хочешь писать GraphQL запросы вручную? Добро пожаловать. Клиент сам разберется с retry-логикой, rate limiting и прочими радостями жизни.

Установка

Кидай в Cargo.toml:

[dependencies]
shikicrate = "<актуальная версия>"

Или для локальной разработки (если хочешь поковырять код):

[dependencies]
shikicrate = { path = "../shikicrate" }

Быстрый старт

use shikicrate::{ShikicrateClient, queries::*};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ShikicrateClient::new()?;
    
    // Ищем Наруто (или что там тебе нужно)
    let params = AnimeSearchParams {
        search: Some("naruto".to_string()),
        limit: Some(10),
        kind: None,
    };
    
    let animes = client.animes(params).await?;
    
    for anime in animes {
        println!("{} (ID: {})", anime.name, anime.id);
    }
    
    Ok(())
}

Что умеет

Аниме

let params = AnimeSearchParams {
    limit: Some(10),
    search: Some("naruto".to_string()),
    kind: None,
};

let animes = client.animes(params).await?;

Манга

let params = MangaSearchParams {
    limit: Some(5),
    search: Some("one piece".to_string()),
    kind: None,
};

let mangas = client.mangas(params).await?;

Персонажи

Можно искать по странице, можно по ID — как удобнее:

// По странице
let params = CharacterSearchParams {
    page: Some(1),
    limit: Some(20),
    ids: None,
};

let characters = client.characters(params).await?;

// Или по ID (если знаешь, кого ищешь)
let params = CharacterSearchParams {
    page: None,
    limit: None,
    ids: Some(vec!["1".to_string(), "2".to_string()]),
};

let characters = client.characters(params).await?;

Люди (режиссеры, сценаристы и прочие)

let params = PeopleSearchParams {
    limit: Some(10),
    search: Some("miyazaki".to_string()),
};

let people = client.people(params).await?;

Пользовательские оценки

let params = UserRateSearchParams {
    page: Some(1),
    limit: Some(20),
    target_type: Some("Anime".to_string()),
    order_field: Some("updated_at".to_string()),
    order: Some("desc".to_string()),
};

let user_rates = client.user_rates(params).await?;

Настройка клиента

Builder (если любишь цепочки методов)

use shikicrate::ShikicrateClientBuilder;
use std::time::Duration;

let client = ShikicrateClientBuilder::new()
    .timeout(Duration::from_secs(60))
    .base_url("https://shikimori.one/api/graphql".to_string())
    .build()?;

Прямое создание (если не любишь)

use shikicrate::ShikicrateClient;

// Дефолтные настройки (30 секунд таймаут)
let client = ShikicrateClient::new()?;

// С кастомным таймаутом
let client = ShikicrateClient::with_timeout(Duration::from_secs(60))?;

// С кастомным URL (если у тебя свой инстанс)
let client = ShikicrateClient::with_base_url("https://api.example.com/graphql".to_string())?;

Обработка ошибок

Клиент сам разбирается с:

• Rate limiting (429): ждет Retry-After и повторяет запрос
• Сетевые ошибки: ретраит до 3 раз с экспоненциальной задержкой (1s → 2s → 4s)
• GraphQL ошибки: возвращает все сообщения об ошибках
• Валидация: проверяет параметры до отправки (чтобы не тратить время зря)

use shikicrate::{ShikicrateError, Result};

match client.animes(params).await {
    Err(ShikicrateError::RateLimit { retry_after, .. }) => {
        println!("Rate limit, retry after: {:?} seconds", retry_after);
    }
    Err(ShikicrateError::Validation(msg)) => {
        println!("Validation error: {}", msg);
    }
    Ok(animes) => println!("Found {} animes", animes.len()),
    Err(e) => eprintln!("Error: {}", e),
}

Примеры

Запусти пример, чтобы посмотреть, как это работает:

cargo run --example test_client

Там показывается:

• Поиск аниме с фильтрами
• Поиск манги
• Поиск персонажей (по странице и по ID)
• Поиск людей
• Вывод детальной информации

Структура проекта

• src/client.rs — HTTP клиент, который делает всю грязную работу
• src/error.rs — типы ошибок (чтобы знать, что пошло не так)
• src/types.rs — типы данных (Anime, Manga, Character, Person и т.д.)
• src/queries.rs — методы для выполнения запросов
• animes, mangas, characters, people, userrates — GraphQL запросы

Тесты

cargo test

Лицензия

MIT OR Apache-2.0 — используй как хочешь.