Planfact.KodySu.Client

Типобезопасный .NET клиент для работы с KodySu API v2.1 с поддержкой кеширования.

Особенности

• Типобезопасность - используются strongly typed модели вместо магических строк
• Надежность - политики повтора (retry), circuit breaker для обработки сбоев
• HTTP-кеширование - прозрачное кеширование ответов API (10 минут TTL)
• Мульти-таргетинг - поддержка .NET 6.0, 8.0 и 9.0
• Логирование - структурированное логирование всех операций
• Конфигурируемость - настройка через appsettings.json или код
• DI интеграция - готовые расширения для ASP.NET Core

Установка

dotnet add package Planfact.KodySu.Client

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

1. Регистрация в DI контейнере

// Базовый клиент без кеширования
services.AddKodySuClient(Configuration);

// Кешированный клиент (рекомендуется)
services.AddCachedKodySuClient(Configuration);

2. Конфигурация через appsettings.json

{
  "KodySuOptions": {
    "ApiKey": "your-api-key",
    "TimeoutSeconds": 30
  }
}

3. Использование

public class PhoneService
{
    private readonly IKodySuClient _kodySuClient;

    public PhoneService(IKodySuClient kodySuClient)
    {
        _kodySuClient = kodySuClient;
    }

    public async Task<string> GetOperatorAsync(string phoneNumber)
    {
        var result = await _kodySuClient.SearchPhoneAsync(phoneNumber);

        if (result?.Success == true)
        {
            return result.Operator ?? "Неизвестный оператор";
        }

        return "Номер не найден";
    }

    public async Task<IReadOnlyList<KodySuResult>> SearchMultipleAsync(
        IEnumerable<string> phoneNumbers)
    {
        return await _kodySuClient.SearchPhonesAsync(phoneNumbers);
    }
}

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

├── IKodySuClient.cs                      # Интерфейс клиента
├── KodySuClientBase.cs                   # Базовый класс с общей функциональностью
├── KodySuClient.cs                       # Основная реализация HTTP клиента
├── CachedKodySuClient.cs                 # Реализация с HTTP-кэшированием
├── KodySuServiceCollectionExtensions.cs  # Регистрация в DI
├── KodySuClientOptions.cs                # Настройки клиента
├── KodySuHttpResponseHandler.cs          # Обработчик HTTP ответов
├── KodySuResult.cs                       # Модель результата поиска
├── KodySuSearchResponse.cs               # Модель ответа API
├── KodySuPhoneType.cs                    # Перечисление типов номеров
├── KodySuExceptions.cs                   # Исключения клиента
├── KodySuErrorCodes.cs                   # Коды ошибок API
└── PhoneNumber.cs                        # Модель телефонного номера

Конфигурация

Опции клиента

public class KodySuClientOptions : HttpClientOptions
{
    public string ApiKey { get; set; } = string.Empty;
    public int CacheExpiryMinutes { get; set; } = 60;

    // Унаследованные настройки:
    // public string BaseUrl { get; set; } = "https://www.kody.su";
    // public int TimeoutSeconds { get; set; } = 30;
    // public string UserAgent { get; set; } = "Planfact-KodySu-Client/1.0";
}

Расширенная конфигурация

{
  "KodySuOptions": {
    "ApiKey": "your-api-key",
    "BaseUrl": "https://www.kody.su",
    "TimeoutSeconds": 60,
    "UserAgent": "MyApp-KodySu-Client/1.0",
    "CacheExpiryMinutes": 60
  }
}

Модели данных

KodySuResult

public class KodySuResult
{
    public string PhoneNumber { get; set; }
    public bool Success { get; set; }
    public string? Operator { get; set; }
    public string? OperatorFull { get; set; }
    public string? Country { get; set; }
    public string? City { get; set; }
    public string? DefCode { get; set; }
    // ... другие свойства
}

Типы номеров

public enum KodySuPhoneType
{
    RussianMobile,
    RussianFixed,
    Other
}

Кеширование

Кешированный клиент (CachedKodySuClient) автоматически кеширует ответы API:

• TTL: 10 минут (MediumTerm preset)
• Размер кеша: 1,000 записей
• Автоматическое управление: очистка старых записей
• Прозрачность: кеширование на уровне HTTP ответов

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

Клиент использует типизированные исключения для различных типов ошибок:

try
{
    var result = await _kodySuClient.SearchPhoneAsync("+79001234567");
}
catch (KodySuAuthenticationException ex)
{
    // Ошибки аутентификации (401, 403)
    Console.WriteLine($"Проблемы с API ключом: {ex.Message}");
}
catch (KodySuValidationException ex)
{
    // Ошибки валидации от API
    Console.WriteLine($"Ошибка валидации: {ex.ErrorCode} - {ex.Message}");
}
catch (KodySuHttpException ex)
{
    // Прочие HTTP ошибки
    Console.WriteLine($"HTTP ошибка: {ex.StatusCode}");
}

Автоматические политики надежности

• Retry: автоматические повторы при транзиентных ошибках
• Circuit Breaker: защита от каскадных сбоев
• Rate Limiting: обработка ответов 429 (Too Many Requests)

Тестирование и покрытие кода

Проект имеет комплексную стратегию тестирования с высоким покрытием:

• 70 unit тестов - полное покрытие основной функциональности
• Snapshot тестирование - Verify.Xunit для автоматического обнаружения изменений API контрактов
• Integration тесты - валидация с реальным kody.su API для выявления breaking changes
• Параллельное выполнение - unit и integration тесты выполняются параллельно в CI
• Кроссплатформенное тестирование - macOS, Ubuntu, Windows
• Автоматическое покрытие - интеграция с Codecov

Запуск тестов локально

# Запуск всех тестов
dotnet test

# Только unit тесты (быстрые)
dotnet test --filter "Category!=Integration"

# Только integration тесты (требуют API ключ)
export KodySu__ApiKey="your-api-key"
dotnet test --filter "Category=Integration"

# Запуск с генерацией HTML отчета о покрытии
./coverage.sh

Важно: Integration тесты требуют реальный API ключ от kody.su и выполняют реальные HTTP запросы.

После выполнения ./coverage.sh откройте ./CoverageReport/index.html в браузере для просмотра детального отчета.

Лицензия

Этот проект лицензирован под MIT License.