如何解决boto3 list_roles方法返回空列表的问题？

问题现象

在使用Python的boto3库调用list_roles()方法时，开发者经常遇到返回空列表的情况，即使账户中确实存在IAM角色。典型代码如下：

import boto3
client = boto3.client('iam')
response = client.list_roles()
print(response['Roles'])  # 输出空列表[]

根本原因分析

经过对AWS文档和社区案例的研究，我们发现以下5个主要原因会导致list_roles()返回空结果：

权限不足：调用API的IAM用户/角色缺少iam:ListRoles权限
区域配置错误：IAM是全局服务，但某些SDK配置可能导致区域解析异常
路径限制：默认只返回路径为/的角色，忽略其他路径的角色
分页处理遗漏：未正确处理分页标记(Marker)导致只获取部分结果
条件筛选冲突：PathPrefix参数设置不当过滤了所有角色

解决方案

1. 检查IAM权限

确保执行调用的凭证具有以下最小权限策略：

{
    "Version": "2012-10-17",
    "Statement": [{
        "Effect": "Allow",
        "Action": "iam:ListRoles",
        "Resource": "*"
    }]
}

2. 显式指定区域

强制指定全局端点避免区域解析问题：

client = boto3.client('iam', region_name='aws-global')

3. 处理分页结果

完整获取所有角色的推荐实现方式：

def get_all_roles():
    client = boto3.client('iam')
    roles = []
    marker = None
    while True:
        kwargs = {'Marker': marker} if marker else {}
        response = client.list_roles(**kwargs)
        roles.extend(response['Roles'])
        if not response.get('IsTruncated'):
            break
        marker = response['Marker']
    return roles

4. 检查路径参数

如果需要获取特定路径下的角色，明确指定PathPrefix：

response = client.list_roles(PathPrefix='/application/')

调试技巧

使用aws sts get-caller-identity确认当前凭证
启用boto3日志记录查看原始请求：
import logging; logging.basicConfig(level=logging.DEBUG)
通过AWS CLI验证结果：
aws iam list-roles --query 'Roles[*].RoleName'

最佳实践

建议采用以下模式避免常见陷阱：

始终检查API响应中的IsTruncated字段
为生产环境实现指数退避重试机制
使用AWS SDK的Paginator简化分页处理
考虑使用get_account_authorization_details替代批量查询

通过以上方法，开发者可以系统地解决list_roles()返回空列表的问题，并建立更健壮的IAM角色查询机制。