kotlin-vk-api

API ВКонтакте сгенерированное на основе схемы с исправленными ошибками c поддержкой корутин.

На текущий момент поддерживается версия VK API 5.131. Её нужно указывать в настройках LongPoll и Callback группы.

Установка

Gradle:

repositories {
    jcenter()
    maven(url = "https://jitpack.io")
}

dependencies {
    implementation("com.github.Anton3:kotlin-vk-api:0.13.1")
}

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

Для начала, создайте один на всё приложение VkClientFactory:

val apacheClient: CloseableHttpAsyncClient = defaultHttpAsyncClient()
val clientFactory: VkClientFactory = apacheClientFactory()

Создайте клиент ВК нужного типа:

val client: GroupClient = clientFactory.group(GroupToken(accessToken))

Используйте этот клиент для выполнения всех запросов, подпадающих под один и тот же лимит запросов ВК:

val wallpost: WallpostFull = client(WallGet(domain = "departureMsk"))

В конце программы стоит всё закрыть:

clientFactory.closeAndJoin()
apacheClient.close()

Замечание. Клиент учитывает ограничения ВК на запросы к API и объединяет несколько запросов в один через Execute, когда это возможно. Тип клиента зависит от прав на выполнение методов. Выполнение метода на клиенте с несовместимым токеном порождает ошибку на этапе компиляции.

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

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

Ошибки VK API: VkApiException
Ошибки соединения: IOException
Ошибки парсинга JSON: JsonProcessingException
Другие ошибки при запросе и парсинге ответа: IOException

Где-то на высоком уровне их следует перехватывать и обрабатывать:

while (true) {
    try {
        // Receive commands, make requests
    } catch (e: VkApiException) {
        log.warn("Request failed with code: ${e.vkError.errorCode}", e)
    } catch (e: IOException) {
        log.warn("Connection error: ", e)
    }
}

Чтобы «проглотить» ошибки при выполнении какого-то метода, можно воспользоваться swallow:

val response: WallpostFull? = swallow { client(WallGet(domain = "departureMsk")) }
println(response)

Можно запросто написать расширение для VkClient<R>, обрабатывающее ошибки нужным вам образом:

suspend inline fun <R : MethodRequirement, T : Any> VkClient<R>.call(
    method: VkMethod<T, R>
): T? = swallow { this(method) }

LongPoll и Callback

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

Логи

// build.gradle.kts
implementation("org.apache.logging.log4j:log4j-slf4j-impl:2.13.0")

В вашей папке resources должен быть файл log4j2.xml, вот пример.

Кастомные запросы

val method = VkMethod<MyResponse, MyRequirement>("wall.get", jacksonTypeRef())
method.unsafeParam("my_first_param", "foo")
method.unsafeParam("my_second_param", "bar")
val response: MyResponse = client(method)

Структура библиотеки

Библиотека разбита на следующие модули:

vk-api-generator — генератор кода запросов и ответов из JSON-схемы
vk-api-core — основная часть библиотеки, не зависящая от конкретных методов, предоставляемых ВК
vk-api-generated — сгенерированные методы и ответы ВК
vk-api-methods — обёртка над vk-api-generated. Исправляет сериализацию некоторых сгенерированных классов, а также предоставляет удобный интерфейс для таких методов, как Callback API, LongPoll API, Upload
vk-api-ktor — привязка к Ktor
vk-api-apache — привязка к Apache AsyncHttpClient
vk-api-simple — включает все модули и предоставляет apacheClientFactory

Т.к. оригинальная схема написана неряшливо, каких-то планов по ее поддержке не озвучено, то в проекте она хранится в следующем виде:

Статус библиотеки

Основная часть библиотеки работает хорошо - уж точно намного лучше, чем официальная либа. Расширенная поддержка методов в vk-api-methods недоработана.

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

Процесс разработки

Разработка ведётся в ветке develop. После прогона нескольких тестов, новый функционал отправляется в master.

Как внести свой вклад

Для любых ошибок или предложений заводите Issue, будем разбираться. Если есть желание заняться реализацией, то:

Заводим Issue
Форкаем репозиторий
Регистрируем на jitpack.io
Перенаправляем на него свои зависимости от kotlin-vk-api
Создаём на базе develop ветку feature-...
Создаём Pull Request
Кодим и коммитим любые изменения
Пишем в Issue, что PR #такой-то готов и решает этот Issue
PR приниимается или отклоняется. Если отклоняется, то вы в любом случае можете создать Release в своём форке и пользоваться своими изменениями дальше

Доработки основного кода библиотеки

vk-api-base, vk-api-core, executors

Дополнения и исправления в JSON-схеме

Дополнения принимаются или в виде новых небольших патчей для JSON-схемы, или в виде доработки vk-api-generator.

Доработки интерфейса методов

Расширенная поддержка методов vk-api-methods находится на ранней стадии разработки. Многое отсутствует. Любая помощь принимается.

Авторы

@alatushkin (email, ВК) — автор оригинального репозтория и первоначальной версии API
@Anton3 (email, ВК) — автор этого форка

Anton3 / kotlin-vk-api