README

此模块为使用 Silverstripe CMS 构建无头网站提供了几个核心功能。虽然它主要用于支持 silverstripe/silverstripe-nextjs 模块，但它不依赖于任何框架，可以作为任何无头解决方案的平台。

安装

此模块需要 Silverstripe/graphql 版本 4 的预发布版。请参阅使用 silverstripe/recipe-cms 稳定版本中版本 4 的安装说明。

安装 silverstripe/graphql:^4 后，您可以使用标准的 composer 安装添加此模块。

composer require silverstripe/silverstripe-headless

功能

将模型批量加载到模式中，例如 MyApp\Models\*
为所有数据对象添加了几个辅助字段（例如 hashID、typeAncestry、exists 等）
网络钩子（入站和出站）
发布状态（等待发布/发布历史）
API 密钥身份验证（参见 sminnee/silverstripe-apikey）
所有 ContentController 请求 404（例如没有前端）
基本 URL 重定向到 /admin
数据对象更改跟踪，以提供将发布的透明度

入门

您首先需要决定您想要公开给内容 API 的模型。这是通过允许列表而不是排除列表完成的。您可以使用通配符命名空间来简化此过程。

要包含模型，请更新 SilverStripe\Headless\GraphQL\ModelLoader 上的配置。以下为默认配置

SilverStripe\Headless\GraphQL\ModelLoader:
  included_dataobjects:
    page: 'Page'
    cms: 'SilverStripe\CMS\Model\SiteTree'
    siteconfig: 'SilverStripe\SiteConfig\*'
    assets: 'SilverStripe\Assets\*'
    elemental: 'DNADesign\Elemental\Models\*'

在您的项目中包含类似的配置。

app/_config/modelLoader.yml

SilverStripe\Headless\GraphQL\ModelLoader:
  included_dataobjects:
    - MyApp\Models\*
    - SomeModule\Models\SomeModel
    # etc...

需要帮助生成此列表？请使用配置生成工具。

决定包含哪些模型以及排除哪些模型可能会相当具体，尤其是在您安装了多个模块的情况下。为了生成此列表，请使用浏览器并导航到 /dev/generate-included-classes。

这是一个简单的用户界面，但它将为您提供系统中的每个数据对象类的复选框，并为您生成相应的配置。

访问 GraphQL API

API 应已配置在 /graphql 上，并为每个公开的数据对象提供 read 和 readOne 操作。使用 silverstripe/graphql-devtools 提供的 GraphQL IDE 浏览 API 并尝试一些查询。

其他功能

额外的数据对象字段

hashID: String!：整个数据库中的唯一 ID。基于 ID / baseClass 对。
typeAncestry: [[String]]：此模型的所有祖先类型的列表。例如 [BlogPage, Page, SiteTree]
exists: Boolean!：在渲染或隐藏 UI 时很有用 -- 检查模型的 exists() 函数是否返回 true。

网络钩子

网络钩子是使无头设置正常工作的关键部分。这是 CMS 与无头实例（例如 Netlify、Vercel）通信的主要方式。

入站网络钩子

默认情况下，提供了三个入站网络钩子 -- 分别针对每个部署事件：DEPLOY_START | DEPLOY_FAILURE | DEPLOY_SUCCESS。

出站网络钩子

您需要定义最重要的出站webhook是“发布”webhook，当在“待发布”视图中点击“发布”按钮时，该webhook将被触发。

“发布”钩子具体有两种行为相关联

OPTIMISTIC：标记内容已发布，并无需等待托管提供商的确认。如果您的托管提供商不提供出站webhook，这可能有必要，但不推荐，因为发布可能会因多种原因而失败。
DEFER：将内容标记为“待发布”，并在接收到传入的webhook，例如DEPLOY_SUCCESS后，再将其标记为已发布。Netlify为所有网站提供免费出站webhook。见下文。

您可以通过点击“调用webhook”来测试webhook。如果收到200响应，您将获得绿色状态消息。

验证传入请求（仅限Netlify）

Netlify允许您通过其出站webhook调用发送带有JWT签名的消息。如果您使用Netlify，利用此功能以最小化CMS实例的攻击面是一个好主意。

您需要做的就是定义一个任意的密钥在NETLIFY_JWS_SECRET环境变量中（例如一个随机的64字符字符串），并将此密钥提供给Netlify中定义的出站webhook。当它触发出站webhook事件时，Silverstripe将检查请求上的签名以验证真实性。

发布内容

发布是一个手动过程。对托管提供商的发布不是在每次对数据库的发布上触发的。假设内容变化可以快速发生，并且许多是瞬时的（例如，匆忙中纠正错误），而且持续的内容部署并不总是非常适合，尽管这个特性考虑到了未来。

随着CMS中的变化，内容变化将被跟踪。任何暴露给您的API的DataObjects更改都将记录在“待发布”管理界面中，您可以在那里发布它们。

一旦更改发布，它们将被添加到“发布历史”视图中。

API密钥认证

所有成员都可以生成API密钥。请参阅每个成员详情视图中的“API密钥”选项卡。通过在graphql请求中传递此密钥并在X-API-Key头中认证，将认证为与该密钥关联的成员。这对于读取草稿或其他受保护的内容很有用。

进一步阅读

请参阅silverstripe/silverstripe-nextjs模块，以了解更多此模块提供的功能实现。

silverstripe / silverstripe-headless

维护者

详细信息