剖析 WordPress `wp_cache_add()` 函数的源码：如何向缓存中添加一个新值，并解释其与 `wp_cache_set()` 的区别。

各位听众朋友们，大家好！我是今天的客座讲师，咱们今天来聊聊WordPress里一个挺重要的缓存函数：wp_cache_add()。 缓存这玩意儿，就像你电脑里的临时文件夹，能大大提高网站速度，让用户体验蹭蹭往上涨。

今天的内容，咱们主要围绕以下几个方面展开：

1. wp_cache_add() 的基本概念： 它到底是干嘛的？
2. 源码深度剖析： 咱们一行行过代码，看看它内部是怎么运作的。
3. 与 wp_cache_set() 的区别： 这俩哥们儿长得像，但用起来可不一样，咱们得弄明白。
4. 使用场景： 什么时候该用 wp_cache_add()，什么时候该用 wp_cache_set()？
5. 实际案例： 结合一些具体的例子，让大家更好地理解。

好了，废话不多说，咱们开始吧！

1. wp_cache_add() 的基本概念

wp_cache_add() 函数，顾名思义，是用来往 WordPress 缓存系统中 添加 一个新值的。但是！它有个非常重要的前提：这个值 必须 不存在于缓存中。如果缓存里已经有这个 key 了，wp_cache_add() 就啥也不干，直接返回 false。

你可以把它想象成一个非常严格的门卫，只有当缓存里没有这个 “人”（key）的时候，它才会允许 “新人” 进入。

函数原型：

wp_cache_add( string $key, mixed $data, string $group = '', int $expire = 0 ) : bool

• $key: 缓存的键名，就像一个身份证号码，用来唯一标识这个缓存值。
• $data: 要缓存的数据，可以是字符串、数组、对象等等，你想存什么都可以。
• $group: 缓存分组，就像一个文件夹，用来把相关的缓存值放在一起管理。默认值是空字符串。
• $expire: 缓存过期时间，单位是秒。如果设置为 0，表示永不过期（或者说是直到缓存被清理）。

返回值：

• true: 如果成功添加了缓存值。
• false: 如果缓存中已经存在相同的键名，或者添加失败。

2. 源码深度剖析

现在，咱们深入到 WordPress 源码里，看看 wp_cache_add() 到底是怎么实现的。

function wp_cache_add( $key, $data, $group = '', $expire = 0 ) {
    global $wp_object_cache;

    return $wp_object_cache->add( $key, $data, $group, (int) $expire );
}

是不是很简单？ wp_cache_add() 本身只是一个简单的包装器，它把工作委托给了全局变量 $wp_object_cache 的 add() 方法。 $wp_object_cache 是一个 WP_Object_Cache 类的实例，这个类负责管理 WordPress 的对象缓存。

接下来，咱们看看 WP_Object_Cache::add() 方法的实现（为了简化，咱们只看核心部分）：

public function add( $key, $data, $group = 'default', $expire = 0 ) {
    if ( is_object( $data ) ) {
        $data = clone $data;
    }

    if ( wp_suspend_cache_addition ) {
        return false;
    }

    if ( ! isset( $this->cache[ $group ] ) ) {
        $this->cache[ $group ] = array();
    }

    if ( false !== $this->get( $key, $group, false, $found ) ) {
        return false; // Key already exists in cache
    }

    $this->cache[ $group ][ $key ] = $data;

    return true;
}

咱们来一行行解读一下：

1. 克隆对象： 如果 $data 是一个对象，先克隆一份，避免修改原始对象。

   if ( is_object( $data ) ) {
       $data = clone $data;
   }

2. 检查是否暂停缓存添加： wp_suspend_cache_addition 是一个全局变量，如果设置为 true，表示暂停缓存添加，直接返回 false。 这通常用于某些特殊情况下，比如在数据库事务中。

   if ( wp_suspend_cache_addition ) {
       return false;
   }

3. 初始化缓存分组： 如果 $group 不存在，就创建一个新的缓存分组。

   if ( ! isset( $this->cache[ $group ] ) ) {
       $this->cache[ $group ] = array();
   }

4. 检查键名是否存在： 这是最关键的一步！ $this->get( $key, $group, false, $found ) 尝试从缓存中获取 $key 对应的值。 如果找到了，说明这个键名已经存在，直接返回 false。 注意这里的 $found 参数，它是一个引用传递的变量，用来指示是否找到了缓存值。

   if ( false !== $this->get( $key, $group, false, $found ) ) {
       return false; // Key already exists in cache
   }

5. 添加缓存值： 如果键名不存在，就把 $data 添加到缓存中。

   $this->cache[ $group ][ $key ] = $data;

6. 返回 true： 表示成功添加了缓存值。

   return true;

总结：

wp_cache_add() 的核心逻辑就是：先检查缓存中是否存在相同的键名，如果不存在，才添加新的缓存值。 这种 “先检查后添加” 的机制，保证了缓存的完整性，避免了重复添加相同键名的缓存值。

3. 与 wp_cache_set() 的区别

wp_cache_add() 和 wp_cache_set() 都是用来往 WordPress 缓存系统中添加值的，但它们之间有个本质的区别：

• wp_cache_add(): 只在缓存中 不存在 指定键名时才添加值。
• wp_cache_set(): 无论缓存中是否 存在 指定键名，都会添加或更新值。

你可以把 wp_cache_set() 想象成一个比较随和的门卫，不管缓存里有没有这个人，它都会允许 “新人” 进入，如果已经有 “同名的人”，它会直接把 “旧人” 替换掉。

wp_cache_set() 的函数原型：

wp_cache_set( string $key, mixed $data, string $group = '', int $expire = 0 ) : bool

参数和返回值与 wp_cache_add() 相同。

WP_Object_Cache::set() 方法的核心实现：

public function set( $key, $data, $group = 'default', $expire = 0 ) {
    if ( is_object( $data ) ) {
        $data = clone $data;
    }

    if ( wp_suspend_cache_addition ) {
        return false;
    }

    if ( ! isset( $this->cache[ $group ] ) ) {
        $this->cache[ $group ] = array();
    }

    $this->cache[ $group ][ $key ] = $data;

    return true;
}

可以看到，WP_Object_Cache::set() 方法并没有像 WP_Object_Cache::add() 那样先检查键名是否存在，而是直接把 $data 存入缓存中。

表格总结：

函数	功能	键名已存在时的行为
wp_cache_add()	添加一个新值到缓存中	不添加，返回 false
wp_cache_set()	添加或更新缓存中的值	更新已存在的值

4. 使用场景

那么，在实际开发中，我们应该在什么时候使用 wp_cache_add()，什么时候使用 wp_cache_set() 呢？

• 使用 wp_cache_add() 的场景：

  • 避免重复计算： 当你需要计算一个值，并且只需要计算一次时，可以使用 wp_cache_add()。 例如，计算一个帖子的总阅读数，你可以先尝试从缓存中获取，如果缓存中没有，就计算并添加到缓存中。

  • 确保唯一性： 当你需要确保缓存中的值是唯一的时，可以使用 wp_cache_add()。 例如，存储一个用户的登录 token，你可以使用 wp_cache_add() 来确保同一个用户只有一个有效的 token。

• 使用 wp_cache_set() 的场景：

  • 更新缓存值： 当你需要更新缓存中的值时，可以使用 wp_cache_set()。 例如，更新一个帖子的阅读数，你可以使用 wp_cache_set() 来更新缓存中的值。

  • 初始化缓存： 当你需要初始化缓存时，可以使用 wp_cache_set()。 例如，在插件激活时，你可以使用 wp_cache_set() 来设置一些初始的缓存值。

简单来说：

• 如果你希望只在缓存中没有这个值的时候才添加，那就用 wp_cache_add()。
• 如果你希望无论缓存中是否有这个值，都强制添加或更新，那就用 wp_cache_set()。

5. 实际案例

为了更好地理解，咱们来看几个实际的例子：

案例 1：计算并缓存帖子的总阅读数

function get_post_views( $post_id ) {
    $key = 'post_views_' . $post_id;
    $views = wp_cache_get( $key );

    if ( false === $views ) {
        // 缓存中没有，需要计算
        $views = calculate_post_views( $post_id ); // 假设这个函数负责计算阅读数

        // 添加到缓存，过期时间为 1 小时
        wp_cache_add( $key, $views, '', 3600 );
    }

    return $views;
}

在这个例子中，我们首先尝试从缓存中获取帖子的阅读数。如果缓存中没有，就计算阅读数，并使用 wp_cache_add() 将其添加到缓存中。 这样，下次访问同一个帖子时，就可以直接从缓存中获取阅读数，避免重复计算。

案例 2：更新帖子的标题

function update_post_title_cache( $post_id, $new_title ) {
    $key = 'post_title_' . $post_id;

    // 直接更新缓存中的标题
    wp_cache_set( $key, $new_title );
}

在这个例子中，我们使用 wp_cache_set() 来更新缓存中帖子的标题。 无论缓存中是否已经存在这个标题，我们都会将其更新为新的标题。

案例 3： 使用 wp_cache_add 存储用户登录 Token，确保唯一性

function generate_and_store_login_token( $user_id ) {
  $key = 'login_token_' . $user_id;
  $token = wp_generate_password( 32, true, true ); // 生成一个随机token

  // 尝试添加到缓存，如果已经存在，则返回false，需要重新生成
  $added = wp_cache_add( $key, $token, 'login_tokens', 3600 ); // 过期时间1小时

  if ( $added ) {
    return $token; // 成功添加，返回 token
  } else {
    // Token 已经存在，说明有问题，需要重新生成并存储
    // 这种情况比较少见，但为了保证唯一性，需要处理
    // 可以考虑重新生成 token 并再次尝试添加，或者记录错误日志
    error_log( 'Failed to add login token for user ' . $user_id . ' - token already exists.' );
    return false; // 或者返回一个错误代码
  }
}

这个例子展示了如何使用 wp_cache_add 确保用户登录 token 的唯一性。 如果 wp_cache_add 返回 false，说明这个用户的 token 已经存在，可能是出现了并发问题或者其他异常情况，我们需要进行相应的处理。

总结：

通过这些例子，相信大家对 wp_cache_add() 和 wp_cache_set() 的使用场景有了更清晰的认识。 选择哪个函数，取决于你的具体需求。

结语

好了，今天的分享就到这里。 wp_cache_add() 和 wp_cache_set() 都是 WordPress 缓存系统中非常重要的函数。 理解它们的区别和使用场景，可以帮助你更好地利用缓存，提高网站的性能。

希望今天的讲解对大家有所帮助。 如果大家有什么问题，欢迎提问。 下次有机会再和大家分享更多关于 WordPress 开发的知识。 谢谢大家！