用 Gophenberg 编写第一个 Go 插件:以 RSS Feed 为参考的实战教程

原创2026-11-03 13:59:541,847 阅读

用 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):

  1. backend 和 frontend 至少要有其一;
  2. 一些 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 行。

登录后查看全文
gophenberg