Swift URL Session遇&符号时AWS S3文档链接响应损坏问题

问题根源 #

你的请求URL里的S3Key参数值包含&——这个字符在URL中是参数分隔符，iOS的URLSession解析时会把&ServiceLetter.pdf当成新的独立参数，导致后端接收到的S3Key被截断成Document/sdd3343-sfnf0asdnd0UserB，最终返回的S3链接自然缺失后半部分文件名。Android和Swagger能正常工作，是因为它们的网络库/工具会自动对查询参数做URL编码，规避了这个问题。

解决方案 #

核心是对包含特殊字符的参数值做URL编码，推荐两种可靠实现方式：

方式1：使用URLComponents（推荐，自动编码）

URLComponents是iOS中构建URL的安全方式，会自动对每个查询参数的value进行正确编码，无需手动处理字符集：

// 原始未编码的S3Key值
let rawS3Key = "Document/sdd3343-sfnf0asdnd0UserB&ServiceLetter.pdf"

// 构建URL组件
guard var components = URLComponents(string: "https://domainName/api/FileUpload/GetDocumentUrl") else {
    // 处理URL格式错误
    return
}

// 添加查询参数
components.queryItems = [
    URLQueryItem(name: "S3Key", value: rawS3Key),
    URLQueryItem(name: "fileCategory", value: "2"),
    URLQueryItem(name: "userId", value: "9888900000")
]

// 生成最终请求URL
guard let requestURL = components.url else {
    return
}

// 发起请求
var request = URLRequest(url: requestURL)
request.httpMethod = "GET"

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    // 处理响应逻辑
}
task.resume()

方式2：手动编码参数值

如果需要手动拼接URL，要先对参数值单独编码，注意排除URL特殊字符：

// 自定义字符集：排除URL参数分隔符（&、=等）
extension CharacterSet {
    static let urlQueryValueAllowed: CharacterSet = {
        let generalDelimiters = ":#[]@"
        let subDelimiters = "!$&'()*+,;="
        let forbidden = CharacterSet(charactersIn: "\(generalDelimiters)\(subDelimiters)")
        return CharacterSet.urlQueryAllowed.subtracting(forbidden)
    }()
}

// 编码S3Key
let rawS3Key = "Document/sdd3343-sfnf0asdnd0UserB&ServiceLetter.pdf"
guard let encodedS3Key = rawS3Key.addingPercentEncoding(withAllowedCharacters: .urlQueryValueAllowed) else {
    return
}

// 拼接完整URL
let fullURLString = "https://domainName/api/FileUpload/GetDocumentUrl?S3Key=\(encodedS3Key)&fileCategory=2&userId=9888900000"
guard let requestURL = URL(string: fullURLString) else {
    return
}

// 发起请求（同方式1）

验证效果 #

编码后的S3Key会变成Document/sdd3343-sfnf0asdnd0UserB%26ServiceLetter.pdf，后端能完整接收这个值，返回的S3链接也会包含完整的&ServiceLetter.pdf部分。

内容的提问来源于stack exchange，提问作者Trevo Fernando