分析 WordPress `rest_prepare_{post_type}` 过滤器源码：如何修改特定文章类型返回的 REST API 数据。

各位听众，大家好！我是你们今天的“WordPress REST API 数据魔改”特邀讲师。今天咱们就来聊聊 WordPress 的 rest_prepare_{post_type} 过滤器，看看如何玩转它，让你的 REST API 数据变得更有个性，更符合你的需求。准备好了吗？Let’s dive in!

第一幕：开场白 – REST API 的诱惑

先简单回顾一下，REST API 在 WordPress 里是个啥？简单来说，它就像一个数据接口，允许你通过 HTTP 请求（比如 GET、POST、PUT、DELETE）来获取和操作 WordPress 的数据，比如文章、页面、用户等等。有了它，你就可以用各种前端框架（React、Vue、Angular…）或者移动应用来构建 WordPress 的应用，而不用局限于 WordPress 的主题。

但是，有时候 WordPress 默认返回的数据格式可能不满足你的需求。比如说，你可能需要：

• 添加一些自定义字段到文章数据中。
• 修改某个字段的值。
• 过滤掉一些不需要的字段。
• 根据用户的角色返回不同的数据。

这时候，rest_prepare_{post_type} 过滤器就派上大用场了！它允许你在数据返回给客户端之前，对数据进行最后的加工。

第二幕：主角登场 – rest_prepare_{post_type} 过滤器

这个过滤器长得有点吓人，但其实很简单，它的结构是这样的：

add_filter( 'rest_prepare_{post_type}', 'your_custom_function', 10, 3 );

• {post_type}：这里替换成你要修改的文章类型。比如，如果你要修改文章（post）的数据，就写 rest_prepare_post；如果要修改页面（page）的数据，就写 rest_prepare_page。
• your_custom_function：这是你自定义的函数，用来修改数据的。
• 10：优先级，表示这个过滤器执行的顺序。数字越小，优先级越高。
• 3：接受的参数个数。rest_prepare_{post_type} 过滤器会传递三个参数给你的函数：
  • $response：WP_REST_Response 对象，包含了要返回的数据。
  • $post：WP_Post 对象，表示当前的文章。
  • $request：WP_REST_Request 对象，包含了请求的信息。

第三幕：实战演练 – 修改文章数据

咱们以修改文章（post）的数据为例，来演示一下如何使用 rest_prepare_post 过滤器。

场景一：添加自定义字段

假设你的文章有一个自定义字段 my_custom_field，你想把它添加到 REST API 返回的数据中。你可以这样写：

function add_custom_field_to_post( $response, $post, $request ) {
    $custom_field_value = get_post_meta( $post->ID, 'my_custom_field', true );
    $response->data['my_custom_field'] = $custom_field_value;
    return $response;
}
add_filter( 'rest_prepare_post', 'add_custom_field_to_post', 10, 3 );

这段代码做了什么？

1. 定义了一个名为 add_custom_field_to_post 的函数，它接收 $response、$post 和 $request 三个参数。
2. 使用 get_post_meta 函数获取 my_custom_field 的值。
3. 把这个值添加到 $response->data 数组中，键名为 my_custom_field。
4. 返回修改后的 $response 对象。
5. 使用 add_filter 函数把这个函数挂载到 rest_prepare_post 过滤器上。

现在，当你通过 REST API 请求文章数据时，你会发现多了一个 my_custom_field 字段。

场景二：修改现有字段的值

有时候，你可能想修改 WordPress 默认返回的字段的值。比如说，你想把文章的标题变成大写。你可以这样写：

function uppercase_post_title( $response, $post, $request ) {
    $response->data['title']['rendered'] = strtoupper( $response->data['title']['rendered'] );
    return $response;
}
add_filter( 'rest_prepare_post', 'uppercase_post_title', 10, 3 );

这段代码很简单，就是把 $response->data['title']['rendered'] 的值转换成大写。

场景三：过滤掉不需要的字段

有时候，你可能想从 REST API 返回的数据中删除一些字段。比如说，你不想返回文章的内容。你可以这样写：

function remove_post_content( $response, $post, $request ) {
    unset( $response->data['content'] );
    return $response;
}
add_filter( 'rest_prepare_post', 'remove_post_content', 10, 3 );

这段代码使用 unset 函数删除了 $response->data['content'] 字段。

场景四：根据用户角色返回不同的数据

有时候，你可能想根据用户的角色返回不同的数据。比如说，只有管理员才能看到文章的某些自定义字段。你可以这样写：

function filter_post_data_by_role( $response, $post, $request ) {
    if ( ! current_user_can( 'administrator' ) ) {
        unset( $response->data['my_custom_field'] );
    }
    return $response;
}
add_filter( 'rest_prepare_post', 'filter_post_data_by_role', 10, 3 );

这段代码使用 current_user_can 函数检查当前用户是否是管理员。如果不是，就删除 my_custom_field 字段。

第四幕：进阶技巧 – 使用 $request 对象

$request 对象包含了请求的信息，你可以利用它来做很多事情。比如说，你可以根据请求的参数来过滤数据。

假设你的 REST API 接口有一个参数 show_excerpt，如果它的值为 true，就返回文章的摘要；否则，就不返回。你可以这样写：

function conditionally_show_excerpt( $response, $post, $request ) {
    $params = $request->get_params();
    if ( isset( $params['show_excerpt'] ) && $params['show_excerpt'] === 'true' ) {
        $response->data['excerpt']['rendered'] = wp_trim_words( get_the_excerpt( $post->ID ), 55, '...' );
    } else {
        unset( $response->data['excerpt'] );
    }
    return $response;
}
add_filter( 'rest_prepare_post', 'conditionally_show_excerpt', 10, 3 );

这段代码做了什么？

1. 使用 $request->get_params() 函数获取请求的参数。
2. 检查 show_excerpt 参数是否存在，并且它的值是否为 true。
3. 如果满足条件，就返回文章的摘要；否则，就不返回。

现在，你可以通过在请求 URL 中添加 show_excerpt=true 参数来控制是否返回文章的摘要。

第五幕：注意事项 – 避免踩坑

在使用 rest_prepare_{post_type} 过滤器时，有一些地方需要注意：

• 性能问题： 尽量避免在过滤器中执行复杂的查询或计算，这可能会影响 API 的性能。
• 数据安全： 注意对用户输入进行验证和过滤，防止 XSS 攻击。
• 代码可读性： 保持代码简洁易懂，添加必要的注释。
• 调试技巧： 使用 error_log 函数来调试代码，或者使用 WordPress 的调试模式。
• 兼容性： 确保你的代码与 WordPress 的版本兼容。

表格总结：

功能	代码示例	说明
添加自定义字段	php $response->data['my_custom_field'] = $custom_field_value;	将自定义字段的值添加到 REST API 响应数据中。
修改现有字段的值	php $response->data['title']['rendered'] = strtoupper( $response->data['title']['rendered'] );	修改 REST API 响应数据中现有字段的值，例如将文章标题转换为大写。
过滤掉不需要的字段	php unset( $response->data['content'] );	从 REST API 响应数据中删除不需要的字段，例如删除文章内容。
根据用户角色返回不同的数据	php if ( ! current_user_can( 'administrator' ) ) { unset( $response->data['my_custom_field'] ); }	根据用户的角色控制 REST API 响应数据的内容，例如只有管理员才能看到某些自定义字段。
使用 $request 对象	php $params = $request->get_params(); if ( isset( $params['show_excerpt'] ) && $params['show_excerpt'] === 'true' ) { ... } | 通过 $request 对象获取请求参数，并根据参数的值来动态调整 REST API 响应数据的内容。
调试代码	php error_log( 'Debug message: ' . print_r( $response->data, true ) ); | 使用 error_log 函数将调试信息写入服务器日志，方便调试代码。
优先级	php add_filter( 'rest_prepare_post', 'your_custom_function', 5, 3 ); // 优先级更高 add_filter( 'rest_prepare_post', 'your_custom_function', 15, 3 ); // 优先级更低	决定了过滤器执行的顺序。数字越小，优先级越高，意味着过滤器会更早地执行。如果多个过滤器都修改了同一个字段，优先级高的过滤器会先执行，它的修改结果可能会被优先级低的过滤器覆盖。因此，在设置优先级时需要仔细考虑，确保各个过滤器能够按照预期的顺序执行。
参数数量	php add_filter( 'rest_prepare_post', 'your_custom_function', 10, 3 ); | rest_prepare_{post_type} 过滤器总是传递 3 个参数：$response、$post 和 $request。因此，你的回调函数必须能够接收这 3 个参数，否则可能会导致错误。即使你的回调函数只需要使用其中的一部分参数，也必须定义所有的参数。

第六幕：尾声 – 数据的魔力

rest_prepare_{post_type} 过滤器是一个强大的工具，它可以让你灵活地修改 WordPress REST API 返回的数据。掌握了它，你就可以构建出更加个性化、更加符合需求的 WordPress 应用。

今天的讲座就到这里。希望大家能够学以致用，玩转 WordPress REST API 数据！感谢大家的聆听！下课！