水缸机器人

Appearance

群成员与黑名单 ​

概述 ​

Bngeuit 提供群成员查询、批量移除与群黑名单管理能力：

  • 成员列表：分页拉取群内全部成员
  • 成员详情：查询单个成员的入群时间、角色、是否机器人
  • 批量移除：一次踢出多名成员，可同时拉黑
  • 黑名单：查询、加入、移出群黑名单

内邀接口

以上接口属于官方内邀白名单接口，需要向平台申请开通。未获授权时调用会返回错误码 11253（应用无接口访问权限），属预期行为而非框架问题。

快速上手 ​

查询成员列表 ​

java
import cn.org.bukkit.bngeuit.Bngeuit;
import cn.org.bukkit.bngeuit.dto.message.member.Member;
import cn.org.bukkit.bngeuit.dto.message.member.MemberListResponse;

// 第一页
MemberListResponse page = Bngeuit.getGroupMembers(groupOpenid);

for (Member m : page.members()) {
    System.out.println(m.username() + " / " + m.memberRole() + " / bot=" + m.bot());
}

// 翻页：nextCursor() 为空串表示已到末页
String cursor = page.nextCursor();
while (cursor != null && !cursor.isEmpty()) {
    page = Bngeuit.getGroupMembers(groupOpenid, cursor);
    // 处理 page.members()...
    cursor = page.nextCursor();
}

查询成员详情 ​

java
Member m = Bngeuit.getGroupMember(groupOpenid, memberOpenid);
if (m != null) {
    System.out.println(m.username() + " 入群于 " + m.joinedAt());
}

批量移除成员 ​

java
import cn.org.bukkit.bngeuit.dto.message.member.BatchRemoveMembersResponse;

// 仅移除
Bngeuit.batchRemoveGroupMembers(groupOpenid, List.of(openid1, openid2));

// 移除并加入黑名单
BatchRemoveMembersResponse r = Bngeuit.batchRemoveGroupMembers(
    groupOpenid, List.of(openid1, openid2), true);

System.out.println(r.removeMembersResult());                        // "success"
System.out.println(r.addToMemberBlacklistFailOpenids());            // 拉黑失败的用户

管理黑名单 ​

java
import cn.org.bukkit.bngeuit.dto.message.member.BlacklistOp;
import cn.org.bukkit.bngeuit.dto.message.member.BlacklistOpResponse;
import cn.org.bukkit.bngeuit.dto.message.member.BlacklistUserListResponse;

// 查询
BlacklistUserListResponse list = Bngeuit.getGroupMemberBlacklist(groupOpenid, null, 20);
for (var u : list.users()) {
    System.out.println(u.username() + " 拉黑于 " + u.bannedAt());
}

// 加入 / 移出
Bngeuit.addMemberToBlacklist(groupOpenid, List.of(openid1));
Bngeuit.removeMemberFromBlacklist(groupOpenid, List.of(openid1));

// 或直接指定操作类型
BlacklistOpResponse r = Bngeuit.updateGroupMemberBlacklist(
    groupOpenid, BlacklistOp.ADD, List.of(openid1, openid2));
if (r.failOpenids() != null && !r.failOpenids().isEmpty()) {
    System.out.println("操作失败: " + r.failOpenids());
}

API 参考 ​

门面方法 ​

方法返回类型说明
getGroupMembers(groupOpenid)MemberListResponse成员列表第一页
getGroupMembers(groupOpenid, cursor)MemberListResponse成员列表（游标翻页）
getGroupMember(groupOpenid, memberOpenid)Member单个成员详情
batchRemoveGroupMembers(groupOpenid, memberOpenids)BatchRemoveMembersResponse批量移除（不拉黑）
batchRemoveGroupMembers(groupOpenid, memberOpenids, addToMemberBlacklist)BatchRemoveMembersResponse批量移除（可选拉黑）
getGroupMemberBlacklist(groupOpenid)BlacklistUserListResponse黑名单第一页（20 条）
getGroupMemberBlacklist(groupOpenid, cursor, limit)BlacklistUserListResponse黑名单列表（可指定单页数量）
updateGroupMemberBlacklist(groupOpenid, op, memberOpenids)BlacklistOpResponse加入 / 移出黑名单
addMemberToBlacklist(groupOpenid, memberOpenids)BlacklistOpResponse加入黑名单（便捷方法）
removeMemberFromBlacklist(groupOpenid, memberOpenids)BlacklistOpResponse移出黑名单（便捷方法）

频率限制 ​

平台对各方法有独立频率限制，超限会被拒绝，批量操作时注意节奏：

方法频率限制
getGroupMembers60 QPM
getGroupMember30 QPM
batchRemoveGroupMembers30 QPM
getGroupMemberBlacklist30 QPM
updateGroupMemberBlacklist60 QPM

限制 ​

项目限制
成员列表单页数量固定上限 30 条
批量移除 / 黑名单操作单次最多 20 个 openid
黑名单单页数量默认 20，最大 100
加入黑名单条件目标用户当前不在群内

数据结构 ​

成员相关对象位于 cn.org.bukkit.bngeuit.dto.message.member。

Member ​

字段类型说明
memberOpenid()String成员 OpenID
username()String成员昵称
memberRole()MemberRole群内角色（member / admin / owner）
bot()boolean是否机器人
joinedAt()String入群时间（RFC3339）
unionOpenid()String跨应用统一 OpenID（如有）

MemberListResponse ​

字段类型说明
members()List<Member>成员列表
nextCursor()String下一页游标（空串 = 末页）

BlacklistUser ​

字段类型说明
unionOpenid()String跨应用统一 OpenID（如有）
memberOpenid()String成员 OpenID
username()String用户昵称
bannedAt()String拉黑时间（RFC3339）
bot()boolean是否机器人

BlacklistUserListResponse ​

字段类型说明
users()List<BlacklistUser>黑名单用户列表
nextCursor()String下一页游标（空串 = 末页）

BatchRemoveMembersResponse ​

字段类型说明
removeMembersResult()String移除结果，成功时为 success
addToMemberBlacklistFailOpenids()List<String>同时拉黑时失败的 openid 列表

BlacklistOpResponse ​

字段类型说明
failOpenids()List<String>操作失败的 openid 列表

BlacklistOp ​

黑名单操作类型枚举：

枚举JSON 值说明
ADD"add"加入黑名单
DEL"del"移出黑名单

事件 ​

GroupMemberBatchRemoveEvent ​

批量移除成员前触发，可取消。取消后本次移除请求不会发出，API 返回 null。

方法返回类型说明
getGroupOpenid()String群 OpenID
getMemberOpenids()List<String>待移除的成员列表
isAddToMemberBlacklist()boolean是否同时拉黑
java
@SubscribeEvent(priority = EventPriority.P1)
public void onBatchRemove(GroupMemberBatchRemoveEvent e) {
    if (e.isAddToMemberBlacklist()) {
        e.setCancelled(true);   // 禁止"移除并拉黑"的组合操作
    }
}

GroupMemberBlacklistEvent ​

群黑名单操作前触发，可取消。

方法返回类型说明
getGroupOpenid()String群 OpenID
getOp()BlacklistOp操作类型
getMemberOpenids()List<String>目标成员列表

两个事件都有配对的 GroupMemberBatchRemoveNotifyEvent / GroupMemberBlacklistNotifyEvent 后置事件， 在请求成功后触发，详见 事件类型参考。