分析 WordPress `wp_send_json_success()` 和 `wp_send_json_error()` 函数的源码：如何返回格式化的 JSON 响应。

大家好，我是你们今天的JSON格式化响应大师。今天我们要深入探讨WordPress的wp_send_json_success() 和 wp_send_json_error() 这两个好用的函数，看看它们是如何优雅地返回格式化的JSON响应的。准备好了吗？让我们开始吧！

开场：为什么我们需要格式化的JSON响应？

想象一下，你是一位辛勤的WordPress开发者，你的插件或者主题需要和前端进行数据交互。你辛辛苦苦地处理完数据，难道要直接把数据一股脑地丢给前端？当然不行！我们需要一个清晰、一致、易于解析的格式，让前端能够轻松地理解并使用这些数据。JSON（JavaScript Object Notation）就是为此而生的。它是一种轻量级的数据交换格式，易于人阅读和编写，同时也易于机器解析和生成。

进入正题：wp_send_json_success() 和 wp_send_json_error() 闪亮登场

WordPress为我们提供了两个非常方便的函数，专门用于发送JSON响应：wp_send_json_success() 和 wp_send_json_error()。它们的主要作用是：

• 格式化数据： 将你的数据转换成JSON格式。
• 设置响应头： 确保浏览器知道这是一个JSON响应。
• 发送响应： 将JSON数据发送给客户端。
• 结束请求： 避免后续代码继续执行，防止产生意外的输出。

这两个函数的用法非常简单，但它们背后却隐藏着一些值得我们学习的技巧。让我们深入源码，一探究竟。

源码剖析：wp_send_json_success()

首先，我们来看看wp_send_json_success() 的源码（以WordPress 6.x版本为例）：

function wp_send_json_success( $data = null, $status_code = null ) {
    return _wp_ajax_response( $data, 'success', $status_code );
}

咦？怎么这么简单？原来它只是调用了另一个函数 _wp_ajax_response()。别急，好戏还在后头。我们继续追踪 _wp_ajax_response() 的源码：

function _wp_ajax_response( $data = null, $type = 'success', $status_code = null ) {
    $status = 'success' === $type; // Convert type to boolean for internal checks.

    $response = array(
        'success' => $status,
        'data'    => $data,
    );

    if ( null !== $status_code ) {
        status_header( $status_code );
    }

    wp_send_json( $response );
}

现在，我们看到了一些关键的步骤：

1. 构建响应数组： 将传入的数据 $data 和表示成功的状态 'success' 组合成一个关联数组 $response。这个数组是最终要转换成JSON的对象。
2. 设置HTTP状态码（可选）： 如果传入了 $status_code，则使用 status_header() 函数设置HTTP状态码。这允许你根据不同的情况返回不同的状态码，例如200 OK，201 Created等等。
3. 发送JSON响应： 调用 wp_send_json() 函数将 $response 数组转换成JSON格式并发送给客户端。

源码剖析：wp_send_json_error()

接下来，我们来看看 wp_send_json_error() 的源码：

function wp_send_json_error( $data = null, $status_code = null ) {
    return _wp_ajax_response( $data, 'error', $status_code );
}

和 wp_send_json_success() 几乎一样！它也是调用了 _wp_ajax_response() 函数，只不过传入的 $type 参数是 'error'。

这意味着，_wp_ajax_response() 函数是核心，它负责处理成功和失败两种情况的JSON响应。

再来回顾一下 _wp_ajax_response() 函数：

function _wp_ajax_response( $data = null, $type = 'success', $status_code = null ) {
    $status = 'success' === $type; // Convert type to boolean for internal checks.

    $response = array(
        'success' => $status,
        'data'    => $data,
    );

    if ( null !== $status_code ) {
        status_header( $status_code );
    }

    wp_send_json( $response );
}

唯一的区别在于，wp_send_json_error() 会将 'success' 键的值设置为 false，表示这是一个错误响应。

深入 wp_send_json()

现在，我们来看看 wp_send_json() 函数的源码：

function wp_send_json( $response, $status_code = null ) {
    global $wp_json_encoder;

    if ( null !== $status_code ) {
        status_header( $status_code );
    }

    header( 'Content-Type: application/json; charset=' . get_option( 'blog_charset' ) );
    header( 'X-Content-Type-Options: nosniff' );

    if ( ! is_string( $response ) ) {
        if ( version_compare( phpversion(), '5.3.0', '>=' ) ) {
            $options = JSON_UNESCAPED_UNICODE;

            if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) {
                $options |= JSON_PRETTY_PRINT;
            }

            $response = wp_json_encode( $response, $options );
        } else {
            $response = wp_json_encode( $response );
        }
    }

    echo $response;

    if ( function_exists( 'wp_die' ) ) {
        wp_die();
    } else {
        die();
    }
}

这个函数做了以下几件事：

1. 设置HTTP状态码（可选）： 类似于 _wp_ajax_response()，如果传入了 $status_code，则使用 status_header() 函数设置HTTP状态码。
2. 设置响应头： 设置 Content-Type 为 application/json，告诉浏览器这是一个JSON响应。还设置了 X-Content-Type-Options: nosniff，防止浏览器进行MIME类型嗅探，增强安全性。
3. JSON编码： 如果传入的 $response 不是字符串，则使用 wp_json_encode() 函数将其转换为JSON字符串。
   • wp_json_encode() 内部实际上调用的是PHP的 json_encode() 函数，但WordPress对其进行了一些封装，以确保兼容性和安全性。
   • 如果PHP版本大于等于5.3.0，并且开启了WP_DEBUG模式，则会使用 JSON_UNESCAPED_UNICODE 和 JSON_PRETTY_PRINT 选项，使JSON输出更易于阅读。JSON_UNESCAPED_UNICODE 确保Unicode字符不被转义，JSON_PRETTY_PRINT 则会添加缩进和换行，使JSON更美观。
4. 输出JSON： 使用 echo 语句将JSON字符串输出到客户端。
5. 结束请求： 调用 wp_die() 函数结束请求，防止后续代码继续执行。如果 wp_die() 函数不存在（例如在某些测试环境中），则使用 PHP 的 die() 函数。

使用示例：让代码说话

现在，让我们通过一些实际的例子来演示如何使用 wp_send_json_success() 和 wp_send_json_error()。

示例1：成功获取用户信息

<?php
// 假设我们从数据库中获取了用户信息
$user_data = array(
    'id'       => 123,
    'username' => 'john.doe',
    'email'    => '[email protected]',
);

// 使用 wp_send_json_success() 发送JSON响应
wp_send_json_success( $user_data );

// 上面的代码会输出类似下面的JSON：
// {
//   "success": true,
//   "data": {
//     "id": 123,
//     "username": "john.doe",
//     "email": "[email protected]"
//   }
// }
?>

示例2：用户认证失败

<?php
// 假设用户认证失败
$error_message = '用户名或密码错误';

// 使用 wp_send_json_error() 发送JSON响应
wp_send_json_error( $error_message, 401 ); // 401 Unauthorized

// 上面的代码会输出类似下面的JSON：
// {
//   "success": false,
//   "data": "用户名或密码错误"
// }

// 并且会设置HTTP状态码为 401 Unauthorized
?>

示例3：更复杂的数据结构

<?php
$data = array(
    'posts' => array(
        array(
            'id' => 1,
            'title' => '第一篇文章',
            'content' => '文章内容...'
        ),
        array(
            'id' => 2,
            'title' => '第二篇文章',
            'content' => '文章内容...'
        )
    ),
    'total' => 2
);

wp_send_json_success( $data );

// 输出类似：
// {
//  "success": true,
//  "data": {
//   "posts": [
//    {
//     "id": 1,
//     "title": "第一篇文章",
//     "content": "文章内容..."
//    },
//    {
//     "id": 2,
//     "title": "第二篇文章",
//     "content": "文章内容..."
//    }
//   ],
//   "total": 2
//  }
// }
?>

注意事项：避坑指南

• 数据类型： wp_send_json() 可以处理各种PHP数据类型，包括数组、对象、字符串、数字等。但是，请确保你的数据结构是有效的JSON格式。
• 字符编码： 确保你的WordPress站点使用UTF-8字符编码，避免出现乱码问题。
• 安全： 在处理用户输入时，要进行适当的验证和过滤，防止XSS攻击。
• 状态码： 根据实际情况设置合适的HTTP状态码，让客户端能够更好地理解响应结果。常见的状态码包括：
  • 200 OK：请求成功。
  • 201 Created：资源创建成功。
  • 400 Bad Request：客户端请求错误。
  • 401 Unauthorized：需要用户认证。
  • 403 Forbidden：没有权限访问。
  • 404 Not Found：资源不存在。
  • 500 Internal Server Error：服务器内部错误。
• 调试： 在开发过程中，可以使用浏览器的开发者工具或者一些在线JSON格式化工具来查看和调试JSON响应。

最佳实践：让你的JSON更上一层楼

• 统一的响应格式： 在你的项目中，尽量使用统一的JSON响应格式，例如：

  {
    "success": true,
    "code": 200,
    "message": "操作成功",
    "data": {
      // 实际数据
    }
  }

  或者

  {
    "success": false,
    "code": 400,
    "message": "参数错误",
    "data": {
      // 错误信息
    }
  }

  这样做可以提高代码的可维护性和可读性。

• 使用HTTP状态码： 不要仅仅依赖 success 字段来判断请求是否成功，也要充分利用HTTP状态码。

• 详细的错误信息： 在错误响应中，提供尽可能详细的错误信息，帮助客户端进行调试。

• 分页： 如果你的API需要返回大量数据，可以使用分页技术，避免一次性返回所有数据。

总结：JSON响应的艺术

wp_send_json_success() 和 wp_send_json_error() 是WordPress中非常实用的函数，它们可以帮助我们轻松地生成格式化的JSON响应。通过深入了解它们的源码，我们可以更好地理解它们的工作原理，并在实际开发中灵活运用。记住，清晰、一致、易于理解的JSON响应是构建优秀API的关键。希望今天的讲座对你有所帮助，谢谢大家！

表格总结：

函数	作用	核心函数	默认 success 值
wp_send_json_success()	发送成功的JSON响应，设置 success 为 true。	_wp_ajax_response()	true
wp_send_json_error()	发送错误的JSON响应，设置 success 为 false。	_wp_ajax_response()	false
_wp_ajax_response()	构建JSON响应数组，根据传入的 $type 参数设置 success 的值。	wp_send_json()	N/A
wp_send_json()	设置HTTP状态码、响应头，将PHP数据转换为JSON字符串，并发送给客户端。如果开启 WP_DEBUG 模式，会格式化JSON输出。最后，使用 wp_die() 或 die() 结束请求。	N/A	N/A