用途:在 Apple 平台上构建或审查网络层,基于 URLSession 的原生 async/await、结构化并发与 Network.framework,目标 Swift 6.3 / iOS 26+。
主要能力与原则:前台请求优先用 URLSession.shared.data(for:)、download(for:)、bytes(for:)。URLSession 只在传输层失败(离线、DNS、超时)时抛错,4xx/5xx 不会抛错,必须显式校验 (200..<300).contains(httpResponse.statusCode)。重试需有界,采用指数退避加抖动,且只重试幂等操作(GET、PUT、DELETE),不得无限循环刷新令牌。令牌存储、刷新锁与 Cookie 管理应隔离在 actor 或串行同步队列中。错误需区分传输错误(URLError)、解码错误(DecodingError)、客户端错误(4xx)、服务端错误(5xx)与取消(CancellationError)。
传输方式:前台数据用 try await session.data(for:),配置 .default 或 .ephemeral,应用挂起时取消;前台下载用 try await session.download(for:),挂起时暂停或取消;后台传输用 session.downloadTask(with:) 配合 delegate 与 URLSessionConfiguration.background(withIdentifier:),由进程外管理并在完成后重启应用;WebSocket 用 session.webSocketTask(with:),恢复连接时需重连。
按任务路由:构建可复用 API 客户端、请求编码器、认证头与 actor 参见 API Client 与 Lightweight Clients;重试、证书固定、TLS 安全与字节流参见 Resilience、Security 与 Streaming;大文件上传、续传数据与进度参见 Uploads and Downloads 与 File Storage Patterns;后台传输与重启处理参见 Background Transfers;实时 WebSocket 参见 WebSocket Networking;分页与 URLProtocol 测试参见 Pagination and URLProtocol Testing;底层 TCP/UDP、路径监控与蜂窝限制(NWPathMonitor)参见 Network Framework。
常见错误:误以为 data(for:) 会在 404/500 时抛错而不检查 statusCode;在后台 URLSessionConfiguration 上使用 async/await 便捷重载(需 delegate 回调);网络超时后自动重试非幂等 POST;泄漏 NWPathMonitor 或未设置 dispatch queue 就启动监控;在 urlSession(_:downloadTask:didFinishDownloadingTo:) 返回后再移动下载文件(返回时文件即被删除)。
审查清单:解码前显式校验 HTTP 状态码;区分传输错误与服务端错误负载;仅对幂等请求使用带抖动的安全重试;令牌刷新用 actor 隔离避免重复刷新;后台会话配置 delegate 并同步移动临时文件;URLProtocol 测试覆盖 2xx、4xx、5xx、超时与取消;非必要不使用 ATS 例外。
限制:资料未提供具体安装命令、收费方式与平台支持范围等细节。