Shopify_app 22.3.0版本中JWT Payload类型校验的变更解析

在Shopify_app从22.2.1升级到22.3.0版本后，许多开发者遇到了一个关于JWT Payload的类型校验问题。这个问题主要表现为在测试环境中运行时抛出TypeError异常，提示"Expected type Integer, got type String with value..."。本文将深入分析这一变更的技术背景、产生原因以及解决方案。

问题背景

Shopify_app在22.3.0版本中对JWT解码器进行了重要更新。原本使用的ShopifyApp::JWT被替换为ShopifyAPI::JwtPayload。这一变更的核心差异在于新的解码器对JWT Payload中的字段类型实施了更严格的校验。

技术细节解析

JWT(JSON Web Token)是Shopify应用认证中的重要组成部分，其Payload部分包含了关键的会话信息。在旧版本中，exp(过期时间)字段可以接受字符串形式的数字值，但在新版本中，这一字段必须严格为整数类型。

这种类型强校验的变更符合JWT标准规范。根据RFC 7519标准，JWT中的时间戳字段(如exp、nbf、iat)都应当使用数值类型(NumericDate)表示。Shopify官方文档中的示例Payload也明确展示了这些字段应为整数形式。

问题重现场景

在测试环境中，开发者通常会手动构造JWT用于测试。常见的做法是使用类似Time.now.to_i + 5.minutes的方式生成过期时间。这种写法在旧版本中可以正常工作，但在22.3.0及以上版本会触发类型校验错误。

解决方案

正确的做法是确保所有时间戳字段都使用纯整数形式。对于测试代码，应将表达式修改为：

exp: (Time.now + 5.minutes).to_i

这一修改确保了生成的exp值是纯粹的整数类型，符合新版本的类型校验要求。

升级建议

对于正在升级Shopify_app的开发者，建议：

1. 全面检查测试代码中所有手动构造JWT的地方
2. 确保时间戳相关字段(exp、nbf、iat)都使用整数类型
3. 在CI/CD流程中加入针对JWT构造的专项测试

这一变更虽然带来了短暂的适配成本，但从长远看提高了类型安全性，使应用行为更加符合标准规范，值得开发者投入时间进行适配。