一个模块化 WordPress 插件后台的标准结构（实战向）

当一个 WordPress 插件开始变得“像产品”，后台结构往往会最先暴露问题。

一开始可能只有几个开关、几个输入框，一页 PHP 表单就能解决；
但随着功能增加、模块增多，很多插件都会走向同一条老路：

• 设置项越来越多
• 页面越来越长
• 不同功能混在一起
• 改一个地方，牵一发动全身

这并不是能力问题，而是插件后台没有在一开始就建立“模块化结构”。

本文将从实战角度，拆解一个真正适合长期维护的模块化 WordPress 插件后台结构，帮助你从“能用”，走向“可持续”。

---

一、什么叫“模块化插件后台”？

先澄清一个容易被误解的概念。

模块化，不是指代码分文件多一点。

而是指：

每一个功能模块，在后台都有清晰的边界、独立的设置入口、可单独维护的逻辑结构。

一个模块化后台，至少具备这三个特征：

1. 功能边界清晰
2. 设置页彼此独立
3. 模块之间低耦合

如果你关掉其中一个模块，其他模块不应该受到影响。

---

二、插件后台为什么一定要模块化？

从用户视角看，模块化意味着：

• 设置更好找
• 功能逻辑更清晰
• 不会被无关选项干扰

从开发者视角看，模块化意味着：

• 新功能可以“按模块添加”
• 老功能可以“按模块重构”
• Bug 更容易定位
• 后期扩展不会推倒重来

模块化，本质是在为插件的未来“留扩展位”。

---

三、推荐的插件目录结构（核心）

下面是一套经过大量插件实践验证、非常稳妥的目录结构示例：

my-plugin/
├─ my-plugin.php               # 插件入口
├─ includes/
│  ├─ bootstrap.php            # 初始化加载
│  ├─ admin/
│  │  ├─ menu.php              # 后台菜单注册
│  │  ├─ assets.php            # 后台资源加载
│  │  └─ rest.php               # 通用 REST 注册
│  ├─ modules/
│  │  ├─ module-a/
│  │  │  ├─ module.php
│  │  │  ├─ admin.php
│  │  │  └─ rest.php
│  │  └─ module-b/
│  │     ├─ module.php
│  │     ├─ admin.php
│  │     └─ rest.php
├─ admin-ui/
│  ├─ src/                      # React 源码
│  ├─ build/                    # 构建产物
│  └─ index.js
└─ assets/

你可以看到一个非常明确的原则：

模块不是“功能开关”，而是一级结构单元。

---

四、后台菜单结构：模块化的第一道门

推荐做法

• 插件主菜单：只做“入口”
• 每个模块：一个独立子菜单

示例逻辑：

插件名称
├─ 总览 / Dashboard
├─ 模块 A 设置
├─ 模块 B 设置
└─ 高级设置（可选）

不要把所有模块塞进一个巨大的设置页。

这是很多插件后期失控的根源。

---

五、每个模块应该包含哪些东西？

一个“合格的后台模块”，至少包含以下 4 层：

1️⃣ 模块定义层（module.php）

• 模块是否启用
• 模块标识（slug / name）
• 模块依赖

这是“模块存在与否”的判断层。

---

2️⃣ 后台接入层（admin.php）

• 注册该模块的子菜单
• 输出 React 挂载容器
• 控制权限（capability）

每个模块只关心自己的后台页面。

---

3️⃣ 数据接口层（rest.php）

• 获取模块设置
• 保存模块设置
• 处理分页 / 搜索 / 批量操作

模块之间不共用 REST 逻辑，避免互相污染。

---

4️⃣ 前端界面层（React）

• UI 组件
• 表单
• 列表
• 交互逻辑

React 层只做一件事：

把模块能力“可视化 + 可操作化”。

---

六、设置数据应该怎么存？（非常关键）

这是模块化后台中最容易踩坑的点。

❌ 错误做法

• 所有模块共用一个巨大 option
• 所有设置混在一个数组里

✅ 推荐策略

场景	建议
少量配置	每模块一个 option
规则/列表型数据	自定义表 或 分片 option
与文章强关联	post meta
与用户强关联	user meta

核心原则只有一句话：

数据结构必须服从“模块边界”，而不是图省事。

---

七、为什么 React 特别适合模块化后台？

当你用 React 来做后台 UI 时，模块化会变得“天然”。

• 一个模块 = 一个页面组件
• 一个模块 = 一套 state
• 一个模块 = 一组 API

你不需要在 PHP 里判断“现在是哪个模块”，
React 页面本身就是模块。

这也是为什么 模块化插件 + React 后台 是一对天然组合。

---

八、模块化后台的“终极好处”

当你的插件做到这一层结构时，你会发现：

• 新模块几乎不影响旧模块
• 可以单独重构某个模块
• 可以按模块做授权 / 付费
• 可以按模块做性能优化

这时候，你写的已经不再是“一个插件”，
而是一个可长期演进的系统。

---

九、写在最后

很多插件的失败，并不是功能不够强，
而是结构不允许它继续成长。

模块化后台不是一开始就必须做到满分，
但一开始就选对方向，会决定你以后写代码是“修修补补”，还是“从容扩展”。

如果你正在认真对待一个插件项目，
这套结构，值得你从第一行代码就开始考虑。

---