用户与成员模型 API 参考

该模块为 QQ 频道机器人 API 中的用户信息、频道成员和相关实体提供数据结构。

核心类型

User

表示系统中的 QQ 用户。

pub struct User {
    pub id: String,
    pub username: Option<String>,
    pub avatar: Option<String>,
    pub bot: Option<bool>,
    pub union_openid: Option<String>,
    pub union_user_account: Option<String>,
}

字段

• id: 唯一用户标识符
• username: 用户的显示名称
• avatar: 头像图片 URL
• bot: 该用户是否为机器人账户
• union_openid: 用户的跨平台标识符
• union_user_account: 联合账户标识符

示例

async fn handle_user_info(user: User) {
    println!("用户: {}", user.username.as_deref().unwrap_or("未知"));
    
    if user.bot.unwrap_or(false) {
        println!("这是一个机器人账户");
    }
    
    if let Some(avatar) = &user.avatar {
        println!("头像 URL: {}", avatar);
    }
}

Member

表示频道成员，包含用户信息以及频道特定数据。

pub struct Member {
    pub user: Option<User>,
    pub nick: Option<String>,
    pub roles: Vec<String>,
    pub joined_at: Option<String>,
    pub deaf: Option<bool>,
    pub mute: Option<bool>,
}

字段

• user: 该成员的用户信息
• nick: 成员在频道中的昵称
• roles: 分配给成员的身份组 ID 列表
• joined_at: 成员加入频道的时间戳
• deaf: 成员在语音子频道中是否被拒听
• mute: 成员在语音子频道中是否被静音

方法

display_name

获取成员的显示名称（昵称或用户名）。

pub fn display_name(&self) -> &str

返回值： 成员的昵称（如果有），否则返回用户名，如果都没有则返回 "未知"。

示例：

let display_name = member.display_name();
println!("成员显示名称: {}", display_name);

is_bot

检查成员是否为机器人。

pub fn is_bot(&self) -> bool

示例：

if member.is_bot() {
    println!("这个成员是机器人");
}

has_role

检查成员是否拥有特定身份组。

pub fn has_role(&self, role_id: &str) -> bool

参数：

• role_id: 要检查的身份组 ID

示例：

if member.has_role("admin_role_id") {
    println!("成员拥有管理员身份组");
}

MessageUser

消息中的用户信息的简化版本。

pub struct MessageUser {
    pub id: String,
    pub username: Option<String>,
    pub bot: Option<bool>,
    pub avatar: Option<String>,
}

字段

• id: 用户唯一标识符
• username: 用户显示名称
• bot: 是否为机器人账户
• avatar: 头像 URL

方法

from_data

从 JSON 数据创建 MessageUser 实例。

pub fn from_data(data: serde_json::Value) -> Self

示例：

let user = MessageUser::from_data(json_data);

MessageMember

消息中的成员信息。

pub struct MessageMember {
    pub nick: Option<String>,
    pub roles: Option<Vec<String>>,
    pub joined_at: Option<chrono::DateTime<chrono::Utc>>,
}

字段

• nick: 成员昵称
• roles: 身份组列表
• joined_at: 加入时间

群聊和 C2C 用户类型

GroupMessageUser

群消息中的用户信息。

pub struct GroupMessageUser {
    pub id: Option<String>,
    pub member_openid: Option<String>,
    pub union_openid: Option<String>,
}

字段

• id: 用户 ID（可选）
• member_openid: 成员 OpenID
• union_openid: 联合 OpenID

C2CMessageUser

C2C 消息中的用户信息。

pub struct C2CMessageUser {
    pub user_openid: Option<String>,
}

字段

• user_openid: 用户 OpenID

DirectMessageUser

私信中的用户信息。

pub struct DirectMessageUser {
    pub id: String,
    pub username: Option<String>,
    pub avatar: Option<String>,
}

字段

• id: 用户 ID
• username: 用户名
• avatar: 头像 URL

DirectMessageMember

私信中的成员信息。

pub struct DirectMessageMember {
    pub nick: Option<String>,
    pub roles: Option<Vec<String>>,
    pub joined_at: Option<chrono::DateTime<chrono::Utc>>,
}

用户管理操作

获取用户信息

async fn get_user_details(ctx: Context, user_id: &str) -> Result<()> {
    // 获取用户基本信息
    let user = ctx.get_current_user().await?;
    println!("当前用户: {}", user.username.as_deref().unwrap_or("未知"));
    
    // 在特定频道中获取用户信息
    let guild_id = "guild_id_here";
    let member = ctx.get_guild_member(guild_id, user_id).await?;
    
    if let Some(user) = &member.user {
        println!("频道成员: {}", user.username.as_deref().unwrap_or("未知"));
        
        if let Some(nick) = &member.nick {
            println!("昵称: {}", nick);
        }
        
        println!("身份组: {:?}", member.roles);
    }
    
    Ok(())
}

成员管理

async fn manage_member(ctx: Context, guild_id: &str, user_id: &str) -> Result<()> {
    // 获取成员信息
    let member = ctx.get_guild_member(guild_id, user_id).await?;
    println!("成员显示名称: {}", member.display_name());
    
    // 检查成员权限
    if member.has_role("moderator_role_id") {
        println!("成员拥有版主权限");
    }
    
    // 为成员添加身份组
    let role_id = "new_role_id";
    ctx.add_guild_role_member(guild_id, role_id, user_id, None).await?;
    println!("已为成员添加身份组");
    
    // 从成员移除身份组
    ctx.remove_guild_role_member(guild_id, role_id, user_id, None).await?;
    println!("已从成员移除身份组");
    
    Ok(())
}

批量用户操作

async fn bulk_user_operations(ctx: Context, guild_id: &str) -> Result<()> {
    // 获取所有成员
    let members = ctx.get_guild_members(guild_id, Some(1000), None).await?;
    
    let mut bot_count = 0;
    let mut human_count = 0;
    let mut admin_count = 0;
    
    for member in &members {
        if member.is_bot() {
            bot_count += 1;
        } else {
            human_count += 1;
        }
        
        if member.has_role("admin_role_id") {
            admin_count += 1;
        }
    }
    
    println!("频道统计:");
    println!("  机器人: {}", bot_count);
    println!("  人类用户: {}", human_count);
    println!("  管理员: {}", admin_count);
    println!("  总成员: {}", members.len());
    
    // 找到最近加入的成员
    let mut recent_members: Vec<_> = members.iter()
        .filter(|m| m.joined_at.is_some())
        .collect();
    
    recent_members.sort_by(|a, b| {
        b.joined_at.as_ref().unwrap().cmp(a.joined_at.as_ref().unwrap())
    });
    
    println!("最近加入的 5 个成员:");
    for member in recent_members.iter().take(5) {
        println!("  - {}", member.display_name());
        if let Some(joined) = &member.joined_at {
            println!("    加入时间: {}", joined.format("%Y-%m-%d %H:%M:%S"));
        }
    }
    
    Ok(())
}

用户权限检查

async fn check_user_permissions(ctx: Context, guild_id: &str, user_id: &str) -> Result<()> {
    let member = ctx.get_guild_member(guild_id, user_id).await?;
    
    // 检查特定身份组
    let admin_roles = ["admin", "moderator", "owner"];
    let is_admin = admin_roles.iter().any(|role| member.has_role(role));
    
    if is_admin {
        println!("用户 {} 拥有管理权限", member.display_name());
    } else {
        println!("用户 {} 是普通成员", member.display_name());
    }
    
    // 检查用户状态
    if member.deaf.unwrap_or(false) {
        println!("用户在语音中被拒听");
    }
    
    if member.mute.unwrap_or(false) {
        println!("用户在语音中被静音");
    }
    
    // 获取用户在特定子频道的权限
    let channel_id = "channel_id_here";
    let permissions = ctx.get_channel_user_permissions(channel_id, user_id).await?;
    println!("用户在子频道中的权限: {}", permissions.permissions);
    
    Ok(())
}

消息中的用户处理

处理用户提及

use botrs::{Context, EventHandler, Message};

struct UserMentionHandler;

#[async_trait::async_trait]
impl EventHandler for UserMentionHandler {
    async fn message_create(&self, ctx: Context, message: Message) {
        if message.has_mentions() {
            println!("消息包含 {} 个用户提及", message.mentions.len());
            
            for mentioned_user in &message.mentions {
                println!("提及用户: {}", 
                    mentioned_user.username.as_deref().unwrap_or("未知"));
                
                if mentioned_user.bot.unwrap_or(false) {
                    println!("  这是一个机器人");
                }
            }
            
            // 回复提及消息
            let response = format!(
                "检测到 {} 个用户提及", 
                message.mentions.len()
            );
            
            if let Err(e) = message.reply(&ctx.api, &ctx.token, &response).await {
                eprintln!("回复失败: {}", e);
            }
        }
    }
}

用户信息展示

async fn display_user_card(ctx: Context, user: User, member: Option<Member>) -> String {
    let mut card = format!("用户信息卡片\n");
    card.push_str(&format!("ID: {}\n", user.id));
    card.push_str(&format!("用户名: {}\n", 
        user.username.as_deref().unwrap_or("未设置")));
    
    if user.bot.unwrap_or(false) {
        card.push_str("类型: 机器人\n");
    } else {
        card.push_str("类型: 用户\n");
    }
    
    if let Some(avatar) = &user.avatar {
        card.push_str(&format!("头像: {}\n", avatar));
    }
    
    if let Some(member) = member {
        if let Some(nick) = &member.nick {
            card.push_str(&format!("昵称: {}\n", nick));
        }
        
        if !member.roles.is_empty() {
            card.push_str(&format!("身份组数量: {}\n", member.roles.len()));
        }
        
        if let Some(joined) = &member.joined_at {
            card.push_str(&format!("加入时间: {}\n", 
                joined.format("%Y-%m-%d %H:%M:%S")));
        }
    }
    
    card
}

常见使用模式

用户验证

async fn verify_user_access(ctx: Context, guild_id: &str, user_id: &str, required_role: &str) -> Result<bool> {
    let member = ctx.get_guild_member(guild_id, user_id).await?;
    
    // 检查用户是否为机器人
    if member.is_bot() {
        return Ok(false);
    }
    
    // 检查用户是否拥有所需身份组
    if !member.has_role(required_role) {
        return Ok(false);
    }
    
    // 检查用户状态
    if member.mute.unwrap_or(false) || member.deaf.unwrap_or(false) {
        return Ok(false);
    }
    
    Ok(true)
}

用户活动分析

async fn analyze_user_activity(ctx: Context, guild_id: &str) -> Result<()> {
    let members = ctx.get_guild_members(guild_id, Some(1000), None).await?;
    
    // 按加入时间分组
    let now = chrono::Utc::now();
    let mut new_members = 0;
    let mut recent_members = 0;
    let mut old_members = 0;
    
    for member in &members {
        if let Some(joined) = &member.joined_at {
            let days_ago = (now - *joined).num_days();
            
            if days_ago <= 7 {
                new_members += 1;
            } else if days_ago <= 30 {
                recent_members += 1;
            } else {
                old_members += 1;
            }
        }
    }
    
    println!("成员活动分析:");
    println!("  新成员 (7天内): {}", new_members);
    println!("  近期成员 (30天内): {}", recent_members);
    println!("  老成员 (30天以上): {}", old_members);
    
    // 身份组分布
    let mut role_distribution = std::collections::HashMap::new();
    for member in &members {
        for role_id in &member.roles {
            *role_distribution.entry(role_id.clone()).or_insert(0) += 1;
        }
    }
    
    println!("身份组分布:");
    for (role_id, count) in role_distribution {
        println!("  {}: {} 人", role_id, count);
    }
    
    Ok(())
}

相关文档

• 客户端 API - 用户和成员操作的主要客户端
• 上下文 API - API 访问的上下文对象
• 消息 - 消息中的用户信息处理
• 频道与子频道 - 频道成员管理