使用Discord JDA创建Discord服务器角色时卡住无报错如何解决

核心诱因 #

• 代码卡住无报错的核心原因是submit().get()和complete()均为阻塞调用，如果JDA内部请求队列被阻塞、机器人账号缺少对应服务器的MANAGE_ROLES权限、JDA网关连接状态异常，都会导致阻塞调用无限挂起，不会主动抛出异常。
• 原代码多次调用getManager()会生成多个独立修改请求，不仅浪费请求配额，也会提升触发速率限制的概率。

修复代码方案 #

优先使用非阻塞queue()方法 #

在回调中处理创建结果，同时添加失败回调捕获错误信息：

Guild g = bot.getGuildById(816744384925663275L);
if (g == null) {
    System.out.println("指定服务器不存在或机器人尚未加入该服务器");
    return;
}
// 预先校验机器人权限
if (!g.getSelfMember().hasPermission(Permission.MANAGE_ROLES)) {
    System.out.println("机器人缺少管理角色权限，无法创建角色");
    return;
}
// 一次性配置所有属性，发起非阻塞请求
g.createRole()
    .setName("Owner")
    .setColor(Color.RED)
    .setHoisted(true)
    .setMentionable(false)
    .setPermissions(Permission.ADMINISTRATOR)
    .queue(
        role -> System.out.println("角色创建成功，ID：" + role.getId()),
        error -> {
            System.err.println("角色创建失败：" + error.getMessage());
            error.printStackTrace();
        }
    );

必须使用阻塞调用时添加超时限制 #

避免线程无限挂起：

try {
    Role rle = g.createRole()
        .setName("Owner")
        .setColor(Color.RED)
        .setHoisted(true)
        .setMentionable(false)
        .setPermissions(Permission.ADMINISTRATOR)
        .submit()
        .get(5, TimeUnit.SECONDS); // 最多等待5秒，超时抛出TimeoutException
} catch (InterruptedException | ExecutionException | TimeoutException e) {
    e.printStackTrace();
}

排查验证要点 #

• 确认机器人在目标服务器已开启MANAGE_ROLES权限，且机器人自身的角色层级高于要创建的角色层级
• 确认JDA初始化时已注册GUILD_ROLES网关意图，JDA 4.x及以上版本需要手动开启该意图才能正常操作角色
• 确认目标服务器的角色数量未达到Discord上限（单服务器最多250个角色）

内容的提问来源于stack exchange，提问作者Joa