详解 WordPress `get_users()` 函数源码：基于 `WP_User_Query` 的用户列表查询。 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

嘿，各位代码狂魔们，早上/下午/晚上好啊！（取决于你看到这段文字的时间，程序员的时间嘛，你懂的）。今天咱们来聊聊 WordPress 里一个相当实用，但又容易被忽视的函数：get_users()。别看它名字简单粗暴，背后可藏着不少玄机呢。

开场白：别再手动拼 SQL 了！

很多同学，尤其是从其他平台转过来的，习惯直接写 SQL 语句来获取用户列表。这样做当然没问题，但效率不高，而且容易出错。WordPress 提供了 get_users()，它封装了 WP_User_Query 类，让你不用直接操作数据库，也能轻松实现各种复杂的用户查询。相当于给你准备好了一个现成的“用户查询生成器”，你只需要告诉它你的需求，它就能帮你搞定。

get_users() 函数：初识庐山真面目

首先，我们来看看 get_users() 函数的基本用法和参数。

<?php
$users = get_users( $args );
?>

$args：这是一个数组，用来传递各种查询参数。比如，你想查询所有角色为 editor 的用户，就可以这样写：

<?php
$args = array(
    'role' => 'editor'
);
$users = get_users( $args );

if ( ! empty( $users ) ) {
    foreach ( $users as $user ) {
        echo '<p>' . esc_html( $user->display_name ) . '</p>';
    }
} else {
    echo '<p>No users found.</p>';
}
?>

是不是很简单？接下来，我们深入探讨 args 数组里可以使用的各种参数。

$args 数组：参数大全

$args 数组是 get_users() 函数的核心，它决定了你的查询条件。下面列举一些常用的参数，并配以详细的解释和示例。

参数名	类型	描述	示例
`blog_id`	int	指定博客 ID，用于多站点环境。默认值是当前博客 ID。	`'blog_id' => 2`
`role`	string	指定用户角色。	`'role' => 'editor'`
`role__in`	array	指定多个用户角色，返回拥有其中任何一个角色的用户。	`'role__in' => array( 'editor', 'author' )`
`role__not_in`	array	指定多个用户角色，返回不拥有这些角色的用户。	`'role__not_in' => array( 'subscriber', 'contributor' )`
`capability`	string	指定用户拥有的权限。	`'capability' => 'edit_posts'`
`capability__in`	array	指定用户拥有的多个权限，返回拥有其中任何一个权限的用户。	`'capability__in' => array( 'edit_posts', 'publish_posts' )`
`capability__not_in`	array	指定用户拥有的多个权限，返回不拥有这些权限的用户。	`'capability__not_in' => array( 'read', 'upload_files' )`
`include`	array	指定用户 ID 列表，只返回这些用户。	`'include' => array( 1, 2, 3 )`
`exclude`	array	指定用户 ID 列表，排除这些用户。	`'exclude' => array( 4, 5, 6 )`
`search`	string	搜索用户名、昵称、邮箱等字段。	`'search' => 'john'` (注意：需要使用通配符 `*`)
`search_columns`	array	指定搜索的字段，默认为 ‘user_login’, ‘user_email’, ‘user_url’, ‘user_nicename’, ‘display_name’。	`'search_columns' => array( 'user_login', 'user_email' )`
`orderby`	string	排序字段。可选值包括 ‘ID’, ‘login’, ‘nicename’, ’email’, ‘url’, ‘registered’, ‘display_name’, ‘post_count’ 等。	`'orderby' => 'registered'`
`order`	string	排序方式。可选值 ‘ASC’ (升序) 和 ‘DESC’ (降序)。	`'order' => 'DESC'`
`number`	int	返回的用户数量。	`'number' => 10`
`offset`	int	偏移量，用于分页。	`'offset' => 20`
`paged`	int	分页参数，用于分页。与 `number` 配合使用。	`'paged' => 2, 'number' => 10` (返回第 2 页，每页 10 个用户)
`has_published_posts`	array/bool	是否有已发布的文章。如果为数组，则指定文章类型。	`'has_published_posts' => true` 或 `'has_published_posts' => array('post','page')`
`fields`	string	返回的数据字段。可选值：’ID’, ‘user_login’, ‘user_pass’, ‘user_nicename’, ‘user_email’, ‘user_url’, ‘user_registered’, ‘display_name’, ‘spam’, ‘deleted’，或者 ‘all’ (默认)。也可以是 ‘count’，只返回用户数量。	`'fields' => 'ID'` (只返回用户 ID) 或 `'fields' => 'count'` (只返回用户数量)
`meta_key`	string	用户元数据的键名。	`'meta_key' => 'your_meta_key'`
`meta_value`	string	用户元数据的值。	`'meta_value' => 'your_meta_value'`
`meta_compare`	string	用户元数据比较操作符。可选值：’=’, ‘!=’, ‘>’, ‘>=’, ‘<‘, ‘<=’, ‘LIKE’, ‘NOT LIKE’, ‘IN’, ‘NOT IN’, ‘BETWEEN’, ‘NOT BETWEEN’, ‘EXISTS’, ‘NOT EXISTS’。	`'meta_compare' => 'LIKE'`
`meta_query`	array	更复杂的元数据查询。	见下文详解

meta_query：元数据查询的高级用法

meta_query 允许你构建更复杂的元数据查询，例如，查询所有年龄大于 30 岁，并且城市是北京的用户。

<?php
$args = array(
    'meta_query' => array(
        'relation' => 'AND', // 多个条件之间的关系，可选 'AND' 或 'OR'
        array(
            'key'     => 'age',
            'value'   => 30,
            'compare' => '>',
            'type'    => 'NUMERIC' // 指定数据类型，可选 'NUMERIC', 'CHAR', 'DATE', 'DATETIME', 'BINARY', 'SIGNED', 'UNSIGNED'
        ),
        array(
            'key'     => 'city',
            'value'   => '北京',
            'compare' => '='
        )
    )
);

$users = get_users( $args );

if ( ! empty( $users ) ) {
    foreach ( $users as $user ) {
        echo '<p>' . esc_html( $user->display_name ) . '</p>';
    }
} else {
    echo '<p>No users found.</p>';
}
?>

relation：指定多个条件之间的关系，可选 'AND' (所有条件都满足) 或 'OR' (满足其中一个条件)。
key：元数据的键名。
value：元数据的值。
compare：比较操作符，可选值和 meta_compare 相同。
type：指定数据类型，可选值包括 'NUMERIC', 'CHAR', 'DATE', 'DATETIME', 'BINARY', 'SIGNED', 'UNSIGNED'。如果不指定， WordPress 会自动推断。

get_users() 的返回值

get_users() 函数根据你传递的 fields 参数，返回不同的数据：

如果 fields 为 'all' (默认值)，返回一个 WP_User 对象数组，包含了用户的全部信息。
如果 fields 为 'ID'，返回一个用户 ID 数组。
如果 fields 为 'count'，返回一个整数，表示符合条件的用户数量。
如果 fields 为其他值（例如 'user_login'），返回一个包含指定字段值的数组。

深入源码：WP_User_Query 类

get_users() 函数实际上是对 WP_User_Query 类的一个简单封装。我们来看一下 get_users() 函数的源码（位于 wp-includes/user.php）：

<?php
function get_users( $args = array() ) {
    $query = new WP_User_Query( $args );

    return $query->get_results();
}
?>

可以看到，它只是创建了一个 WP_User_Query 对象，并将 $args 传递给它，然后调用 get_results() 方法获取结果。

接下来，我们深入了解 WP_User_Query 类，看看它是如何工作的。

WP_User_Query 类：用户查询的幕后英雄

WP_User_Query 类负责构建和执行用户查询。它接收一个参数数组，根据这些参数生成 SQL 查询语句，并从数据库中获取用户数据。

我们来看一下 WP_User_Query 类的一些关键方法：

__construct( $query = null )：构造函数，接收查询参数，并初始化查询。
prepare_query()：根据查询参数，构建 SQL 查询语句。
get_sql()：返回构建好的 SQL 查询语句。
get_results()：执行 SQL 查询，并返回结果。
get_total()：返回符合条件的用户总数。

prepare_query() 方法：SQL 查询语句的生成器

prepare_query() 方法是 WP_User_Query 类中最核心的方法之一。它根据你传递的查询参数，构建复杂的 SQL 查询语句。

这个方法非常复杂，包含了大量的条件判断和字符串拼接。简单来说，它会根据你的参数，构建 WHERE 子句、ORDER BY 子句、LIMIT 子句等等。

例如，如果你传递了 'role' => 'editor' 参数，prepare_query() 方法会构建如下的 WHERE 子句：

WHERE 1=1 AND mt1.meta_key = 'wp_capabilities' AND mt1.meta_value LIKE '%"editor"%'

这个 WHERE 子句的意思是：从 wp_usermeta 表中查询 meta_key 为 wp_capabilities 并且 meta_value 包含 "editor" 的记录。

get_sql() 方法：揭开 SQL 查询语句的神秘面纱

get_sql() 方法可以让你看到 WP_User_Query 类最终生成的 SQL 查询语句。这对于调试和优化查询非常有用。

<?php
$args = array(
    'role' => 'editor'
);

$user_query = new WP_User_Query( $args );

echo '<pre>';
print_r( $user_query->get_sql() );
echo '</pre>';
?>

这段代码会输出 WP_User_Query 类生成的 SQL 查询语句。你可以复制这个 SQL 语句，在数据库管理工具中执行，看看结果是否符合你的预期。

get_results() 方法：执行查询，获取数据

get_results() 方法负责执行 prepare_query() 方法生成的 SQL 查询语句，并从数据库中获取用户数据。

它使用 $wpdb 对象来执行查询，并将结果转换为 WP_User 对象数组。

get_total() 方法：获取用户总数

get_total() 方法用于获取符合条件的用户总数。它可以用于分页功能。

<?php
$args = array(
    'role' => 'editor'
);

$user_query = new WP_User_Query( $args );

$total_users = $user_query->get_total();

echo '<p>Total editors: ' . esc_html( $total_users ) . '</p>';
?>

实际应用场景：用户列表展示与管理

get_users() 函数和 WP_User_Query 类在实际开发中有很多应用场景。比如：

用户列表展示：在后台管理界面，展示用户列表，并提供搜索、排序、分页等功能。
用户权限管理：根据用户角色或权限，控制用户对某些功能的访问。
用户数据分析：根据用户注册时间、活跃度等信息，进行用户数据分析。
自定义用户查询：根据特定需求，构建自定义的用户查询，例如，查询所有购买了某个产品的用户。

优化技巧：提升查询效率

虽然 get_users() 函数和 WP_User_Query 类已经做了很多优化，但在某些情况下，仍然需要注意一些优化技巧，以提升查询效率。

尽量使用索引：确保你的查询条件对应的字段有索引。例如，如果你经常根据 meta_key 查询用户，可以为 wp_usermeta 表的 meta_key 字段添加索引。
避免使用 LIKE '%keyword%'：这种查询方式会扫描整个表，效率很低。尽量使用 LIKE 'keyword%' 或全文索引。
限制返回的数据量：如果只需要用户 ID，可以使用 'fields' => 'ID' 参数，避免返回不必要的字段。
缓存查询结果：对于一些不经常变化的数据，可以缓存查询结果，避免重复查询数据库。

注意事项：安全第一

在使用 get_users() 函数和 WP_User_Query 类时，一定要注意安全性。

验证用户输入：对用户传递的参数进行验证，防止 SQL 注入攻击。
使用 esc_html() 函数：在输出用户数据时，使用 esc_html() 函数进行转义，防止 XSS 攻击。
控制用户权限：确保只有授权用户才能访问敏感数据。

总结：告别繁琐，拥抱便捷

get_users() 函数和 WP_User_Query 类是 WordPress 提供的强大工具，可以帮助你轻松实现各种复杂的用户查询。通过深入了解它们的原理和用法，你可以编写出更高效、更安全的代码。

记住，不要再手动拼 SQL 语句了！让 get_users() 和 WP_User_Query 帮你搞定一切。

今天的讲座就到这里，希望对大家有所帮助。祝大家编码愉快！咱们下次再见！

发表回复 取消回复

发表回复取消回复