Discord API public_flags 位掩码解码教程

理解 Discord public_flags

discord api在用户对象中提供了一个名为public_flags的字段，它是一个整数值。这个整数实际上是一个位掩码（bitmask），用于紧凑地表示用户所拥有的一系列公共徽章。每个徽章都对应一个唯一的2的幂次方值（例如1, 2, 4, 8, 64等）。当一个用户拥有多个徽章时，public_flags的值就是这些徽章对应数值的总和。例如，如果一个用户拥有hypesquad events（值4）和early supporter（值512）徽章，那么他的public_flags将是 4 + 512 = 516。

为了从这个复合值中提取出单个的徽章信息，我们需要利用位运算。

位运算解码原理

解码public_flags的核心在于位与（Bitwise AND, &）操作。位与操作会比较两个数的二进制表示，如果两个对应位都是1，则结果位为1；否则为0。

其原理如下：

1. 定义徽章映射： 创建一个映射表，将每个徽章的数值（2的幂次方）与其对应的文本名称关联起来。
2. 遍历徽章映射： 逐一检查每个可能的徽章值。
3. 执行位与操作： 对于每个徽章的数值（例如$key），将其与用户的public_flags值（例如$flags）进行位与操作：($key & $flags)。
4. 判断结果：
   • 如果($key & $flags)的结果大于0，这意味着public_flags中包含$key所代表的徽章的位，因此用户拥有该徽章。
   • 如果结果为0，则用户不拥有该徽章。

Discord public_flags 徽章映射表

以下是Discord API中常见的public_flags值及其对应的徽章名称：

文心快码

文心快码（Comate）是百度推出的一款AI辅助编程工具

35

查看详情

PHP 实现示例

假设我们从Discord API获取到的public_flags值为 644。根据问题描述，这个值代表用户拥有 HypeSquad Event、Brilliance 和 Early_Supporter 徽章。我们将使用PHP来验证这一点。

<?php

/**
 * 定义Discord public_flags的徽章映射表。
 * 键是徽章的数值，值是徽章的名称。
 */
$badges = [
    1      => 'Discord_Employee',
    2      => 'Partnered_Server_Owner',
    4      => 'HypeSquad_Events',
    8      => 'Bug_Hunter_Level_1',
    64     => 'House_Bravery',
    128    => 'House_Brilliance',
    256    => 'House_Balance',
    512    => 'Early_Supporter',
    16384  => 'Bug_Hunter_Level_2',
    131072 => 'Early_Verified_Bot_Developer',
];

// 示例用户的 public_flags 值
$publicFlags = 644;

/**
 * 使用 array_filter 结合位与操作来筛选出用户拥有的徽章。
 *
 * @param array    $badges      所有可能的徽章映射数组。
 * @param int      $publicFlags 用户当前的 public_flags 值。
 * @return array 包含用户所拥有徽章名称的数组。
 */
function decodeDiscordPublicFlags(array $badges, int $publicFlags): array
{
    // array_filter 的回调函数会遍历 $badges 数组的每个元素。
    // $key 是徽章的数值 (1, 2, 4, ...)，$value 是徽章的名称。
    // ARRAY_FILTER_USE_BOTH 确保回调函数能同时接收键和值。
    return array_filter($badges, function($value, $key) use($publicFlags) {
        // 执行位与操作：如果 publicFlags 包含当前徽章的位，结果会大于0。
        return ($key & $publicFlags) > 0;
    }, ARRAY_FILTER_USE_BOTH);
}

// 调用函数解码 public_flags
$userBadges = decodeDiscordPublicFlags($badges, $publicFlags);

// 输出结果
echo "用户 public_flags: {$publicFlags}\n";
echo "用户拥有的徽章:\n";
print_r($userBadges);

// 预期输出:
// 用户 public_flags: 644
// 用户拥有的徽章:
// Array
// (
//     [4] => HypeSquad_Events
//     [128] => House_Brilliance
//     [512] => Early_Supporter
// )

// 另一个示例：public_flags = 6
// $publicFlags = 6;
// $userBadges = decodeDiscordPublicFlags($badges, $publicFlags);
// echo "\n用户 public_flags: {$publicFlags}\n";
// echo "用户拥有的徽章:\n";
// print_r($userBadges);
// 预期输出:
// 用户 public_flags: 6
// 用户拥有的徽章:
// Array
// (
//     [2] => Partnered_Server_Owner
//     [4] => HypeSquad_Events
// )

?>

代码解析

1. $badges 数组： 这个数组是所有已知Discord徽章及其对应数值的映射表。它是解码过程的基础。
2. $publicFlags 变量： 存储从Discord API获取到的用户的public_flags整数值。
3. decodeDiscordPublicFlags 函数：
   • 它接收$badges映射表和$publicFlags作为参数。
   • 核心是array_filter()函数。array_filter()用于遍历数组并根据回调函数的返回值过滤元素。
   • 回调函数 function($value, $key) use($publicFlags)：
     • $value 是当前徽章的名称（例如'HypeSquad_Events'）。
     • $key 是当前徽章的数值（例如4）。
     • use($publicFlags) 允许回调函数访问外部的$publicFlags变量。
     • ($key & $publicFlags) youjiankuohaophpcn 0 是位运算的关键。它检查$publicFlags是否“包含”$key所代表的位。如果包含，位与结果将是一个非零值（通常就是$key本身），因此表达式为真。
   • ARRAY_FILTER_USE_BOTH 参数确保回调函数能同时接收到数组的键（即徽章数值）和值（即徽章名称）。
   • array_filter最终返回一个新数组，其中只包含用户实际拥有的徽章。

注意事项

• 徽章列表的完整性： Discord API可能会更新或添加新的public_flags。为了确保解码的准确性，应定期检查Discord API文档，更新$badges映射表。
• 跨语言通用性： 位运算是编程语言中的通用概念。无论使用PHP、Python、JavaScript、Java或其他语言，都可以采用类似的位与逻辑来解码位掩码。只需根据相应语言的语法实现array_filter（或其等效功能）和位与操作即可。
• 错误处理： 在实际应用中，建议对从API获取的public_flags值进行类型验证，确保它是一个有效的整数。
• 性能： 位运算是一种非常高效的操作，因此这种解码方法在性能方面表现优秀，即使处理大量用户数据也不会成为瓶颈。

总结

通过理解public_flags的位掩码机制和巧妙运用位与操作，我们可以轻松地将Discord API返回的单一整数值转换为用户所拥有的详细徽章列表。这种技术不仅适用于Discord API，也广泛应用于其他需要用一个整数表示多个布尔状态的场景，是开发者工具箱中一个强大而实用的技能。

以上就是Discord API public_flags 位掩码解码教程的详细内容，更多请关注php中文网其它相关文章！