wordpress【开发者日志 & 公开分享文档】

这次的分享，将为众多开发者解决长期以来 NPS 开发中最隐蔽、最难排查的问题 —— 没有审计系统，无日志留痕，出了错无从查起。而这个 nps_log() 函数将真正做到，可以对每一个函数如何请求的、如何回应的，哪里出错的都能明确的追踪执行过程。这个开发日志函数是我自己在开发过程中为了排除错误而写的，非常有用于是分享出来记录在这里，当然这个日志函数可应用在任何插件的开发上：

📦 “开发可回放、调试可定位、安全可追踪、运营可审计”

比如在使用 NPS（Nginx Proxy Server）进行客户端配置管理、同步、恢复等操作时，接口行为非常复杂 —— 包含了用户身份、多个字段变更、数据结构深嵌套，以及网络请求行为。

问题痛点：

• 请求失败无法溯源

• curl 请求丢失无法复现

• 接口执行成功却没有日志

• 多人开发协作看不清谁做了什么

于是，我们开发了一个通用日志函数 nps_log()，将所有关键行为 结构化地记录到数据库，从此再也不怕「不知谁、何时、对谁做了什么」。

✅ 使用场景

• 用户同步客户端配置时

• 管理员修改客户端限速、流量

• 恢复历史备份配置

• 与 NPS API 接口交互时

• 用户中心触发自动操作

🧠 函数原型代码（建议复制粘贴到 functions.php）

/**
 * ✅ NPS 操作日志记录函数
 * 用于记录接口行为、请求参数、响应数据、资源变更、curl重放命令等
 * 建议用于所有调用 NPS 接口的地方
 */
function nps_log($params = []) {
    global $wpdb;
    $table = $wpdb->prefix . 'nps_logs';

    if (empty($params['action'])) {
        return false; // 必须指定操作名称
    }

    // 基础字段
    $user_id = isset($params['user_id']) ? intval($params['user_id']) : null;
    $nps_id  = isset($params['nps_id']) ? intval($params['nps_id']) : null;
    $action  = sanitize_text_field($params['action']);
    $api_url = isset($params['api_url']) ? esc_url_raw($params['api_url']) : null;

    // 请求和响应
    $request_data = isset($params['request_data']) ? maybe_serialize($params['request_data']) : null;
    $response_data = isset($params['response_data'])
        ? (is_array($params['response_data']) || is_object($params['response_data'])
            ? maybe_serialize($params['response_data'])
            : sanitize_textarea_field($params['response_data']))
        : null;

    $status  = isset($params['status']) ? intval($params['status']) : 0;
    $message = isset($params['message']) ? sanitize_textarea_field($params['message']) : null;
    $resource_changes = isset($params['resource_changes']) ? maybe_serialize($params['resource_changes']) : null;

    // 构造 curl 命令
    $curl_cmd = null;
    if (!empty($api_url) && !empty($params['request_data']) && is_array($params['request_data'])) {
        $post_fields = http_build_query($params['request_data']);
        $curl_cmd = "curl -X POST '" . esc_url_raw($api_url) . "' -d '" . $post_fields . "'";
    }

    // 分析资源变更中的流量变动
    $flow_change = '无';
    if (!empty($params['resource_changes']) && is_array($params['resource_changes'])) {
        if (isset($params['resource_changes']['flow_limit'])) {
            $old = $params['resource_changes']['flow_limit']['old'] ?? '无';
            $new = $params['resource_changes']['flow_limit']['new'] ?? '无';
            $flow_change = "{$old} → {$new}";
        }
    } elseif (isset($params['flow_change'])) {
        $flow_change = sanitize_text_field($params['flow_change']);
    }

    // 最终写入数据库
    $data = [
        'user_id'          => $user_id,
        'nps_id'           => $nps_id,
        'action'           => $action,
        'api_url'          => $api_url,
        'request_data'     => $request_data,
        'response_data'    => $response_data,
        'curl_cmd'         => $curl_cmd,
        'status'           => $status,
        'message'          => $message,
        'resource_changes' => $resource_changes,
        'flow_change'      => $flow_change,
        'created_at'       => current_time('mysql')
    ];

    return $wpdb->insert($table, $data) !== false;
}

🔧 用法示例（同步客户端）

nps_log([
    'user_id'     => get_current_user_id(),
    'nps_id'      => $client_id,
    'action'      => 'sync_client',
    'api_url'     => $api_url,
    'request_data'=> $post_data,
    'response_data'=> $response_body,
    'status'      => $ok ? 1 : 0,
    'message'     => $ok ? '✅ 客户端同步成功' : '❌ 同步失败',
    'resource_changes' => [
        'flow_limit' => ['old' => '10 GB', 'new' => '50 GB']
    ]
]);

📊 数据库设计建议（字段名）

你需要有一个数据库表，比如叫 wp_nps_logs：

CREATE TABLE `wp_nps_logs` (
  `id` bigint UNSIGNED NOT NULL AUTO_INCREMENT,
  `user_id` bigint DEFAULT NULL,
  `nps_id` bigint DEFAULT NULL,
  `action` varchar(100) NOT NULL,
  `api_url` text,
  `request_data` longtext,
  `response_data` longtext,
  `curl_cmd` text,
  `status` tinyint DEFAULT 0,
  `message` text,
  `resource_changes` longtext,
  `flow_change` varchar(255),
  `created_at` datetime DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

🧠 开发建议

一句话总结

✨ “没有日志的系统无法运营。”

还可以用这个函数，做成审计与动作行为追踪拓展。