查詢註冊表 | EmDash CMS Everything

這是一個進階主題，用於針對外掛註冊表建構您自己的軟體。如果您只想在 EmDash 站點上安裝外掛，則不需要這些——在設定中啟用註冊表並使用管理儀表板即可。

註冊表的發現端是一個公開的唯讀 API。@emdash-cms/registry-client 套件對其進行封裝，這樣您就可以在 EmDash 之外建構外掛目錄、搜尋頁面或發佈訂閱源。客戶端可在任何 fetch 可用的地方執行——Node、Workers、瀏覽器或 Astro 站點。

安裝

discovery 子路徑沒有認證或 OAuth 依賴。安裝客戶端並固定到確切版本：

npm install @emdash-cms/[email protected]

列出和解析套件

以下 Astro 頁面列出註冊表中的所有外掛：

---
import { DiscoveryClient } from "@emdash-cms/registry-client/discovery";

const discovery = new DiscoveryClient({
  aggregatorUrl: "https://registry.emdashcms.com",
});

const { packages } = await discovery.searchPackages({ q: "", limit: 50 });
---

<ul>
  {
    packages.map((pkg) => (
      <li>
        <a href={`/plugins/${pkg.did}/${pkg.slug}`}>
          {pkg.profile?.name ?? pkg.slug}
        </a>
        {pkg.latestVersion && <span>v{pkg.latestVersion}</span>}
        <p>{pkg.profile?.description}</p>
      </li>
    ))
  }
</ul>

連結使用始終存在的 pkg.did。發佈者 handle 是盡力而為的，可能不存在，因此不要從中建構 URL。

套件詳情頁透過 DID 和 slug 取得外掛，然後取得最新發佈：

import { DiscoveryClient } from "@emdash-cms/registry-client/discovery";

const discovery = new DiscoveryClient({
  aggregatorUrl: "https://registry.emdashcms.com",
});

export async function getPlugin(did: string, slug: string) {
  const pkg = await discovery.getPackage({ did, slug });
  const latest = await discovery.getLatestRelease({
    did: pkg.did,
    package: pkg.slug,
  });
  return { pkg, latest };
}

發現方法

客戶端為每個聚合器查詢公開一個方法：

searchPackages({ q, capability?, limit?, cursor? }) — 自由文字搜尋，可選擇過濾到宣告了給定存取類別的套件。回傳 { packages, cursor? }。
resolvePackage({ handle, slug }) — 透過 handle 和 slug 解析套件。
getPackage({ did, slug }) — 透過 DID 和 slug 取得套件。
listReleases({ did, package, limit?, cursor? }) — 套件的所有發佈，最新版本優先。
getLatestRelease({ did, package }) — 未撤回的最高發佈版本。

處理不可信記錄

聚合器是一個不可信的索引，它轉發不是自己撰寫的記錄，因此客戶端在邊界處驗證每一條記錄。由此產生兩條規則：

profile 和 release 欄位可以是 null。 當轉發的記錄驗證失敗時，客戶端將其呈現為 null 而不是讓整個呼叫失敗，這樣一條格式錯誤的記錄不會清空搜尋頁面。在讀取 pkg.profile?.name 或 latest.release?.artifacts.package 之前始終進行空值檢查。
在渲染之前自行驗證 URL 方案。 驗證檢查結構，而不是 URL 安全性——uri 欄位可以攜帶 javascript: 方案。在將註冊表提供的任何 URL 放入 href 或 src 之前，套用您自己的 http/https 許可清單。

非 2xx 回應會拋出 ClientResponseError（從套件中重新匯出），包含 .error、.description、.status 和 .headers。

按主機相容性過濾

發佈可以在其 requires 區塊中宣告環境要求（EmDash 或 Astro 版本範圍）。@emdash-cms/registry-client/env 子路徑對其進行評估，這樣目錄可以標記不會在給定主機上執行的發佈：

import { checkEnvCompatibility, hostEnvFromVersions } from "@emdash-cms/registry-client/env";
import type { ValidatedReleaseView } from "@emdash-cms/registry-client/discovery";

const host = hostEnvFromVersions("0.17.0", "5.6.0");

// 傳入 getLatestRelease() 結果。當發佈在此主機上執行時，
// 回傳的陣列為空。
export function envMismatches(latest: ValidatedReleaseView) {
  return checkEnvCompatibility(latest.release?.requires, host);
}

接下來閱讀

外掛註冊表 — 在 EmDash 站點上啟用和使用註冊表
打包和發佈 — 將外掛發佈到註冊表