## 概述

在 Headless WordPress 架构中，自定义 REST API 端点是与外部系统交互的核心通道。然而，生产环境常常面临两大挑战：API 认证在各类服务器配置下的兼容性问题，以及第三方平台（如微信公众号）对内容格式的严苛要求。本文分享萨龙网络在龙霄主题项目中针对这两个痛点的优化实践。

## 一、自定义 REST API 的安全加固

在之前的版本中，我们使用 `define('HERMES_AI_PUBLISH_API_KEY', 'xxx')` 定义 API 密钥，并在认证回调中通过常量比较验证请求。这种方式在实际部署中暴露出两个问题：

### 1. 常量被意外覆盖

WordPress 的 `define()` 是幂等的——如果同一个常量名在其他地方先被定义，插件中的定义会被静默忽略。在萨龙网络的服务器上，主题或框架代码中可能存在同名的常量定义，导致插件中预设的密钥失效。解决方案是使用 `defined()` 守卫和更独特的常量名：

```
if (!defined('HERMES_PUBLISH_SECRET')) {
    define('HERMES_PUBLISH_SECRET', 'hermes-ai-publish-key-2026');
}
```

更彻底的做法是直接在认证逻辑中硬编码密钥进行比较，完全避免常量解析的不确定性：

```
return !empty($key) && $key === 'hermes-ai-publish-key-2026';
```

### 2. 请求头的多层级回退

Nginx、CDN 或安全插件可能会对自定义 HTTP 头进行规范化处理（如统一转为小写）甚至直接剥离。为保证兼容性，认证逻辑需要建立多层级的 header 回退链：

```
$key = $request->get_header('X-Hermes-Key');        // WP 规范化
if (empty($key)) $key = $request->get_header('x-hermes-key'); // 全小写
if (empty($key)) $key = $_SERVER['HTTP_X_HERMES_KEY'] ?? '';  // 原始头
if (empty($key)) $key = $request->get_param('key');           // URL 参数
```

这个回退链覆盖了 WP REST API 规范化、Nginx 小写转换、以及极端情况下头被剥离后通过 query string 传递的场景。

### 3. Debug 端点的价值

在生产环境中调试 API 认证问题时，添加一个无需认证的 `/debug` 端点可以极大节省排查时间。该端点直接返回请求头的原始信息和当前常量的解析值：

```
register_rest_route('hermes/v1', '/debug', [
    'methods'  => 'GET',
    'callback' => function ($request) {
        return rest_ensure_response([
            'headers'     => $request->get_headers(),
            'param_key'   => $request->get_param('key'),
            'defined_key' => defined('HERMES_PUBLISH_SECRET') 
                ? HERMES_PUBLISH_SECRET : 'NOT_DEFINED',
        ]);
    },
    'permission_callback' => '__return_true',
]);
```

通过这个端点，可以快速确认：请求头是否正确到达了 WordPress、常量是否被覆盖、以及认证失败的具体环节。

## 二、微信公众号文章排版自动化

萨龙网络的龙霄主题集成了微信公众号草稿同步功能。当文章在 WordPress 后台发布后，需要自动将内容推送到微信公众号的草稿箱。这个过程的核心挑战在于：微信公众平台对 HTML 的支持非常有限。

### 1. 从主题配置中提取排版参数

传统的做法是硬编码一套固定的字号和行高。但龙霄主题提供了丰富的主题选项，允许用户自定义各级标题和正文字号。改进方案是动态读取主题配置中的 `style_general` 选项：

```
$styleGeneral = (array) salong_theme_options('style_general');
// 提取 h1-h6 的 fontSize 和 lineHeight
foreach (['h1', 'h2', 'h3', 'h4', 'h5', 'h6'] as $tag) {
    $size   = $styleGeneral[$tag]['width'] ?? '';
    $height = $styleGeneral[$tag]['height'] ?? '';
    $h[$tag] = [
        'size'   => $size ? $size . 'px' : '',
        'height' => $height ? $height . 'px' : '',
    ];
}
// 正文优先使用移动端字号配置
$bodySize = $styleGeneral['post_content_mobile']['width'] 
    ?? $styleGeneral['body']['width'] 
    ?? '16px';
```

这样做的好处是：微信端的排版自动跟随主题设置，无需额外维护一套独立的样式配置。

### 2. HTML 内容清洗流水线

微信公众号不支持 `<iframe>`、`<video>`、`<audio>`、`<embed>`、`<script>`、`<style>` 等标签。此外，Gutenberg 编辑器会在输出中插入大量块级 HTML 注释（如 `\<!-- wp:paragraph -->`）。清洗流水线如下：

```
// 1. 移除不支持的标签
$html = preg_replace('/<iframeb[^>]*>.*</iframe>/is', '', $html);
$html = preg_replace('/<videob[^>]*>.*</video>/is', '', $html);
$html = preg_replace('/<audiob[^>]*>.*</audio>/is', '', $html);
$html = preg_replace('/<embedb[^>]*>/i', '', $html);
$html = preg_replace('/<scriptb[^>]*>.*</script>/is', '', $html);
$html = preg_replace('/<styleb[^>]*>.*</style>/is', '', $html);
$html = preg_replace('/<linkb[^>]*>/i', '', $html);

// 2. 移除 Gutenberg 块注释
$html = preg_replace('/<!--s*/?wp:.*?-->s*/s', '', $html);

// 3. 为段落和图片注入内联样式
$html = preg_replace('/<p(?![^>]*bstyle=)([^>]*)>/i', 
    '<p style="margin:0 0 16px;"$1>', $html);
$html = preg_replace('/<img(?![^>]*bstyle=)([^>]*)>/i', 
    '<img style="max-width:100%;height:auto;"$1>', $html);
```

### 3. 作者信息自动填充

新版本还增加了从 WordPress 用户资料自动获取作者信息的功能：

```
$author_id   = (string) get_the_author_meta('ID', $post_id);
$author_data = User::data($author_id);
$article['author'] = $author_data['name'] ?? '';
```

同时保留了「直接发布」模式的扩展点，为未来实现自动发布到微信公众号（而非仅保存草稿）预留了接口。

## 三、实践总结

本次优化围绕两个核心原则：**防御性编程**和**配置驱动**。

在 API 安全层面，不假设单一认证方式在所有环境下都能正常工作。通过多层回退、debug 端点、以及硬编码兜底策略，确保服务的鲁棒性。在内容格式化层面，将排版参数的控制权交还给主题配置系统，避免硬编码带来的维护负担。

这些实践同样适用于其他 WordPress 与第三方平台集成的场景——无论是对接微信小程序、飞书文档、还是企业微信，认证兼容性和内容适配都是必须认真对待的工程问题。