用 Gophenberg 编写第一个 Go 插件:以 RSS Feed 为参考的实战教程
用 Gophenberg 编写第一个 Go 插件:以 RSS Feed 为参考的实战教程
Gophenberg 是一款插件优先(plugin-first)的 CMS:Go 后端、React 管理界面、Gutenberg 块编辑器。它的核心理念只有一条——"能做成插件的,就一定是插件"。除了 HTTP 服务器、认证和内容域之外,其余功能全部由插件提供。
本文以 Gophenberg 自带的官方参考插件 RSS Feed(plugins/feed)为蓝本,带你从零编写并接入第一个 Go 插件:认识 plugin.json 清单、实现 Register 入口、声明路由与公开路径,再用 make generate 一键完成自动接线。全程只依赖官方文档和参考源码,跟着做就能跑通。
想先看官方教程?可参考仓库内的 write-a-plugin.md 与 the-plugin-sdk.md。
一、动手前:Gophenberg 插件长什么样
一个 Gophenberg 插件就是 plugins/ 目录下的一个文件夹,包含三部分:
| 组成部分 | 说明 | 参考位置 |
|---|---|---|
plugin.json 清单 |
插件的"身份证":id、名称、Go 包路径 | plugins/feed/plugin.json |
| Go 包(编译进二进制) | 导出 Register(deps sdk.Deps) (sdk.Plugin, error) |
plugins/feed/feed.go |
frontend/(可选) |
React 管理界面包,导出名为 plugin 的 FrontendPlugin 对象 |
无内置示例,见文档 |
几个关键特性,先有个印象:
- 📡 独立路由命名空间:每个插件的接口自动挂载在
/api/plugins/{id}/下(管理端路由则挂在/{id}); - 🔓 公开路径:插件可声明无需登录即可访问的精确路径(RSS 就是这样对读者开放的);
- 🗄️ 独立数据库 schema:插件可以拥有自己的表和迁移,互不干扰;
- 🧩 只通过 SDK 接触核心:插件之间永不互相导入,唯一允许的 Gophenberg 依赖是 sdk/ 模块。
Gophenberg 插件架构图
二、环境准备:克隆仓库并启动开发环境
在本地动手之前,先把仓库克隆下来并启动开发环境:
git clone https://gitcode.com/gh_mirrors/go/gophenberg
cd gophenberg
cp .env.example .env
make seed
make seed 会启动 PostgreSQL、执行迁移,并创建一个开发管理员(admin@example.com / password1234)和演示内容。依赖:go.mod 指定的 Go 版本、Node 26 + pnpm、Docker(跑 PostgreSQL)。
然后开两个终端分别启动 API 和管理界面:
make dev
pnpm install && pnpm --filter @gophenberg/frontend dev
API 监听 localhost:8081,管理界面在 localhost:5174。这一步的详细写法见 README.md 的 "Running it locally" 小节。
三、第一步:创建插件目录与 plugin.json 清单
假设我们要写一个名为 hello 的插件,先建目录:
plugins/hello/
├── plugin.json
└── hello.go
然后写入清单文件。对照官方参考插件 plugins/feed/plugin.json:
{
"id": "hello",
"name": "Hello",
"backend": "github.com/gopherium/gophenberg/plugins/hello"
}
各字段的规则:
| 字段 | 规则 |
|---|---|
id |
必填。小写字母、数字和连字符,且以字母开头;必须与目录名一致 |
name |
必填。人类可读的名称 |
backend |
插件 Go 包的导入路径 |
frontend |
可选。管理界面包名(如有) |
两个小提醒(来自 write-a-plugin.md):
backend和frontend至少要有其一;- 一些 id 会被拒绝——比如 Go 关键字(
err、plugins),以及list、check、serve等已被命令行占用的名字。
四、第二步:实现 Register 入口与生命周期
插件的入口是一个 Register 函数,它接收宿主注入的依赖 sdk.Deps,返回一个实现了 sdk.Plugin 接口的值。最小骨架如下(完整版见 plugins/feed/feed.go#L43-L73):
// Register 从依赖构建插件。
func Register(deps sdk.Deps) (sdk.Plugin, error) {
return &Plugin{}, nil
}
// ID 返回插件标识。
func (p *Plugin) ID() string { return "hello" }
// Start 开始服务。
func (p *Plugin) Start(ctx context.Context) error { return nil }
// Stop 结束服务。
func (p *Plugin) Stop(ctx context.Context) error { return nil }
这里有一条重要的生命周期纪律(详见 the-plugin-sdk.md):
Register只做读配置、建对象,不打开连接、不启 goroutine——因为list、check等命令会注册所有插件后又立即停止,但从不启动它们;- 所以
Stop必须保证:即使Start从未运行过也要能正常工作。
SDK 给插件递了哪些"依赖"?
sdk.Deps 的定义在 sdk/sdk.go#L39-L46,各字段用途:
| 字段 | 用途 |
|---|---|
DB |
插件专属的数据库连接池份额(带连接数上限,避免多插件吃光连接) |
DatabaseURL |
PostgreSQL 连接串(SQLite 下为空),供插件自开连接 |
Content |
已发布内容的只读视图,RSS 插件就靠它取文章 |
Accounts |
批量读取账户名称、角色、头像(不含邮箱) |
Env |
读取 GOPHENBERG_ 前缀下的配置项 |
Getenv |
读取任意完整环境变量的兜底方式 |
除必需的 Plugin 接口(ID/Start/Stop)外,还有六个宿主自动发现的可选接口:
| 接口 | 能力 |
|---|---|
RouteProvider(Routes()) |
在 /api/plugins/{id} 下提供 HTTP 端点 |
PublicPathProvider(PublicPaths()) |
声明免登录的精确公开路径 |
Migrator(Migrate()) |
在任何插件启动前执行数据库迁移 |
CommandProvider(Commands()) |
向 gophenberg 命令行注入 <插件id>:<命令> |
TypeDeclarer |
声明插件自带的文章类型、字段组与字段 |
RoleProvider(Roles()) |
声明角色与权限(新权限必须以 <插件id>. 开头) |
五、第三步:以 RSS Feed 为参考,实现路由与公开路径
RSS Feed 插件做了一件事:把已发布的文章变成一条 RSS 订阅源。它的核心实现只有三块,全部在 plugins/feed/feed.go 中:
① 从环境读取配置(feed.go#L43-L58):
settings := deps.Env.Within("FEED_")
title := settings.Value("TITLE") // 读 GOPHENBERG_FEED_TITLE
items, err := settings.Count("ITEMS", 20) // 读 GOPHENBERG_FEED_ITEMS
Env.Within("FEED_") 把前缀收窄为 GOPHENBERG_FEED_,于是 Value("TITLE") 实际读取的就是 GOPHENBERG_FEED_TITLE。配置变量一览见 rss-feed.md:
| 变量 | 默认值 | 作用 |
|---|---|---|
GOPHENBERG_FEED_TITLE |
Gophenberg |
订阅源显示的名称 |
GOPHENBERG_FEED_ITEMS |
20 |
订阅源携带的文章数(必须是正整数,否则启动即报错) |
② 声明公开路径(feed.go#L76-L78):
// PublicPaths 返回免会话访问的路径。
func (p *plugin) PublicPaths() []string {
return []string{feedPath} // "/rss.xml"
}
这是"精确匹配",永不作前缀匹配。正因为如此,订阅源最终能在 https://你的域名/api/plugins/feed/rss.xml 上免登录访问——这就是你该递给 RSS 阅读器或 newsletter 服务的地址。
③ 提供路由(feed.go#L81-L85):
// Routes 返回服务订阅源的处理器。
func (p *plugin) Routes() http.Handler {
mux := http.NewServeMux()
mux.HandleFunc("GET /rss.xml", p.serveFeed)
return mux
}
serveFeed 内部调用 p.posts.ListPublished(ctx, "post", p.items) 从内容域拿到已发布文章(sdk.ContentReader 接口见 sdk/sdk.go#L63-L66),再编码成 RSS 2.0 XML 输出——每个条目带标题、站内链接、完整正文(不是摘要)、urn:uuid: GUID 和 RFC 1123 格式的发布时间(feed.go#L100-L159)。
⚠️ 两点安全细节值得抄作业:
- 插件路由默认要求登录,成功的响应会被标记
private, no-store,所以公开路径上的写操作(来自跨域页面的 POST)会在到达插件前被拒绝; - 因此公开路径上的 GET 绝不能产生副作用。
六、第四步:make generate 一键接线
Gophenberg 的接线是生成式的,不需要手动维护任何"插件列表":
make generate
这个目标(Makefile#L192-L194)会运行生成器 cmd/pluginwire:它读取 plugins/*/plugin.json 的所有清单,重新生成接线文件 cmd/gophenberg/plugins_gen.go。生成后的文件里,每个插件一行注册调用(对照 feed 的实际产物,plugins_gen.go#L17-L27):
feedPlugin, err := feed.Register(deps)
下一次构建时你的插件就被编译进了二进制。CI 会检查生成文件是否过期,过期直接失败——所以改完清单/代码后务必跑一遍 make generate。
七、运行与验证:check、list 与订阅源
接线完成后,按这个顺序验证最稳妥:
gophenberg check # 注册插件、校验配置与命令名,不触碰数据库
gophenberg list # 查看插件清单;注册失败的插件会列在 "Not loaded:" 下
make dev # 启动服务
check 的价值在于:配置写错时它会把问题在上线前拦下来。比如把 GOPHENBERG_FEED_ITEMS 设成 banana,它会打印:
gophenberg: plugin feed: GOPHENBERG_FEED_ITEMS: must be a whole number, got "banana"
最后打开浏览器访问:
http://localhost:8081/api/plugins/feed/rss.xml
看到一条条 <item> 时,恭喜——你手里就是一个和参考插件行为一致的服务了。插件行为本身的单元测试可参考 plugins/feed/feed_test.go:用一个 stubPosts 假实现 ContentReader 接口,配合 httptest 就能完整验证输出,不需要真数据库。
八、进阶:给插件加数据库、命令行与配置
当插件长大时,SDK 已经预留好了三条扩展路径:
1️⃣ 数据库(Migrator + deps.DB)
实现 Migrate(ctx) error,宿主会在任何插件启动前执行它。deps.DB 是每个插件的限额连接份额(默认 4 个槽位,GOPHENBERG_PLUGIN_DB_CONNS 可调),语句用 PostgreSQL 的 $1、$2 占位符;事务与单条语句分别受 GOPHENBERG_PLUGIN_TX_TIMEOUT(30s)和 GOPHENBERG_PLUGIN_QUERY_TIMEOUT(5s)约束。SQLite 模式下该份额当前是关闭的,可用 deps.DB.Engine() 先判断引擎再决定是否使用。
2️⃣ 命令行命令(CommandProvider)
实现 Commands() <a href="https://link.gitcode.com/i/bde5f400b3bbd61f4c64ccbfd15fa1c7" target="_blank">]sdk.Command 后,命令会以 hello:<command> 的形式出现在 gophenberg 命令行中,gophenberg help hello:greet 可看帮助页。sdk.Command 支持参数声明(Args)、自定义 flag(Flags/Needs)、干跑模式(Writes)和权限要求(Capability)。完整字段表见 [the-plugin-sdk.md。
3️⃣ 权限与角色(RoleProvider)
返回 []sdk.RoleDeclaration 即可新增角色或给现有角色加权限。硬性规则:新权限名必须以你的插件 id 加一个点开头(如 notes.manage),保证两个插件永远不会撞车。
九、插件开发常见注意事项清单
- ✅
Register保持"冷启动":不建连接、不读数据库。命令如list会注册后立即停止插件,Stop必须无条件可用; - ✅ id 与目录名保持一致,且避开 Go 关键字和
list、check、serve等保留名; - ✅ 改完清单就跑
make generate,否则 CI 会因接线文件过期而失败; - ✅ 公开路径只放读操作,跨域写请求在到达你之前就会被
request_cross_origin拒绝; - ✅ 输出 HTML 时记得转义:
sdk.Item的Title、Excerpt按原样返回,只有Content经过了核心同款过滤; - ✅ SQLite 下先查
deps.DB.Engine():插件数据库份额与部分内容读取在 SQLite 上尚未开放; - ⚖️ 一条诚实的边界:编译进二进制不等于沙箱——
deps.DB和DatabaseURL通向核心同一个库。你编译什么进去,就是信任什么进去。
十、延伸阅读与源码速查
| 资料 | 路径 |
|---|---|
| 编写插件(官方教程) | write-a-plugin.md |
| 插件 SDK 全览 | the-plugin-sdk.md |
| 声明文章类型 | declare-content.md |
| RSS Feed 配置参考 | rss-feed.md |
| 参考插件源码 | plugins/feed/feed.go、plugins/feed/plugin.json |
| SDK 契约源码 | sdk/sdk.go、sdk/env.go、sdk/db.go |
| 接线生成器 | cmd/pluginwire/main.go、Makefile |
| 本地开发指南 | local-development.md |
Gophenberg 的 SDK 是独立 Go module(github.com/gopherium/gophenberg/sdk),如果你的插件放在另一个仓库,只需 go get 这一个模块,永远不要依赖 Gophenberg 整体——SDK 只引用自己的类型和标准库,核心依赖升级不会改变你的编译契约。
从 hello 到 feed,你只需要再走一步:给你的插件加上第一个真实功能。参考插件的全部"武功"都在 plugins/feed 里,拆开来读,不过 160 行。