enonic-guillotine-query-builder

Enonic Guillotine 查询构建器

操作步骤

步骤 1：扫描工作区，查找现有的 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. 如果两种风格并存，请标记已弃用的用法，以便迁移。

步骤 2：加载 Guillotine API 参考

1. 在编写任何查询之前，阅读 references/guillotine-reference.md。
2. 如果工作区面向多个 Guillotine 版本，或需要在这些版本之间迁移，请阅读 references/compatibility.md。

步骤 3：确定查询结构

1. 确定用户需要的操作：
   • 获取单个内容：使用 get(key)。
   • 直接子项：使用 getChildren(key)；需要分页时使用 getChildrenConnection(key)。
   • 筛选搜索：使用 queryDsl(query) 获取平面列表；需要分页、聚合或高亮时使用 queryDslConnection(query)。
   • 内容类型元数据：使用 getType(name) 或 getTypes。
2. 如果需要分页，优先使用连接变体（queryDslConnection、getChildrenConnection），并指导调用方传入 after / first。
3. 如果需要聚合或高亮，则必须使用 queryDslConnection——queryDsl 不支持这些功能。

步骤 4：构造内容类型片段

1. 根据内容类型描述符推导 GraphQL 类型名称：将点号（.）和冒号（:）替换为下划线（_），并删除连字符（-），同时将连字符后面的字母大写。冒号后每个部分的首字母都要大写。例如：com.enonic.app.myapp:BlogPost → com_enonic_app_myapp_BlogPost。对于内置类型：portal:template-folder → portal_TemplateFolder。
2. 使用内联片段访问类型专属的 data 字段：... on <GraphQLTypeName> { data { ... } }。
3. 对于内容引用（ContentSelector、ImageSelector、MediaSelector），请在引用后使用目标类型上的嵌套内联片段。
4. 对于 RichText / HtmlArea 字段，请包含 processedHtml，并可选择包含 links、images、macros 子字段。需要绝对 URL、srcset 宽度（imageWidths）或响应式尺寸（imageSizes）时，请使用 processHtml 输入参数。

步骤 5：构建查询筛选条件和排序

1. 使用 Query DSL 输入类型。每个 QueryDSLInput 必须恰好包含一个表达式字段。
2. 使用 boolean 及其 must、should、mustNot 和 filter 数组组合多个条件。
3. 对日期或数值范围，使用 range 表达式，以及 gt / gte / lt / lte 和正确的 DSLExpressionValueInput 类型（localDate、localDateTime、instant、long、double）。
4. 排序时，使用包含 field 和 direction（ASC / DESC）的 SortDslInput。
5. 如果查询模式与文档化示例相符，请阅读 references/examples.md。

步骤 6：按需添加聚合和高亮

1. 在 queryDslConnection 上，将 aggregations 作为 AggregationInput 对象数组传入。
2. 每个聚合都必须有唯一的 name，并且恰好包含一个聚合类型字段（terms、dateRange、stats 等）。
3. 需要高亮时，传入 highlight，并使用 properties 数组为每个需要高亮的字段指定 propertyName。
4. 从连接结果的 aggregationsAsJson 和 highlightAsJson 中读取聚合和高亮结果。 步骤 7：生成 TypeScript 类型（如有要求）
5. 读取 assets/guillotine-query.template.ts，将其用作起始模板。
6. 将 __APP_KEY__、__CONTENT_TYPE__、__GRAPHQL_TYPE__ 和 __FIELDS__ 占位符替换为实际的内容类型值。
7. 在 Data 接口中添加类型化字段，使其与查询中请求的内容类型架构字段相匹配。
8. 对于连接查询，使用 ContentConnection<T> 泛型，并指定具体的内容类型。

步骤 8：设置站点上下文（如适用）

1. 如果查询针对特定站点，请在 guillotine 字段上设置 siteKey，或指示调用方设置 X-Guillotine-SiteKey HTTP 标头。
2. 对于相对于站点的查询，在路径参数中使用 ${site} 占位符。
3. 使用 _path(type: siteRelative) 返回相对于站点的路径。

步骤 9：验证查询

1. 验证所有内联片段类型名称都使用下划线，而非原始描述符格式。
2. 确认使用的是 queryDsl / queryDslConnection，而不是已弃用的 query / queryConnection。
3. 确保 QueryDSLInput 对象恰好包含一个表达式字段。
4. 验证 DSLExpressionValueInput 对象恰好包含一个值类型字段。
5. 检查聚合和高亮仅用于连接变体。
6. 对于 Guillotine 7+ 项目，验证 pageUrl / mediaUrl / imageUrl / attachmentUrl 的 params 参数使用 Json 类型，而非 String。
7. 如果查询返回意外的空值、空结果或类型错误，请阅读 references/troubleshooting.md。

错误处理

• 如果 get 返回 null，请验证该键是否为有效的内容路径或 ID，以及目标分支是否正确（draft 或 master）。
• 如果内联片段字段为 null，请确认 GraphQL 类型名称使用下划线，且与内容类型描述符完全匹配。
• 如果 queryDsl 返回空结果，请先简化为 matchAll: {}，以确认数据存在，再逐个重新添加筛选条件。
• 如果聚合或高亮结果为 null，请验证查询使用的是 queryDslConnection，而非 queryDsl。
• 如果使用了已弃用的 query 字段，请阅读 references/compatibility.md，了解如何迁移到使用 DSL 语法的 queryDsl。
• 如果 scripts/find-guillotine-targets.mjs 无法运行，请手动扫描工作区以查找 Guillotine 标记，然后继续。