JDA（Java Discord API）

这个开源库旨在使用实时网关和REST API在Discord上实现机器人。它提供了基于事件的功能来实现各种类型的机器人，允许创建高效且可扩展的应用程序。

📖 概述

JDA的核心概念经过精心设计，使构建可扩展应用变得简单：

事件系统提供来自网关API的简化事件，无需太多麻烦即可实时响应任何平台事件。
REST操作易于使用且可扩展的REST API功能实现，让你可以在回调、组合器、futures和阻塞方式之间进行选择。该库还自动处理Discord施加的速率限制，同时仍提供替换默认实现的方法。
可定制的缓存在必要时权衡内存使用和性能，提供合理的默认预设供选择和自定义。

你可以通过访问我们的wiki或参考我们的Javadocs了解更多信息。

🔬 安装

该库可在Maven Central上获得。最新版本始终显示在GitHub Release中。

JDA支持的最低Java版本是Java SE 8。JDA还使用JSR 305以支持与Kotlin的良好互操作性。

Gradle

repositories {
    mavenCentral()
}

dependencies {
    implementation("net.dv8tion:JDA:$version") { // 将$version替换为最新版本
      // 可选择禁用音频原生库以通过排除`opus-java`来减小jar包大小
      // Gradle DSL:
      // exclude module: 'opus-java'
      // Kotlin DSL:
      // exclude(module="opus-java")
    }
}

Maven

<dependency>
    <groupId>net.dv8tion</groupId>
    <artifactId>JDA</artifactId>
    <version>$version</version> <!-- 将$version替换为最新版本 -->
    <!-- 可选择禁用音频原生库以通过排除`opus-java`来减小jar包大小
    <exclusions>
        <exclusion>
            <groupId>club.minnced</groupId>
            <artifactId>opus-java</artifactId>
        </exclusion>
    </exclusions>
    -->
</dependency>

🤖 创建机器人

要使用这个库，你需要在Discord应用程序面板中创建一个应用程序并获取你的机器人令牌。你可以在我们的wiki页面创建Discord机器人中找到详细的分步指南。

🏃‍♂️ 入门

我们提供了一些示例来帮助你熟悉JDA。你还可以查看我们的官方Wiki、文档和FAQ。

每个由JDA实现的机器人都从使用JDABuilder或DefaultShardManagerBuilder开始。这两个构建器都提供了一组默认预设，用于缓存使用和它想要接收的事件：

createDefault - 为在语音频道中活跃的用户启用缓存，并启用所有缓存标志
createLight - 禁用所有用户缓存和缓存标志
create - 启用成员分块，缓存所有用户，并启用所有缓存标志我们建议阅读缓存和意图指南，以了解如何正确配置您的机器人。以下是一些可能的使用场景：

示例：消息日志记录

[!注意] 以下示例使用了特权意图GatewayIntent.MESSAGE_CONTENT，需要在您的应用程序仪表板中明确启用。您可以在我们的wiki指南中了解更多关于意图的信息。

简单地将消息记录到控制台。使用JDABuilder，这是小型机器人的预期入口点，不打算扩展到数千个公会。

启动您的机器人并附加一个事件监听器，使用正确的意图：

public static void main(String[] args) {
  JDABuilder.createLight(token, EnumSet.of(GatewayIntent.GUILD_MESSAGES, GatewayIntent.MESSAGE_CONTENT))
      .addEventListener(new MessageReceiveListener())
      .build();
}

您的事件监听器可能如下所示：

public class MessageReceiveListener extends ListenerAdapter {
  @Override
  public void onMessageReceived(MessageReceivedEvent event) {
    System.out.printf("[%s] %#s: %s\n",
      event.getChannel(),
      event.getAuthor(),
      event.getMessage().getContentDisplay());
  }
}

您可以在MessageLoggerExample类中找到更详细的示例。

示例：斜杠命令机器人

这是一个使用交互来响应用户命令的机器人。与消息日志记录机器人不同，这个机器人可以在没有启用任何意图的情况下工作，因为交互始终可用。

public static void main(String[] args) {
  JDA jda = JDABuilder.createLight(token, Collections.emptyList())
      .addEventListener(new SlashCommandListener())
      .build();

  // 注册您的命令，使其在Discord上全局可见：

  CommandListUpdateAction commands = jda.updateCommands();

  // 在此操作实例上添加所有命令
  commands.addCommands(
    Commands.slash("say", "让机器人说出你告诉它的内容")
      .addOption(STRING, "content", "机器人应该说什么", true), // 接受用户输入
    Commands.slash("leave", "让机器人离开服务器")
      .setGuildOnly(true) // 这在私信中没有意义
      .setDefaultPermissions(DefaultMemberPermissions.DISABLED) // 只有管理员应该能够使用此命令
  );

  // 最后使用API将您的命令发送到Discord
  commands.queue();
}

响应命令的事件监听器可能如下所示：

public class SlashCommandListener extends ListenerAdapter {
  @Override
  public void onSlashCommandInteraction(SlashCommandInteractionEvent event) {
    switch (event.getName()) {
      case "say" -> {
        String content = event.getOption("content", OptionMapping::getAsString);
        event.reply(content).queue();
      };
      case "leave" -> {
        event.reply("我现在要离开服务器了！")
          .setEphemeral(true) // 此消息仅对命令用户可见
          .flatMap(m -> event.getGuild().leave()) // 使用flatMap附加后续操作
          .queue(); // 将两个操作排队按顺序执行（发送消息 -> 离开公会）
      };
      default -> return;
    }
  }
}

您可以在SlashBotExample类中找到更详细的示例。

🚀 RestAction

在这个库中，RestAction接口用作所有API端点的请求构建器。该接口表示一个懒加载的请求构建器，如下简单示例所示：

channel.sendMessage("你好朋友！")
  .addFiles(FileUpload.fromData(greetImage)) // 链式调用构建器方法来配置请求
  .queue() // 异步发送请求

[!重要] 最后调用queue()发送请求。您也可以同步发送请求或使用futures，查看我们在RestAction Wiki中的扩展指南。

RestAction接口还支持许多操作符，以避免回调地狱：

map
将RestAction的结果转换为不同的值
flatMap
在结果上链接另一个RestAction
delay
延迟前一步的元素

以及组合器如：

and
要求另一个RestAction成功完成，并行运行
allOf
将多个操作累积成一个列表（另见mapToResult）
zip
类似于and，但将结果组合成一个列表

以及配置器如：

timeout和deadline
配置操作允许在队列中等待的时间，如果等待时间过长则取消
setCheck
在发送请求之前进行一些检查，当请求在队列中等待较长时间时这很有用
reason
操作的审核日志原因

示例:

public RestAction<Void> selfDestruct(MessageChannel channel, String content) {
    return channel.sendMessage("以下消息将在1分钟后自毁!")
        .addActionRow(Button.danger("delete", "立即删除")) // 在发送前进一步修改消息
        .delay(10, SECONDS, scheduler) // 发送后等待10秒
        .flatMap((it) -> it.editMessage(content)) // 然后编辑消息
        .delay(1, MINUTES, scheduler) // 再等待1分钟
        .flatMap(Message::delete); // 然后删除
}

然后可以在代码中这样使用:

selfDestruct(channel, "你好朋友，这是我的秘密消息").queue();

🧩 扩展

由sedmelluq创建，现在由lavalink社区维护
Lavaplayer是Java创建的音乐机器人中最受欢迎的库。它与JDA和Discord4J高度兼容，允许播放来自YouTube、Soundcloud、Twitch、Bandcamp和更多提供商的音频。
通过实现自己的AudioSourceManager并注册它，可以轻松扩展该库以支持更多服务。我们建议除了lavaplayer之外还使用udpqueue，以避免由GC暂停引起的卡顿问题。

建议阅读Lavaplayer的使用部分，以了解正确的实现方法。
Sedmelluq在他的存储库中提供了一个演示，展示了JDA的示例实现： https://github.com/lavalink-devs/lavaplayer/tree/master/demo-jda

udpqueue (jda-nas的扩展)

由sedmelluq创建和维护，由MinnDevelopment扩展
为JDA音频发送系统提供原生实现，以避免GC暂停可能导致的持续音频播放问题。

请注意，此发送系统会创建一个额外的UDP客户端，这会导致音频接收无法正常工作，因为Discord将发送UDP客户端识别为接收者。

JDABuilder builder = JDABuilder.createDefault(BOT_TOKEN)
    .setAudioSendFactory(new NativeAudioSendFactory());

Lavalink

由Freya Arbjerg创建，现在由lavalink社区维护。

Lavalink是一个流行的基于Lavaplayer的独立音频发送节点。Lavalink在设计时考虑了可扩展性，并允许通过多个服务器流式传输音乐。它支持Lavaplayer的大部分功能。

Lavalink被许多大型机器人使用，也被那些无法使用Java库如Lavaplayer的机器人开发者使用。如果你计划使用JDA在较小规模上提供音乐服务，通常直接使用Lavaplayer更为简单。

Lavalink-Client是JDA的官方Lavalink客户端。

🛠️ 为JDA贡献

如果你想为JDA做出贡献，请确保你的分支是基于我们的master分支（或功能分支）创建的，并将你的PR创建到同一个分支中。

请遵循我们的贡献指南。

不要期望你的拉取请求能立即得到关注，有时可能需要很长时间才能得到回应。你可以加入我们的discord服务器，并在#lib-dev中询问，然后再开始新的PR工作，以从我们的社区成员那里获得更直接的反馈。

🚨 重大变更

由于Discord API的特性，该库将定期引入重大变更，以便快速采用新功能。我们尽量保持这些重大变更最小化，但无法完全避免。大多数破坏性变更将导致次要版本号的增加（5.1.2 → 5.2.0）。

JDA