Anton3/kotlin-vk-api

API ВКонтакте на Kotlin с полной поддержкой асинхронности https://vk.com/dev/methods

Download

Step 1. Add the JitPack repository to your build file

Add it in your root settings.gradle at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url 'https://jitpack.io' }
		}
	}

Add it in your settings.gradle.kts at the end of repositories:

	dependencyResolutionManagement {
		repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
		repositories {
			mavenCentral()
			maven { url = uri("https://jitpack.io") }
		}
	}

Add to pom.xml

	<repositories>
		<repository>
		    <id>jitpack.io</id>
		    <url>https://jitpack.io</url>
		</repository>
	</repositories>

Add it in your build.sbt at the end of resolvers:

 
    resolvers += "jitpack" at "https://jitpack.io"

Add it in your project.clj at the end of repositories:

 
    :repositories [["jitpack" "https://jitpack.io"]]

Step 2. Add the dependency

	dependencies {
		implementation 'com.github.anton3:kotlin-vk-api:0.14.0'
	}
	dependencies {
		implementation("com.github.anton3:kotlin-vk-api:0.14.0")
	}
	<dependency>
	    <groupId>com.github.anton3</groupId>
	    <artifactId>kotlin-vk-api</artifactId>
	    <version>0.14.0</version>
	</dependency>

                            
    libraryDependencies += "com.github.anton3" % "kotlin-vk-api" % "0.14.0"
        
        

                            
    :dependencies [[com.github.anton3/kotlin-vk-api "0.14.0"]]

Readme

kotlin-vk-api

All Contributors Release

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

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

  1. Оригинальный набор файлов
  2. Набор патчей

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

Основная часть библиотеки работает хорошо - уж точно намного лучше, чем официальная либа. Расширенная поддержка методов в 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, ВК) — автор этого форка