# iOS 网络适用于 iOS 26+ 的现代网络模式，使用带有异步/等待和结构化并发的 URLSession。所有示例都针对 Swift 6.2。不需要第三方依赖项——URLSession 满足绝大多数网络需求。 ## 内容 * 核心 URLSession 异步/等待 * API客户端架构 * 错误处理 * 分页 * 网络可达性 * 配置URL会话 * 常见错误 * 审查清单 * 参考文献 ## 核心 URLSession 异步/等待 URLSession 在 iOS 15 中获得了本机异步/等待重载。这些是在新代码中使用的唯一网络 API。切勿在新项目中使用完成处理程序变体。 ### 数据请求 // 基本的获取让（数据，响应）=尝试等待URLSession.shared.data（来自：url） // 使用配置好的 URLRequest var request = URLRequest(url: url) 请求.httpMethod =“POST” request.setValue("application/json", forHTTPHeaderField: "Content-Type") request.httpBody = 尝试 JSONEncoder().encode(payload) 请求超时间隔 = 30 request.cachePolicy = .reloadIgnoringLocalCacheData 让（数据，响应）=尝试等待URLSession.shared.data（for：请求） ### 响应验证在解码之前始终验证 HTTP 状态代码。 URLSession 不会抛出 4xx/5xx 响应——它只抛出传输级故障。守卫让 httpResponse = 响应为？ HTTPURL响应其他{ 抛出 NetworkError.invalidResponse } 守卫 (200..<300).contains(httpResponse.statusCode) else { 抛出 NetworkError.httpError( 状态代码：httpResponse.statusCode，数据：数据） } ### 使用 Codable 进行 JSON 解码 func fetch(_ type: T.Type, from url: URL) 异步抛出 -> T { 让（数据，响应）=尝试等待URLSession.shared.data（来自：url）守卫让 httpResponse = 响应为？ HTTPURL响应， (200..<300).contains(httpResponse.statusCode) else { 抛出 NetworkError.invalidResponse } 让解码器 = JSONDecoder() 解码器.dateDecodingStrategy = .iso8601 解码器.keyDecodingStrategy = .convertFromSnakeCase 返回尝试解码器.解码（T.self，来自：数据） } ### 下载和上传对于大文件使用“download(for:)”——它将流式传输到磁盘，而不是将整个有效负载加载到内存中。 // 下载到临时文件 let (localURL, response) = 尝试等待 URLSession.shared.download(for: request) // 在方法返回之前从临时位置移动让目的地= filesDirectory.appendingPathComponent（“file.zip”）尝试 FileManager.default.moveItem(at: localURL, to: 目的地) // 上传数据让（数据，响应）=尝试等待URLSession.shared.upload（for：request，from：bodyData） // 从文件上传让（数据，响应）=尝试等待URLSession.shared.upload（for：request，fromFile：fileURL） ### 使用 AsyncBytes 进行流式传输使用“bytes(for:)”来流式响应、进度跟踪或行分隔数据（例如服务器发送的事件）。让（字节，响应）=尝试等待URLSession.shared.bytes（for：请求）尝试在 bytes.lines 中等待行 { // 在每一行到达时对其进行处理（例如，SSE 流）处理事件（行） } ## API 客户端架构 ### 基于协议的客户端定义可测试性协议。这使您可以在测试中交换实现，而无需直接模拟 URLSession。协议 APIClientProtocol: 可发送 { func fetch( _ 类型：T.类型，端点：端点 ) 异步抛出 -> T func send( _ 类型：T.类型，端点：端点，主体：一些可编码和可发送 ) 异步抛出 -> T } 结构端点：可发送{ 让路径：字符串 var 方法: String = "GET" var queryItems: [URLQueryItem] = [] var headers: [String: String] = [:] func url(relativeTo baseURL: URL) -> URL { 保护让组件 = URLComponents( url: baseURL.appendingPathComponent(路径), 解析AgainstBaseURL：true ）否则{ preconditionFailure("路径的 URL 组件无效：\(path)") } var mutableComponents = 组件如果！queryItems.isEmpty { mutableComponents.queryItems = queryItems } Guard let url = mutableComponents.url else { preconditionFailure("无法从组件构造 URL") } 返回网址 } } 客户端接受“baseURL”、可选的自定义“URLSession”、“JSONDecoder”和“RequestMiddleware”拦截器数组。每个方法从端点构建一个“URLRequest”，应用中间件，执行请求，验证状态代码，并对结果进行解码。请参阅“references/urlsession-patterns.md”，了解完整的“APIClient”实现以及便捷方法、请求构建器和测试设置。 ### 轻量级基于闭包的客户端对于使用 MV 模式的应用程序，请使用基于闭包的客户端来实现可测试性和 SwiftUI 预览支持。有关完整模式，请参阅“references/lightweight-clients.md”（异步闭包结构，通过 init 注入）。 ### 请求中间件/拦截器中间件在发送请求之前对其进行转换。将其用于身份验证、日志记录、分析标头和类似的横切关注点。协议 RequestMiddleware: 可发送 { func prepare(_ request: URLRequest) 异步抛出 -> URLRequest } 结构AuthMiddleware：RequestMiddleware { let tokenProvider: @Sendable () 异步抛出 -> String func prepare(_ request: URLRequest) 异步抛出 -> URLRequest { var 请求 = 请求让 token = 尝试等待 tokenProvider() request.setValue("承载\(token)", forHTTPHeaderField: "授权") 退货请求 } } ### 令牌刷新流程通过刷新令牌并重试一次来处理 401 响应。 func fetchWithTokenRefresh( _ 类型：T.类型，端点：端点，令牌存储：令牌存储 ) 异步抛出 -> T { 做{ 返回尝试等待获取（类型，端点：端点） } 捕获 NetworkError.httpError(statusCode: 401, _) { 尝试等待 tokenStore.refreshToken() 返回尝试等待获取（类型，端点：端点） } } ## 错误处理 ### 结构化错误类型枚举 NetworkError：错误，可发送 { 案例无效响应 case httpError(statusCode: Int, data: Data) 案例解码失败（错误）案例无连接案例超时案件被取消 /// 将 URLError 映射到类型化的 NetworkError 静态函数 from(_ urlError: URLError) -> NetworkError { 切换 urlError.code { 案例.notConnectedToInternet，.networkConnectionLost：返回.noConnection 案例.timedOut：返回.timedOut 案件.取消：退货.取消默认：返回 .httpError(statusCode: -1, data: Data()) } } } ### 关键 URL 错误案例 URL错误代码 |意义|行动 ---|---|--- `.notConnectedToInternet` |设备离线|显示离线 UI，排队重试 `.networkConnectionLost` |连接在请求过程中中断 |后退重试 `.timedOut` |服务器未及时响应 |重试一次，然后显示错误 `.取消` |任务被取消 |无需采取任何行动；不显示错误 `.cannotFindHost` | DNS 故障 |检查 URL，显示错误 `.secureConnectionFailed` | TLS 握手失败 |检查证书固定、ATS 配置 `.userAuthenticationRequired` | 401 来自代理 |触发授权流程 ### 解码服务器错误体结构 APIErrorResponse：可解码，可发送 { 让代码：字符串让消息：字符串 } func解码APIError（来自数据：数据）-> APIErrorResponse？ { 尝试？ JSONDecoder().decode(APIErrorResponse.self，来自：数据) } // catch 块中的用法捕获 NetworkError.httpError(let statusCode, let data) { 如果让 apiError =decodeAPIError（来自：数据）{ showError("服务器错误：\(apiError.message)") } 否则{ showError("HTTP \(statusCode)") } } ### 使用指数退避重试使用结构化并发进行重试。尊重尝试之间的任务取消。跳过取消和 4xx 客户端错误（429 除外）的重试。 func withRetry( 最大尝试次数：Int = 3，初始延迟：持续时间=.秒（1），操作： @Sendable () 异步抛出 -> T ) 异步抛出 -> T { var LastError: 错误？对于 0.. AsyncStream { AsyncStream { 继续让监视器 = NWPathMonitor() Monitor.pathUpdateHandler = { continuation.yield($0.status) } continuation.onTermination = { _ in monitor.cancel() } Monitor.start（队列：DispatchQueue（标签：“NetworkMonitor”）） } } 检查“path.isExpense”（蜂窝）和“path.isConstrained”（低数据模式）以适应行为（降低图像质量、跳过预取）。 ## 配置 URLSession 为生产代码创建已配置的会话。 `URLSession.shared` 仅适用于简单的一次性请求。让配置 = URLSessionConfiguration.default 配置.timeoutIntervalForRequest = 30 配置.timeoutIntervalForResource = 300 配置.waitsForConnectivity = true 配置.requestCachePolicy = .returnCacheDataElseLoad 配置.httpAdditionalHeaders = [ “接受”：“应用程序/json”， “接受语言”：Locale.preferredLanguages.first ?? “恩” ] 让会话= URLSession（配置：配置） `waitsForConnectivity = true` 很有价值——它使会话等待网络路径，而不是在离线时立即失败。与 UI 反馈的 urlSession(_:taskIsWaitingForConnectivity:) 委托回调结合使用。 ## 常见错误 **不要：** 使用“URLSession.shared”来满足自定义配置需求。 **要做：** 创建一个已配置的“URLSession”，具有适当的超时、缓存和生产代码委托。 **不要：** 使用动态输入强制解包 `URL(string:)`。 **要：** 使用“URL(string:)”并进行适当的错误处理。强制解包仅适用于编译时常量字符串。 **不要：** 在主线程上解码 JSON 以获取大负载。 **DO:** 继续在 URLSession 调用的调用上下文上进行解码，默认情况下该调用上下文是 off-main 的。仅跳转到“@MainActor”来更新 UI 状态。 **不要：** 忽略长时间运行的网络任务中的取消。 **要做：** 检查 `Task.isCancelled` 或在循环中调用 `try Task.checkCancellation()`（分页、流式传输、重试）。在 SwiftUI 中使用 `.task` 进行自动取消。 **不要：** 当 URLSession async/await 处理需要时使用 Alamofire 或 Moya。 **要：** 直接使用 URLSession。使用 async/await，证明第三方库合理的人体工程学差距不再存在。为真正缺少的功能（例如图像缓存）保留第三方库。 **不要：** 直接在测试中模拟 URLSession。 **要：** 使用“URLProtocol”子类进行传输级模拟，或使用接受测试替身的基于协议的客户端。 **不要：** 使用 `data(for:)` 进行大文件下载。 **要：** 使用 `download(for:)` 流式传输到磁盘并避免内存峰值。 **不要：**激发来自“body”或视图初始值设定项的网络请求。 **DO:** 使用 `.task` 或 `.task(id:)` 来触发网络调用。 **不要：** 在请求中硬编码身份验证令牌。 **要做：** 通过中间件注入代币，以便它们集中且可刷新。 **不要：** 忽略 HTTP 状态代码并盲目解码。 **DO：** 在解码之前验证状态代码。具有无效 JSON 的 200 和具有错误正文的 500 需要不同的处理。 ## 审核清单 * 所有网络调用都使用 async/await （不是完成处理程序） * 错误处理涵盖 URLError 情况（.notConnectedToInternet、.timedOut、.cancelled） * 请求是可取消的（通过“.task”修饰符或存储的任务引用来尊重任务取消） * 通过中间件注入的身份验证令牌，而不是硬编码 * 解码前验证响应 HTTP 状态代码 * 大量下载使用 `download(for:)` 而不是 `data(for:)` * 网络调用发生在 `@MainActor` 之外（仅在 main 上更新 UI） * URLSession 配置了适当的超时和缓存 * 重试逻辑不包括取消和 4xx 客户端错误 * 分页检查页面之间的 `Task.isCancelled` * 存储在钥匙串中的敏感令牌（不是 UserDefaults 或普通文件） * 动态输入中没有强制解包的 URL * 服务器错误响应被解码并呈现给用户 * 确保网络响应模型类型符合Sendable；使用@MainActor作为UI更新完成路径 ## 参考文献 * 请参阅 `references/urlsession-patterns.md` 了解完整的 API 客户端实现、分段上传、下载进度、URLProtocol 模拟、重试/退避、证书固定、请求日志记录和分页实现。 * 请参阅 `references/background-websocket.md` 了解后台 URLSession 配置、后台下载/上传、具有结构化并发的 WebSocket 模式以及重新连接策略。 * 请参阅 `references/lightweight-clients.md` 了解轻量级基于闭包的客户端模式（异步闭包的结构，通过 init 注入以实现可测试性和预览支持）。 * 请参阅 `references/network-framework.md` 了解 Network.framework（NWConnection、NWListener、NWBrowser、NWPathMonitor）和低级 TCP/UDP/WebSocket 模式。

IOS网络

包含技能