理解 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。
其原理如下：
- 定义徽章映射： 创建一个映射表，将每个徽章的数值（2的幂次方）与其对应的文本名称关联起来。
- 遍历徽章映射： 逐一检查每个可能的徽章值。
- 执行位与操作： 对于每个徽章的数值（例如$key），将其与用户的public_flags值（例如$flags）进行位与操作：($key & $flags)。
-
判断结果：
- 如果($key & $flags)的结果大于0，这意味着public_flags中包含$key所代表的徽章的位，因此用户拥有该徽章。
- 如果结果为0，则用户不拥有该徽章。
Discord public_flags 徽章映射表
以下是Discord API中常见的public_flags值及其对应的徽章名称：
| 标志值 | 徽章名称 |
|---|---|
| 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 |
PHP 实现示例
假设我们从Discord API获取到的public_flags值为 644。根据问题描述，这个值代表用户拥有 HypeSquad Event、Brilliance 和 Early_Supporter 徽章。我们将使用PHP来验证这一点。
'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
// )
?>代码解析
- $badges 数组： 这个数组是所有已知Discord徽章及其对应数值的映射表。它是解码过程的基础。
- $publicFlags 变量： 存储从Discord API获取到的用户的public_flags整数值。
-
decodeDiscordPublicFlags 函数：
- 它接收$badges映射表和$publicFlags作为参数。
- 核心是array_filter()函数。array_filter()用于遍历数组并根据回调函数的返回值过滤元素。
- 回调函数 function($value, $key) use($publicFlags)：
- $value 是当前徽章的名称（例如'HypeSquad_Events'）。
- $key 是当前徽章的数值（例如4）。
- use($publicFlags) 允许回调函数访问外部的$publicFlags变量。
- ($key & $publicFlags) > 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，也广泛应用于其他需要用一个整数表示多个布尔状态的场景，是开发者工具箱中一个强大而实用的技能。
