EmDash 插件开发指南：Taxonomies 与 Redirects 能力接入与安全边界

EmDash 插件开发指南Taxonomies 与 Redirects 能力接入与安全边界【免费下载链接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress项目地址: https://gitcode.com/gh_mirrors/emdas/emdash导读本文聚焦 EmDash CMS 插件系统中两个常被忽视却至关重要的宿主能力分类法Taxonomies与重定向Redirects。通过taxonomies:read/taxonomies:write与redirects:read/redirects:write四组能力声明插件可以读取分类定义、术语与条目归类创建术语、增量调整条目归类以及分页读取、版本化创建/更新/删除重定向规则。读完本文你将掌握两组能力的授权模型、API 形态、宿主校验规则、版本冲突CONFLICT处理以及针对生产边界production boundary的运行时测试方法并能在自己的插件中正确、安全地声明与使用它们。本文的完整背景可参考 创建 EmDash 插件技能说明其中能力矩阵表列出了taxonomies:read、taxonomies:write、redirects:read、redirects:write的授予范围。一、能力模型读、写与最小权限EmDash 插件通过emdash-plugin.jsonc清单声明能力capability。与内容、媒体、评论等 API 一样分类法与重定向遵循读能力为基础、写能力隐含读的授权模型能力授予范围隐含关系taxonomies:read暴露分类法定义definitions、术语terms与条目归类entry assignments无taxonomies:write在 read 之上增加createTerm()、addEntryTerms()、removeEntryTerms()隐含taxonomies:readredirects:read暴露游标分页列表与版本化读取无redirects:write在 read 之上增加创建、更新、删除隐含redirects:read能力字符串在插件清单 Schema 中显式枚举插件清单 Schema 中收录了taxonomies:read、taxonomies:write、redirects:read、redirects:write四个合法值。能力声明之后宿主才会在插件上下文中装配对应的访问接口其装配逻辑位于 插件上下文实现先判断taxonomies:write则注入可写访问器否则判断taxonomies:read注入只读访问器重定向同理redirects:write优先于redirects:read。若两者都未声明ctx.taxonomies与ctx.redirects直接为undefined任何访问都会在运行时失败。能力测试也验证了这一门控集成测试 capabilities.test.ts 断言只声明taxonomies:read的插件能拿到ctx.taxonomies而只有content:read的插件拿不到L634-L645 进一步断言只读插件上的createTerm为undefined只有声明taxonomies:write的插件才暴露该函数。1.1 权限声明的操作示范在插件清单中声明以 JSONC 格式{ id: my-taxonomy-and-redirect-plugin, name: My Taxonomy Redirect Plugin, capabilities: [ taxonomies:read, taxonomies:write, redirects:read, redirects:write ] }需要特别提醒能力即信任契约。增加能力尤其是写能力需要管理员重新审批因此应坚持最小权限原则——只声明当前插件实际用到的能力。分类法读能力与重定向写能力之间没有依赖关系可以单独声明。二、Taxonomies 访问接口与宿主校验2.1 只读接口taxonomies:readctx.taxonomies在声明taxonomies:read后可用接口定义见 插件类型声明方法签名说明getAll(options?: { locale?: string })列出分类法定义名称、标签、是否层级、挂载的集合、localegetTerms(taxonomy, options?)返回某分类法的全部术语按标签排序getEntryTerms(collection, entryId, options?)返回条目已归类的术语可用taxonomy参数缩小范围读操作都接受可选的locale过滤参数省略locale时返回所有 locale 的行见 TaxonomyReadOptions 注释。返回的术语为扁平结构层级分类法通过parentId重建树形——parentId存的是父术语的 locale 无关translationGroup而非父术语自身 ID见 TaxonomyTermInfo 注释。只读访问器在 context.ts 中实现getAll直接查询_emdash_taxonomy_defs表并做 locale 过滤getTerms通过TaxonomyRepository.findByName读取getEntryTerms委托getTermsForEntry按集合、条目与可选分类法过滤。2.2 写接口taxonomies:write声明taxonomies:write后在只读接口之上追加三个写方法见 TaxonomyAccessWithWrite方法签名行为createTerm(taxonomy, input)新建术语input含label、可选slug、parentId、description、locale、translationOfaddEntryTerms(collection, entryId, taxonomy, termIds[])为条目增量添加术语归类removeEntryTerms(collection, entryId, taxonomy, termIds[])为条目增量移除术语归类三个方法对应实现见 context.tscreateTerm调用handleTermCreate处理器addEntryTerms与removeEntryTerms先经resolveTaxonomyDelta校验再分别调用attachGroupsToEntry与detachGroupsFromEntry最后读取解析后的最新归类返回。2.3 关键设计一以 ID 而非 slug 寻址术语赋值方法接收的是术语行 ID 或翻译组 IDtranslation-group ID不是 slug。这一点是插件开发中最容易踩的坑。原因在于多语言场景下同一概念在不同 locale 有不同 slug而归类必须锚定到跨语言的翻译身份上。实现中resolveTaxonomyDelta对每个 term ID 调用repo.findByIdOrTranslationGroup(id)解析成功后统一以term.translationGroup ?? term.id作为归类的目标组见 context.ts。桥接层测试 bridge-taxonomy.test.ts 也展示了从插件侧透传术语 ID 的完整链路addEntryTerms(posts, post-1, category, [term-2])。2.4 关键设计二幂等增量而非整体替换添加与移除操作应用的是幂等增量idempotent deltas而不是替换完整集合。也就是说addEntryTerms只把指定的术语组加入条目不会清掉条目上已有的其他归类removeEntryTerms只移除指定术语组。因此并发插件各自添加自己的术语时互不覆盖这是delta语义带来的并发安全特性。增量上限为 64 个术语 ID超出抛VALIDATION_ERROR见 MAX_TAXONOMY_DELTA_TERMS 与 resolveTaxonomyDelta 校验。2.5 宿主校验矩阵宿主会对每一次分类法访问做严格校验覆盖以下维度校验维度说明失败错误码分类法存在性目标 taxonomy 必须存在于_emdash_taxonomy_defsNOT_FOUND集合挂载关系分类法必须挂载到目标 collectioncreateTerm之外的操作同样受检VALIDATION_ERROR条目存在性目标内容条目必须存在NOT_FOUND术语归属术语必须属于同一分类法跨分类法术语被拒绝VALIDATION_ERROR配置的 locale归类写入遵循条目的 locale回退到默认 locale—翻译身份术语 ID 需解析为翻译组身份见 2.3NOT_FOUND层级合法性createTerm()对扁平分类法传入parent会被拒绝见下校验代码位于 resolveTaxonomyDelta依次检查 delta 大小上限、术语 ID 非空、分类法存在、分类法挂载了目标集合、条目存在再逐个解析术语并确认其属于该分类法。集成测试 capabilities.test.ts 覆盖了创建术语并拒绝跨分类法父级、分类法未挂载集合时拒绝赋值等场景。createTerm()拒绝为扁平分类法指定父术语——只有hierarchical: true的分类法才允许parentId。这也是扁平形状数据模型的直接后果。2.6 能力边界哪些操作不可用从类型定义可以明确看到能力边界定义管理、挂载关系变更、赋值整体替换、术语更新、术语删除均不可用。插件只能创建术语并对条目做增量归类分类法本身的增删改、挂载集合的调整、以及术语的改名/删除都属于宿主管辖插件无权触碰。这是为了把分类法的结构主权保留给站点管理员避免插件误操作破坏全局分类体系。三、Redirects 访问接口与版本化语义3.1 只读接口redirects:readctx.redirects在声明redirects:read后可用接口定义见 RedirectAccess方法签名说明list(options?)游标分页列出重定向支持limit、cursor、search、group、enabled、auto过滤get(id)读取单条重定向的版本化快照返回{ redirect, _rev }列表接口通过宿主处理器handleRedirectList执行分页返回{ items, cursor, hasMore }结构见 context.ts。每条重定向记录包含source、destination、type301/302/307/308/410/451、isPattern、enabled、hits、lastHitAt、groupName、auto标记及时间戳见 RedirectInfo。3.2 写接口redirects:write声明redirects:write后追加三个写方法见 RedirectAccessWithWrite方法签名说明create(input)创建重定向input含source、可选destination、type、enabled、groupNameupdate(id, input { _rev })更新重定向必须携带原_revdelete(id, { _rev })删除重定向必须携带原_rev3.3 关键设计不透明修订号_rev与 CONFLICT更新与删除时必须原样传回读取时获得的_rev不透明修订号不可自行构造或猜测。修订号实际上是一个带前缀的编码载荷encodeRedirectRevision把重定向 ID 与数据库中的configRevision更新时间戳拼接后做 URL-safe Base64 编码前缀为r1.decodeRedirectRevision解码并校验其格式与归属见 context.ts。版本语义带来经典的乐观并发控制如果重定向在你读取之后被其他人修改你携带的_rev对应的修订号与当前记录不一致宿主编译时返回CONFLICT。正确的处理姿势是捕获CONFLICT错误重新读取该重定向get(id)获取最新_rev用新_rev重试更新或删除。集成测试 capabilities.test.ts 验证了这一点同一_rev连续两次更新第二次返回reason.code CONFLICT。get返回的版本化快照是读取时的一次性数据库快照保证redirect字段与_rev来自同一版本见测试 L924。3.4 宿主校验矩阵重定向写操作全部经过宿主校验见 重定向处理器 与 RedirectAccess 的实现校验维度说明源模式校验若source形如模式pattern执行validatePattern非法模式返回VALIDATION_ERROR目标参数校验若源为模式校验destination引用的参数必须来自源模式中的合法参数validateDestinationParams重复源校验精确匹配的源已存在时返回CONFLICT排除自身的更新除外状态码校验type必须属于301 \| 302 \| 307 \| 308 \| 410 \| 451由请求体 Schema 约束环路校验通过wouldCreateLoop检查新规则是否在重定向链中形成环宿主字段保护插件输入不得包含宿主自有字段模式相关校验代码位于 redirects.ts源看起来像模式时先校验模式合法性再校验目标参数引用非模式源做精确查重随后用wouldCreateLoop检查环路。3.5 宿主字段保护auto标记不可写入重定向记录中的auto字段标记自动生成的规则由宿主管理插件输入无法设置。assertNoAutomaticRedirectMarker会检查输入对象是否含有auto键有则直接抛VALIDATION_ERROR错误消息为 The automatic redirect marker is managed by EmDash见 context.ts。创建与更新路径都会先调用该断言见 L580、L595。3.6 责任边界请求写能力前的思考重定向规则直接决定访客被送往哪里因此只有当插件确实拥有该行为时才应请求redirects:write。改变重定向可能影响 SEO、外链与用户可达性属于高风险行为。这与 EmDash 插件系统的整体能力即信任契约理念一致声明的每项能力都应在审批时有充分理由写能力尤其如此。四、运行时测试验证生产边界重定向与分类法写入都影响站点全局状态因此测试不应停留在单元层面而应覆盖生产边界production boundary——即插件真实经过的 route/action 边界。4.1 测试策略要点用 fixtures 建立重定向状态不触发 hooks运行时夹具runtime fixtures直接建立状态而不会触发内容钩子见 SKILL.md 中的 Runtime fixtures 说明通过真实的 route/action 边界调用插件使用createPluginRuntimeTestHost()它才能真正执行内容动作、插件激活、媒体、评论、重定向、调度等行为见 SKILL.md检查持久化的规则断言操作后数据库中的重定向规则符合预期而非仅检查返回值覆盖关键失败路径与重定向相关的测试应覆盖陈旧修订stale revision与环路/目标校验失败场景。桥接层测试是很好的参照Cloudflare Worker 侧的 bridge-taxonomy.test.ts 通过 mock 的createTerm/addEntryTerms/removeEntryTerms验证沙箱桥接对分类法调用的透传bridge-redirect.test.ts 验证重定向访问在沙箱边界的封装。这些测试展示了从插件调用到宿主边界的完整链路可作为运行时测试的模板。4.2 一个可参考的冲突处理测试骨架// 伪代码骨架展示 CONFLICT → 重读 → 重试 的模式 const created await access.create({ source: /old-path, destination: /new-path }); // 第一次更新成功 await access.update(created.redirect.id, { destination: /winner-a, _rev: created._rev, }); // 复用同一 _rev 再次更新 → 预期 CONFLICT await expect( access.update(created.redirect.id, { destination: /winner-b, _rev: created._rev }), ).rejects.toMatchObject({ reason: expect.objectContaining({ code: CONFLICT }) });该骨架对应的真实测试见 capabilities.test.ts。实践中重读再重试的逻辑通常封装在一个带有限次重试的辅助函数里避免业务代码散落冲突处理。五、实战小结接入清单检查项要点依据能力声明按需声明taxonomies:read/write、redirects:read/writemanifest schema术语寻址用术语 ID/翻译组 ID不用 slugcontext.ts归类语义增量 delta非整体替换上限 64 个 IDcontext.ts重定向写操作更新/删除必须回传_rev冲突时重读重试context.ts宿主校验源模式、目标参数、查重、状态码、环路校验redirects.ts宿主字段保护不可写auto自动规则标记context.ts能力边界分类法结构管理定义/挂载/术语更新删除不可用types.ts测试策略fixtures 建状态 真实边界调用 检查持久化结果 覆盖 CONFLICT/环路SKILL.md六、进一步阅读创建 EmDash 插件总览能力矩阵、沙箱格式选择、脚手架与测试总纲Taxonomies 与 Redirects 参考原文档本文对应的原始精简参考插件上下文实现两大访问器的装配与校验落地插件类型声明全部接口、输入输出类型的权威定义重定向处理器模式校验、查重与环路检测实现能力集成测试能力门控、分类法校验、重定向版本冲突的真实用例沙箱桥接测试分类法调用跨沙箱边界的透传验证【免费下载链接】emdashEmDash is a full-stack TypeScript CMS based on Astro; the spiritual successor to WordPress项目地址: https://gitcode.com/gh_mirrors/emdas/emdash创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考