在 Enonic XP 中用 Guillotine…

适用于为 Enonic XP 无头内容交付编写或排查 Guillotine GraphQL 查询、通过 GraphQL 查询自定义内容类型、以及从 Guillotine 响应生成类型化接口。

适用场景

解决思路

1. 执行 `node scripts/find-guillotine-targets.mjs .` 扫描工作区，清点包含 Guillotine 标记（查询字符串、库导入、端点引用）的文件。
2. 若没有 Node 运行时，手动在 `.ts`、`.js`、`.graphql`、`.gql` 文件中搜索 `guillotine`、`queryDsl`、`queryDslConnection` 或 `/lib/guillotine`。
3. 确认所用 Guillotine 版本：若发现 `query(query: "...")` 字符串字段，说明项目使用已弃用的 5.x 风格 API；若发现 `queryDsl` / `queryDslConnection`，说明使用 6.x+ DSL；检查 `guillotine/guillotine.js` 中的 `exports.extensions` 以检测 Guillotine 7 Extensions API。
4. 若两种风格并存，标记已弃用用法以便迁移。
5. 在编写任何查询前阅读 `references/guillotine-reference.md`。
6. 当工作区目标或迁移涉及 Guillotine 版本时，阅读 `references/compatibility.md`。
7. 确定查询形态：单条内容获取用 `get(key)`；直接子项用 `getChildren(key)`，分页用 `getChildrenConnection(key)`；过滤搜索用 `queryDsl(query)` 获取扁平列表，或用 `queryDslConnection(query)` 获取分页、聚合或高亮；内容类型元数据用 `getType(name)` 或 `getTypes`。
8. 若需要分页，优先使用 connection 变体（`queryDslConnection`、`getChildrenConnection`），并引导调用方传入 `after` / `first`。
9. 若需要聚合或高亮，必须使用 `queryDslConnection`——这些功能在 `queryDsl` 上不可用。
10. 从内容类型描述符推导 GraphQL 类型名：将点（`.`）和冒号（`:`）替换为下划线（`_`），移除连字符（`-`）并将后一个字母大写，冒号后每段首字母大写。例如 `com.enonic.app.myapp:BlogPost` → `com_enonic_app_myapp_BlogPost`；内置类型 `portal:template-folder` → `portal_TemplateFolder`。
11. 使用内联片段访问类型特有的 `data` 字段：`... on <GraphQLTypeName> { data { ... } }`。
12. 对于内容引用（ContentSelector、ImageSelector、MediaSelector），在引用后跟一个针对目标类型的嵌套内联片段。
13. 对于 RichText / HtmlArea 字段，包含 `processedHtml`，可选包含 `links`、`images`、`macros` 子字段；使用 `processHtml` 输入参数设置绝对 URL、srcset 宽度（`imageWidths`）或响应式尺寸（`imageSizes`）。
14. 使用 Query DSL 输入类型；每个 `QueryDSLInput` 必须恰好包含一个表达式字段。
15. 使用 `boolean` 的 `must`、`should`、`mustNot`、`filter` 数组组合多个条件。
16. 对于日期或数值范围，使用 `range` 表达式配合 `gt`/`gte`/`lt`/`lte` 以及正确的 `DSLExpressionValueInput` 类型（`localDate`、`localDateTime`、`instant`、`long`、`double`）。
17. 排序使用 `SortDslInput`，指定 `field` 和 `direction`（`ASC` / `DESC`）。
18. 当查询模式匹配文档示例时，阅读 `references/examples.md`。
19. 如需聚合，在 `queryDslConnection` 上传入 `aggregations` 数组，元素为 `AggregationInput` 对象。
20. 每个聚合需要唯一的 `name` 且恰好一个聚合类型字段（`terms`、`dateRange`、`stats` 等）。
21. 如需高亮，传入 `highlight`，其 `properties` 数组为每个要高亮的字段指定 `propertyName`。
22. 从连接结果的 `aggregationsAsJson` 和 `highlightAsJson` 读取聚合和高亮结果。
23. 如需生成 TypeScript 类型，先阅读 `assets/guillotine-query.template.ts` 作为起始模板。
24. 将 `__APP_KEY__`、`__CONTENT_TYPE__`、`__GRAPHQL_TYPE__`、`__FIELDS__` 占位符替换为实际内容类型值。
25. 向 `Data` 接口添加与查询中请求的内容类型 schema 字段匹配的类型化字段。
26. 对于连接查询，使用 `ContentConnection<T>` 泛型并指定具体内容类型。
27. 若查询针对特定站点，在 `guillotine` 字段上设置 `siteKey`，或指示调用方设置 `X-Guillotine-SiteKey` HTTP 头。
28. 在路径参数中使用 `${site}` 占位符进行站点相对查询。
29. 使用 `_path(type: siteRelative)` 返回站点相对路径。
30. 验证所有内联片段类型名使用下划线而非原始描述符格式。
31. 确认使用 `queryDsl` / `queryDslConnection` 而非已弃用的 `query` / `queryConnection`。
32. 确保 `QueryDSLInput` 对象恰好包含一个表达式字段。
33. 验证 `DSLExpressionValueInput` 对象恰好包含一个值类型字段。
34. 检查聚合和高亮仅用于 connection 变体。
35. 对于 Guillotine 7+ 项目，验证 `pageUrl` / `mediaUrl` / `imageUrl` / `attachmentUrl` 的 `params` 参数使用 `Json` 类型而非 `String`。
36. 若查询返回意外 null、空结果或类型错误，阅读 `references/troubleshooting.md`。
37. 若 `get` 返回 null，验证 key 是有效的内容路径或 ID，且目标分支（draft 与 master）正确。
38. 若内联片段字段为 null，确认 GraphQL 类型名使用下划线且与内容类型描述符完全匹配。
39. 若 `queryDsl` 返回空结果，简化为 `matchAll: {}` 确认数据存在，然后逐个重新添加过滤器。
40. 若聚合或高亮结果为 null，验证查询使用 `queryDslConnection` 而非 `queryDsl`。
41. 若使用了已弃用的 `query` 字段，阅读 `references/compatibility.md` 迁移到使用 DSL 语法的 `queryDsl`。
42. 若 `scripts/find-guillotine-targets.mjs` 无法运行，手动扫描工作区中的 Guillotine 标记并继续。

适用边界 · 注意事项

• 不适用于内容类型 XML 定义。
• 不适用于非 Enonic 的 GraphQL API（Apollo、Hasura）。
• 不适用于服务端 lib-content 查询，也不适用于 Guillotine 部署和 CORS 配置。