AWS SDK for Go v2 中 EC2 DescribeKeyPairs 空过滤器序列化问题分析

问题背景

在 AWS SDK for Go v2 的最新版本中，使用 EC2 服务的 DescribeKeyPairs API 时，当传入空的过滤器(Filters)切片时，会出现 400 Bad Request 错误。这个问题在升级 SDK 版本后出现，表现为 API 请求被 EC2 服务拒绝，返回"InvalidRequest: The request received was invalid"错误。

问题现象

通过对比新旧版本的请求日志，可以清晰地看到差异：

旧版本(1.22.2)请求:

Action=DescribeKeyPairs&KeyPairId.1=key-0d42034f8dbc0254b&Version=2016-11-15

新版本(1.26.1)请求:

Action=DescribeKeyPairs&Filter=&KeyPairId.1=key-0d42034f8dbc0254b&Version=2016-11-15

关键区别在于新版本会序列化空的 Filters 参数为"Filter="，而旧版本则完全忽略空的过滤器列表。

根本原因

深入分析 SDK 代码变化，发现问题源于序列化逻辑的修改。在旧版本(1.22.2)中，序列化函数会检查切片长度，如果为空则直接返回：

func awsEc2query_serializeDocumentFilterList(v []types.Filter, value query.Value) error {
    if len(v) == 0 {
        return nil
    }
    // ...其余代码
}

而在新版本(1.26.1)中，这个长度检查被移除了：

func awsEc2query_serializeDocumentFilterList(v []types.Filter, value query.Value) error {
    array := value.Array("Filter")
    // ...其余代码
}

这种变化源于 SDK 对 EC2 查询协议(ec2Query)序列化行为的调整，目的是更严格地遵循协议规范。然而，EC2 服务端似乎不能正确处理这种显式空过滤器的序列化形式。

技术细节

1. 序列化差异：

   • 空切片(nil slice)不会被序列化
   • 非空但长度为0的切片([]types.Filter{})会被序列化为"Filter="
   • 包含元素的切片会正常序列化为"Filter.1.Name=...&Filter.1.Value.1=..."等形式

2. EC2 查询协议：

   • EC2 使用特殊的查询协议(ec2Query)，与标准的AWS查询协议(awsQuery)有所不同
   • 协议规范要求某些参数必须存在，但对空值的处理可能存在服务端实现差异

解决方案

目前推荐的解决方案是：

1. 将空切片设为nil： 在构造请求参数时，避免使用零长度切片，而是直接设为nil：

input := &ec2.DescribeKeyPairsInput{
    KeyPairIds: []string{"key-0d42034f8dbc0254b"},
    Filters:    nil, // 而不是 []types.Filter{}
}

2. 等待官方修复： AWS SDK 团队已经确认这是一个问题，并计划在未来的版本中修复，使 ec2Query 协议的空列表序列化行为与 awsQuery 协议区分开来。

最佳实践

1. 参数初始化： 在构造 API 请求参数时，对于可能为空的列表参数，优先使用nil而不是空切片。

2. 版本升级检查： 升级 SDK 版本时，特别注意与序列化相关的变更日志，测试所有关键API调用。

3. 错误处理： 对可能出现的400错误增加重试逻辑，特别是当升级SDK后遇到类似问题时。

总结

这个问题展示了协议实现细节对API客户端的影响。作为开发者，理解底层协议的序列化行为对于诊断和解决这类问题至关重要。在AWS SDK for Go v2的使用中，应当注意空参数的处理方式，特别是在涉及EC2服务时。目前可以通过将空切片设为nil来规避此问题，同时期待官方在未来版本中提供更完善的解决方案。