AWS Amplify JS 中 GraphQL 查询过滤条件的类型匹配问题解析

问题背景

在使用 AWS Amplify JS 的 GraphQL API 时，开发者可能会遇到一个关于查询过滤条件的类型匹配问题。这个问题主要出现在使用 secondaryIndex（二级索引）进行查询时，当尝试对 sortKey（排序键）应用特定过滤条件时，系统会抛出"TypeError: Cannot convert null value to object"的错误。

问题现象

开发者在使用 Amplify Gen 2 版本时，定义了一个 Post 模型，其中包含一个名为"unreadPostsReceived"的二级索引，该索引以 receiverId 作为分区键，reactionTimestamp 作为排序键。当尝试查询未读帖子时，开发者希望筛选出 reactionTimestamp 字段不存在的记录。

开发者最初尝试使用以下查询方式：

const response = await client.models.Post.listPostsByReceiverId({
  receiverId: currentUser.userId,
  reactionTimestamp: { attributeExists: false } // 抛出类型错误
})

这种方式会导致系统报错。而改为以下方式则可以正常工作：

const response = await client.models.Post.listPostsByReceiverId({
  receiverId: currentUser.userId,
  reactionTimestamp: { eq: undefined } // 正常工作
})

技术分析

1. 类型系统不匹配

核心问题在于 TypeScript 的类型提示与实际的 AppSync 查询能力之间存在差异。TypeScript 的类型系统提供了比实际支持的更多的过滤选项，这导致了开发者的困惑。

在 TypeScript 中，开发者可以看到包括 attributeExists 在内的多种过滤选项，但实际上 AppSync 对于排序键只支持有限的几种比较操作符：

• eq (等于)
• le (小于等于)
• lt (小于)
• ge (大于等于)
• gt (大于)
• between
• beginsWith

2. 错误信息不友好

当开发者使用了不支持的过滤条件时，系统返回的错误信息"TypeError: Cannot convert null value to object"不够明确，没有指出真正的问题所在。这增加了调试的难度，开发者需要花费额外时间才能发现是过滤条件不匹配的问题。

3. 类型定义问题

深入分析发现，问题源于类型定义系统错误地将 ModelStringInput 类型应用到了应该使用 ModelStringKeyCondition 类型的场景。前者包含更多过滤选项，而后者只包含 AppSync 实际支持的有限操作。

解决方案

1. 使用正确的过滤条件

对于排序键字段，开发者应仅使用 AppSync 支持的几种比较操作符。对于检查字段是否存在的需求，可以使用 eq: undefined 作为替代方案。

2. 更新依赖

这个问题在较新版本的 @aws-amplify/data-schema 包中已经得到修复。开发者可以通过运行以下命令更新项目依赖：

npm update @aws-amplify/data-schema

3. 开发建议

1. 在使用二级索引查询时，仔细查阅官方文档，了解对排序键支持的具体过滤操作
2. 注意 TypeScript 的类型提示可能与实际支持的功能存在差异
3. 遇到类似类型错误时，首先考虑过滤条件是否匹配
4. 保持 Amplify 相关依赖的最新版本

总结

AWS Amplify JS 在提供强大功能的同时，其类型系统与实际后端服务的匹配度问题可能会给开发者带来困扰。理解 GraphQL 查询过滤条件的实际支持范围，以及 TypeScript 类型系统的局限性，可以帮助开发者更高效地构建应用。随着 Amplify 项目的持续发展，这类问题正在逐步得到改善，开发者应及时更新依赖以获取最佳体验。