在主题里用「单页 + $_REQUEST」做 JSON API（例如 c=PatrolSkipReason&a=add&name=...）时，常出现列表正常、带 name 的写入却 404 或行为异常。排查后发现与业务语法无关，而是 WordPress 对查询变量 name 的保留与主查询干扰。本文记录原因与改参办法。

问题背景

• 场景：前端通过 POST /api-data 提交表单，其中包含展示名称参数 name。
• 现象：getList 正常；带 name 的 add 等请求出现 HTTP 404 或路由被改写。
• 为何值得关注：name 在业务里很常见，但在 WordPress 请求生命周期里属于核心查询变量（通常对应文章 slug），与自定义页上的「伪 API」叠加时，容易触发重写规则或主查询。

原因说明

1. name 是保留语义：用于按 post name 解析主查询（单篇文章、固定链接等）。
2. 主查询优先：解析器按已注册的 query_vars 处理；模板里再读 $_REQUEST['name'] 时，上游可能已消费或改写该参数。
3. 误判：同一入口下「不带 name 的列表能通过、带 name 的写操作失败」，容易误判为控制器或 add 方法语法错误。

解决办法（推荐）

原则：在面向 WordPress 前端的请求里，不要用 name 作为自定义业务参数名。

• 前端：改为 reason_name、title、label、display_name 等非保留名，并避开 p、page、pagename、attachment 等公共查询变量。
• 后端：读取时优先新参数，再回退旧参数，兼容老客户端。
• 数据库：表字段仍可叫 name，仅 HTTP 参数改名，降低与 WP 全局行为的耦合。

// 优先 reason_name；仍兼容旧参数 name
private static function display_name_from_args($args) {
    if (!is_array($args)) return '';
    if (isset($args['reason_name'])) {
        $v = trim((string) $args['reason_name']);
        if ($v !== '') return $v;
    }
    if (isset($args['name'])) {
        return trim((string) $args['name']);
    }
    return '';
}

延伸建议

• 自建 API 页：POST Body 参数名尽量避开 WordPress 公共查询变量。
• 调试时区分 HTTP 404 与 JSON 里业务码「接口不存在」。
• 不推荐为抢救 name 去大幅改写核心 query_vars，维护成本高。

总结