# OneBot

> For the complete documentation index, see [llms.txt](https://simbot.forte.love/llms.txt).

[https://github.com/simple-robot/simpler-robot/releases](https://github.com/simple-robot/simpler-robot/releases)

## See also

### 相关链接

[OneBot组件源码](https://github.com/simple-robot/simpler-robot/tree/dev/simbot-component-onebot) [Ktor首页](https://ktor.io/) [OneBot11](https://github.com/botuniverse/onebot-11)

## 概述

OneBot 组件是一个 [OneBot11协议](https://github.com/botuniverse/onebot-11) 的客户端SDK， 也是 Simple Robot 标准API下实现的组件库。

借助simbot核心库提供的能力，它支持众多高级功能和封装，比如组件协同、Spring支持等， 助你快速开发 OneBot 客户端应用！

> **Tip:**
> 序列化和网络请求相关分别基于 [Kotlin serialization](https://github.com/Kotlin/kotlinx.serialization) 和 [Ktor](https://ktor.io/)。

* 前往OneBot组件的 [源码目录](https://github.com/simple-robot/simpler-robot/tree/dev/simbot-component-onebot)

> **Tip:**
> 自 `5.0` 起，OneBot 组件在主仓库中维护，随标准库统一版本发布，模块坐标保持不变。 OneBot v11 核心模块提供 JVM、JS、`wasm-js` 和部分 Native 目标。

## 模块

### 公共模块

OneBot组件为所有协议实现的模块提供了一些共享内容的模块， 命名为 `simbot-component-onebot-common`。

此模块中会定义一些通用的类型或注解等。 对于普通开发者来讲可以不用过多关注，此模块由其他组件模块引用并使用。

### OneBot11

在OneBot组件中，我们提供了针对 [OneBot11](https://github.com/botuniverse/onebot-11) 协议的组件实现模块，它们的坐标以 `simbot-component-onebot-v11` 作为开头：

* simbot-component-onebot-v11-common 在OneBot11协议的实现模块中进行共享的模块。 对于普通开发者来讲可以不用过多关注，此模块由其他组件模块引用并使用。

* simbot-component-onebot-v11-core OneBot11协议作为一个simbot组件的实现模块。通常会是你真正使用的模块。 当前组件标识为 `simbot.onebot11`。

* simbot-component-onebot-v11-event 对OneBot11协议中的[原始事件](https://github.com/botuniverse/onebot-11/tree/master/event) 类型提供定义的模块， 被 `simbot-component-onebot-v11-core` 引用并依赖。 > **Tip:** > 需要注意的是这里的事件并不是simbot中的事件，而仅仅是一种数据类实现， 是对原始事件的JSON结构的基本映射。

* simbot-component-onebot-v11-message 对OneBot11协议中的[原始消息段](https://github.com/botuniverse/onebot-11/blob/master/message/segment.md) 类型提供定义的模块。 这里定义的大部分类型都是针对消息段的数据类实现， 是对它们的JSON结构的基本映射， 被 `simbot-component-onebot-v11-core` 引用并依赖。

> **Tip:**
> 对于普通应用开发者来说，通常直接依赖 `simbot-component-onebot-v11-core` 即可。 其余模块更多用于协议模型、底层封装或扩展实现。

## 安装

### 安装OneBot11组件

Procedure: 前期准备

* 准备OneBot11协议服务端

OneBot组件是一个 OneBot 协议的客户端实现， 因此在使用之前，你需要准备一个支持 OneBot11 的服务端， 例如 `NapCat`, `Language.OneBot` 等。

> **Warning:**
> 鉴于 OneBot 生态的特殊性， 此处不对具体服务端实现作更多展开说明。 你只需要确保它：
>
>
>
> * 支持 OneBot11
>
> * 提供 HTTP API
>
> * 如需事件订阅，则提供正向 WebSocket

Procedure: 安装依赖

1. 安装simbot核心库实现

> **Note:**
> 在安装组件库之前，确保你已经安装了可用的核心库实现，比如 [核心库](start-use-core.html) 或 [Spring Boot starter](spring-boot.html) 。

核心库:

Gradle(Kotlin DSL):

```KOTLIN
implementation("love.forte.simbot:simbot-core:5.0.0-Alpha2")
```

如果使用 Java 而不配合使用 Gradle 的 [Kotlin 插件](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin), 那么你需要指定依赖的后缀为 `-jvm`。

```KOTLIN
implementation("love.forte.simbot:simbot-core-jvm:5.0.0-Alpha2")
```

Gradle(Groovy):

```GROOVY
implementation 'love.forte.simbot:simbot-core:5.0.0-Alpha2'
```

如果使用 Java 而不配合使用 Gradle 的 [Kotlin 插件](https://kotlinlang.org/docs/gradle-configure-project.html#apply-the-plugin), 那么你需要指定依赖的后缀为 `-jvm`。

```GROOVY
implementation 'love.forte.simbot:simbot-core-jvm:5.0.0-Alpha2'
```

Maven:

```XML
<dependency>
    <groupId>love.forte.simbot</groupId>
    <artifactId>simbot-core-jvm</artifactId>
    <version>5.0.0-Alpha2</version>
</dependency>
```

> **Tip:**
> 前往 [核心库](start-use-core.html) 了解更多内容。

Spring Boot starter:

Spring Boot 3:

Gradle(Kotlin DSL):

```KOTLIN
implementation("love.forte.simbot:simbot-core-spring-boot-starter:5.0.0-Alpha2")
```

Gradle(Groovy):

```GROOVY
implementation 'love.forte.simbot:simbot-core-spring-boot-starter:5.0.0-Alpha2'
```

Maven:

```XML
<dependency>
    <groupId>love.forte.simbot</groupId>
    <artifactId>simbot-core-spring-boot-starter</artifactId>
    <version>5.0.0-Alpha2</version>
</dependency>
```

> **Tip:**
> 前往 [使用 Spring Boot 3](start-use-spring-boot-3.html) 或 [集成Spring Boot](spring-boot.html) 了解更多内容。

Spring Boot 2:

Gradle(Kotlin DSL):

```KOTLIN
implementation("love.forte.simbot:simbot-core-spring-boot-starter-v2:5.0.0-Alpha2")
```

Gradle(Groovy):

```GROOVY
implementation 'love.forte.simbot:simbot-core-spring-boot-starter-v2:5.0.0-Alpha2'
```

Maven:

```XML
<dependency>
    <groupId>love.forte.simbot</groupId>
    <artifactId>simbot-core-spring-boot-starter-v2</artifactId>
    <version>5.0.0-Alpha2</version>
</dependency>
```

> **Tip:**
> 前往 [使用 Spring Boot 2](start-use-spring-boot-2.html) 了解更多内容。

2. 安装 `simbot-component-onebot-v11-core` 依赖

Gradle(Kotlin DSL):

```KOTLIN
implementation("love.forte.simbot.component:simbot-component-onebot-v11-core:5.0.0-Alpha2")
```

如果使用 Java 而不配合使用 Gradle 的 `kotlin` 插件, 那么你需要指定依赖的后缀为 `-jvm`。

```KOTLIN
implementation("love.forte.simbot.component:simbot-component-onebot-v11-core-jvm:5.0.0-Alpha2")
```

Gradle(Groovy):

```GROOVY
implementation 'love.forte.simbot.component:simbot-component-onebot-v11-core:5.0.0-Alpha2'
```

如果使用 Java 而不配合使用 Gradle 的 `kotlin` 插件, 那么你需要指定依赖的后缀为 `-jvm`。

```GROOVY
implementation 'love.forte.simbot.component:simbot-component-onebot-v11-core-jvm:5.0.0-Alpha2'
```

Maven:

```XML
<dependency>
    <groupId>love.forte.simbot.component</groupId>
    <artifactId>simbot-component-onebot-v11-core-jvm</artifactId>
    <version>5.0.0-Alpha2</version>
</dependency>
```

3. 安装Ktor客户端引擎

OneBot11组件使用 [Ktor](https://ktor.io) 作为 HTTP 客户端实现， 但是默认不会依赖任何具体的引擎。

因此，你需要选择并使用一个 Ktor Client 引擎实现。

> **Warning:**
> 注意，你需要选择一个支持 WebSocket 的引擎。

你可以前往 [Ktor文档](https://ktor.io/docs/http-client-engines.html) 处选择一个对应所用平台下合适的 `Client Engine`。 这里会根据不同平台提供几个示例，你可以选择其他可用目标。

> **Tip:**
> 注意应选择使用 `v2.x` 版本的 Ktor。5.0 后的版本会更新到 Ktor 3。

JVM:

Java:

在 Java11+ 的环境下，可以选择 [Java](https://ktor.io/docs/http-client-engines.html#java) 引擎。

Gradle Kotlin DSL:

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

如果不使用Kotlin的[Gradle插件](https://kotlinlang.org/docs/gradle-configure-project.html):

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

Gradle Groovy:

```GROOVY
runtimeOnly 'io.ktor:ktor-client-java:$ktor_version'
```

如果不使用Kotlin的[Gradle插件](https://kotlinlang.org/docs/gradle-configure-project.html):

```GROOVY
runtimeOnly 'io.ktor:ktor-client-java-jvm:$ktor_version'
```

Maven:

```XML
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-java-jvm</artifactId>
    <version>${ktor_version}</version>
    <scope>runtime</scope>
</dependency>
```

OkHttp:

[OkHttp](https://ktor.io/docs/client-engines.html#okhttp) 引擎基于 OkHttp，是一个不错的库。

Gradle Kotlin DSL:

```KOTLIN
runtimeOnly("io.ktor:ktor-client-okhttp:$ktor_version")
```

如果不使用Kotlin的[Gradle插件](https://kotlinlang.org/docs/gradle-configure-project.html):

```KOTLIN
runtimeOnly("io.ktor:ktor-client-okhttp-jvm:$ktor_version")
```

Gradle Groovy:

```GROOVY
runtimeOnly 'io.ktor:ktor-client-okhttp:$ktor_version'
```

如果不使用Kotlin的[Gradle插件](https://kotlinlang.org/docs/gradle-configure-project.html):

```GROOVY
runtimeOnly 'io.ktor:ktor-client-okhttp-jvm:$ktor_version'
```

Maven:

```XML
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-okhttp-jvm</artifactId>
    <version>${ktor_version}</version>
    <scope>runtime</scope>
</dependency>
```

CIO:

[CIO](https://ktor.io/docs/http-client-engines.html#cio) 是一个比较通用的引擎。 在不知道选什么的情况下，可以考虑使用它。

Gradle Kotlin DSL:

```KOTLIN
runtimeOnly("io.ktor:ktor-client-cio:$ktor_version")
```

如果不使用Kotlin的[Gradle插件](https://kotlinlang.org/docs/gradle-configure-project.html):

```KOTLIN
runtimeOnly("io.ktor:ktor-client-cio-jvm:$ktor_version")
```

Gradle Groovy:

```GROOVY
runtimeOnly 'io.ktor:ktor-client-cio:$ktor_version'
```

如果不使用Kotlin的[Gradle插件](https://kotlinlang.org/docs/gradle-configure-project.html):

```GROOVY
runtimeOnly 'io.ktor:ktor-client-cio-jvm:$ktor_version'
```

Maven:

```XML
<dependency>
    <groupId>io.ktor</groupId>
    <artifactId>ktor-client-cio-jvm</artifactId>
    <version>${ktor_version}</version>
    <scope>runtime</scope>
</dependency>
```

> **Tip:**
> 引擎大部分情况下可以 runtime only，除非你需要显式地定制化它。

JavaScript:

JavaScript 平台下可以选择 [Js](https://ktor.io/docs/http-client-engines.html#js) 引擎。

Gradle Kotlin DSL:

```KOTLIN
implementation("io.ktor:ktor-client-js:$ktor_version")
```

Gradle Groovy:

```GROOVY
implementation 'io.ktor:ktor-client-js:$ktor_version'
```

Native:

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

Mingw:

可以选择 [WinHttp](https://ktor.io/docs/http-client-engines.html#winhttp) 引擎。

Gradle Kotlin DSL:

```KOTLIN
implementation("io.ktor:ktor-client-winhttp:$ktor_version")
```

Gradle Groovy:

```GROOVY
implementation 'io.ktor:ktor-client-winhttp:$ktor_version'
```

Linux:

Linux 下依旧可以选择 [CIO](https://ktor.io/docs/http-client-engines.html#cio) 引擎。

Gradle Kotlin DSL:

```KOTLIN
implementation("io.ktor:ktor-client-cio:$ktor_version")
```

Gradle Groovy:

```GROOVY
implementation 'io.ktor:ktor-client-cio:$ktor_version'
```

MacOS:

可以选择 [Darwin](https://ktor.io/docs/http-client-engines.html#darwin) 引擎。

Gradle Kotlin DSL:

```KOTLIN
implementation("io.ktor:ktor-client-darwin:$ktor_version")
```

Gradle Groovy:

```GROOVY
implementation 'io.ktor:ktor-client-darwin:$ktor_version'
```