使用API

安装

plugins {
    // 或使用 kotlin("multiplatform")
    // 但是不管是什么，你都需要 kotlin 插件来支持自动选择对应平台的依赖。
    kotlin("jvm") version "1.9.21"
    // 其他一些插件, 随你喜欢
    `[[[java|https://docs.gradle.org/current/userguide/java_plugin.html#header]]]` // 你依旧可以使用 Java 编写代码
    `[[[application|https://docs.gradle.org/current/userguide/application_plugin.html]]]` // 使用 application 可以打包你的应用程序
}
// 其他配置...
dependencies {
    implementation("love.forte.simbot.component:simbot-component-miyoushe-villa-api:0.2.0")
    // 其他依赖..
}

plugins {
    // 或使用 org.jetbrains.kotlin.multiplatform，
    // 但是不管是什么，你都需要 kotlin 插件来支持自动选择对应平台的依赖。
    id 'org.jetbrains.kotlin.jvm' version '1.9.21'
    // 其他一些插件, 随你喜欢
    id '[[[java|https://docs.gradle.org/current/userguide/java_plugin.html#header]]]' // 你依旧可以使用 Java 编写代码
    id '[[[application|https://docs.gradle.org/current/userguide/application_plugin.html]]]' // 使用 application 可以打包你的应用程序
}
// 其他配置...
dependencies {
    implementation 'love.forte.simbot.component:simbot-component-miyoushe-villa-api:0.2.0'
    // 其他依赖..
}

<dependency>
    <groupId>love.forte.simbot.component</groupId>
    <!-- Maven 需要添加 `-jvm` 后缀来选择使用 JVM 平台 -->
    <artifactId>simbot-component-miyoushe-villa-api-jvm</artifactId>
    <version>0.2.0</version>
</dependency>

然后选择一个合适的 Ktor 引擎。

Ktor引擎: 你可以前往 Ktor文档处选择一个对应所用平台下合适的 Client Engine。这里会根据不同平台提供几个示例，你可以选择其他可用目标。

CIO 是一个比较通用的引擎。在不知道选什么的情况下，可以考虑使用它。
runtimeOnly("io.ktor:ktor-client-cio-jvm:$ktor_version")
runtimeOnly 'io.ktor:ktor-client-cio-jvm:$ktor_version'
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-cio-jvm</artifactId> <version>${ktor_version}</version> <scope>runtime</scope> </dependency>

如果你打算使用 Java11+，也可以选择 Java 引擎。

runtimeOnly("io.ktor:ktor-client-java:$ktor_version")

如果你想要显式配置引擎，那么就不能使用 runtimeOnly 了。
runtimeOnly 'io.ktor:ktor-client-java:$ktor_version'

如果你想要显式配置引擎，那么就不能使用 runtimeOnly 了。
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-client-java-jvm</artifactId> <version>${ktor_version}</version> <scope>runtime</scope> </dependency>

如果你想要显式配置引擎，那么就不能使用 runtime scope 了。

JavaScript 平台下可以选择 Js 引擎。
implementation("io.ktor:ktor-client-js:$ktor_version")
implementation 'io.ktor:ktor-client-js:$ktor_version'

native 平台目标下，可能需要根据不同的平台类型选择不同的引擎。

可以选择 WinHttp 引擎。
implementation("io.ktor:ktor-client-winhttp:$ktor_version")
implementation 'io.ktor:ktor-client-winhttp:$ktor_version'

Linux 下依旧可以选择 CIO 引擎。
implementation("io.ktor:ktor-client-cio:$ktor_version")
implementation 'io.ktor:ktor-client-cio:$ktor_version'

可以选择 Darwin 引擎。
implementation("io.ktor:ktor-client-darwin:$ktor_version")
implementation 'io.ktor:ktor-client-darwin:$ktor_version'

使用

大别野组件的API模块提供了针对米游社大别野API 的基本对应封装。

API封装的命名与API具有一定关联，例如 获取大别野信息：

GET /vila/api/bot/platform/getVilla

love.forte.simbot.miyoushe.api.villa.GetVillaApi

API的应用大差不差，因此此处仅使用部分类型作为示例，不会演示所有API。

// 准备 bot 的必要信息
val botId = "bot_xxxx"
val botSecret = "xxxx"
// 大别野ID，请求时作为token的一员。
val villaId = "1234"
// 构建请求用的 token
val token = MiyousheVillaApiToken(botId, botSecret, villaId)

// 准备一个用于 HTTP 请求的 [[[HttpClient|https://ktor.io/docs/create-client.html]]]
// 如果使用 JVM，你需要确保 classpath 环境中添加了合适的 [[[引擎|https://ktor.io/docs/http-client-engines.html]]]
// 如果使用其他平台，例如 JS 或 native，则可能需要添加了合适的引擎依赖后手动填入它们，以 mingwx64 平台为例：`HttpClient(WinHttp)`。
val httpClient = HttpClient()

// 构建需要请求的 API 示例，此处为 [[[获取房间信息|https://webstatic.mihoyo.com/vila/bot/doc/room_api/get_room.html]]] API
val roomId: ULong = 1234u // 假设房间ID是 1234
val api = GetRoomApi.create(roomId)

// 发起请求并得到结果。在 API 模块中有三种请求方式（均为挂起函数）：
// 1️⃣ 使用 api.request, 得到 Ktor 进行 HTTP 请求的原始响应类型 HttpResponse
val response: HttpResponse = api.request(httpClient, token)

// 2️⃣ 使用 api.requestResult, 得到请求结果的统一响应体结构。假如此响应代表成功(result.retcode == 0), 则可以通过 result.data 获取响应结果。
val result: ApiResult<GetRoomResult> = api.requestResult(httpClient, token)

// 3️⃣ 使用 api.requestData, 得到当响应体代表成功时的响应数据。如果响应体不为成功则会抛出异常。
val requestData: GetRoomResult = api.requestData(httpClient, token)

// 准备 bot 的必要信息
var botId = "bot_xxxx";
var botSecret = "xxxx";
// 大别野ID，请求时作为token的一员。
var villaId = "1234";
// 构建请求用的 token
var token = new MiyousheVillaApiToken(botId, botSecret, villaId);

// 准备一个用于 HTTP 请求的 [[[HttpClient|https://ktor.io/docs/create-client.html]]]
// 你需要确保 classpath 环境中添加了合适的 [[[引擎|https://ktor.io/docs/http-client-engines.html]]]
var client = HttpClientJvmKt.HttpClient((config) -> Unit.INSTANCE);

// 构建需要请求的 API 示例，此处为 [[[获取房间信息|https://webstatic.mihoyo.com/vila/bot/doc/room_api/get_room.html]]] API
// 假设房间ID是 1234
var api = GetRoomApi.create(Long.parseUnsignedLong("1234"));
// Java 中操作无符号数字比较麻烦，因此面向Java的大部分相关操作也会提供基于字符串操作的重载、扩展API
var api = GetRoomApi.create("1234");

// 发起请求并得到结果。在 API 模块中有三种请求方式（均使用 `APIRequests` 的静态方法）：
// 1️⃣ 使用 api.request, 得到 Ktor 进行 HTTP 请求的原始响应类型 HttpResponse
HttpResponse response = APIRequests.requestBlocking(api, client, token);

// 2️⃣ 使用 api.requestResult, 得到请求结果的统一响应体结构。假如此响应代表成功(result.retcode == 0), 则可以通过 result.data 获取响应结果。
ApiResult<GetRoomResult> result = APIRequests.requestResultBlocking(api, client, token);

// 3️⃣ 使用 api.requestData, 得到当响应体代表成功时的响应数据。如果响应体不为成功则会抛出异常。
GetRoomResult requestData = APIRequests.requestDataBlocking(api, client, token);

import java.util.concurrent.CompletableFuture;// 准备 bot 的必要信息
var botId = "bot_xxxx";
var botSecret = "xxxx";
// 大别野ID，请求时作为token的一员。
var villaId = "1234";
// 构建请求用的 token
var token = new MiyousheVillaApiToken(botId, botSecret, villaId);

// 准备一个用于 HTTP 请求的 [[[HttpClient|https://ktor.io/docs/create-client.html]]]
// 你需要确保 classpath 环境中添加了合适的 [[[引擎|https://ktor.io/docs/http-client-engines.html]]]
var client = HttpClientJvmKt.HttpClient((config) -> Unit.INSTANCE);

// 构建需要请求的 API 示例，此处为 [[[获取房间信息|https://webstatic.mihoyo.com/vila/bot/doc/room_api/get_room.html]]] API
// 假设房间ID是 1234
var api = GetRoomApi.create(Long.parseUnsignedLong("1234"));
// Java 中操作无符号数字比较麻烦，因此面向Java的大部分相关操作也会提供基于字符串操作的重载、扩展API
var api = GetRoomApi.create("1234");

// 发起请求并得到结果。在 API 模块中有三种请求方式（均使用 `APIRequests` 的静态方法）：
// 1️⃣ 使用 api.request, 得到 Ktor 进行 HTTP 请求的原始响应类型 HttpResponse
CompletableFuture<HttpResponse> response = APIRequests.requestAsync(api, client, token);

// 2️⃣ 使用 api.requestResult, 得到请求结果的统一响应体结构。假如此响应代表成功(result.retcode == 0), 则可以通过 result.data 获取响应结果。
CompletableFuture<ApiResult<GetRoomResult>> result = APIRequests.requestResultAsync(api, client, token);

// 3️⃣ 使用 api.requestData, 得到当响应体代表成功时的响应数据。如果响应体不为成功则会抛出异常。
CompletableFuture<GetRoomResult> requestData = APIRequests.requestDataAsync(api, client, token);

异步API的响应结果都是 CompletableFuture 类型的，在处理它们的时候需要注意尽可能避免使用任何会造成阻塞的方法，例如 get 或 join。

// ↓ CompletableFuture<? extends GetRoomResult>
var requestData = APIRequests.requestDataAsync(api, client, token);
// 使用 CompletableFuture 的 thenAccept 或诸如此类的流程化API来接收、处理你的结果
requestData.thenAccept(result -> System.out.println("Result: " + result));

当然，你也可以选择配合使用一些与 CompletableFuture 兼容的其他异步/响应式框架，例如 reactor。

同样的，异步结果的异常也需要特别处理，否则你可能会在不经意间错过它：

// ↓ CompletableFuture<? extends GetRoomResult>
var requestData = APIRequests.requestDataAsync(api, client, token);
requestData.exceptionally(ex -> {
    // 生产环境里应该使用更好的处理方法或可靠的日志输出
    ex.printStackTrace();
    return null;
})
.thenAccept(...);

Last modified: 05 January 2024