Swift API封装：多可选查询参数的最优处理方案问询

针对你开发Swift API封装层时遇到的多可选查询参数批量处理问题，推荐两种比现有方案更高效的实现思路：

1. 基于Encodable的通用参数转换方案 #

这个方案能一次性解决所有API端点的参数需求，不用逐个拼接或手动解析，完全复用转换逻辑。

核心实现步骤： #

• 给每个API端点定义对应的Encodable参数结构体（无参数的端点用空结构体就行）
• 写一个通用工具方法，把Encodable实例自动转成URL查询参数列表，再拼到请求URL里

代码示例：

import Foundation

// 通用工具：将Encodable对象转为URL查询参数
extension Encodable {
    func toQueryItems() throws -> [URLQueryItem] {
        let encoder = JSONEncoder()
        encoder.keyEncodingStrategy = .convertToSnakeCase // 自动适配API常用的蛇形命名
        let data = try encoder.encode(self)
        
        guard let paramDict = try JSONSerialization.jsonObject(with: data) as? [String: Any] else {
            throw NSError(domain: "APIParamsError", code: -1, userInfo: [NSLocalizedDescriptionKey: "参数转换失败"])
        }
        
        return paramDict.compactMap { key, value in
            // 处理非字符串类型的参数（比如数字、布尔值）
            let stringValue = (value as? String) ?? "\(value)"
            return URLQueryItem(name: key, value: stringValue)
        }
    }
}

// 示例：某API的10个可选参数结构体
struct UserListParams: Encodable {
    let page: Int?
    let pageSize: Int?
    let sortBy: String?
    let filterName: String?
    let filterAge: Int?
    let includeDeleted: Bool?
    let startDate: String?
    let endDate: String?
    let region: String?
    let language: String?
}

// 构建API请求的示例方法
func fetchUserList(params: UserListParams) async throws -> Data {
    var components = URLComponents(string: "https://api.example.com/users")!
    components.queryItems = try params.toQueryItems()
    
    guard let url = components.url else {
        throw NSError(domain: "APIURLBuildError", code: -2, userInfo: [NSLocalizedDescriptionKey: "URL构建失败"])
    }
    
    let (data, _) = try await URLSession.shared.data(from: url)
    return data
}

// 无参数的API端点用空结构体
struct EmptyParams: Encodable {}
func fetchSystemStatus() async throws -> Data {
    let params = EmptyParams()
    var components = URLComponents(string: "https://api.example.com/status")!
    components.queryItems = try params.toQueryItems() // 生成空列表，不影响URL
    
    guard let url = components.url else {
        throw NSError(domain: "APIURLBuildError", code: -2, userInfo: [NSLocalizedDescriptionKey: "URL构建失败"])
    }
    
    let (data, _) = try await URLSession.shared.data(from: url)
    return data
}

方案优势： #

• 批量复用：所有API端点只需定义对应参数结构体，转换逻辑全靠通用方法搞定
• 类型安全：编译期就能检查参数类型和字段，避免手动拼接的拼写错误
• 自动适配：通过keyEncodingStrategy自动处理驼峰/蛇形命名转换，不用手动改参数名
• 扩展方便：新增参数只要在结构体里加字段，根本不用改拼接逻辑

2. 进阶：用泛型简化API请求方法 #

可以再封装一层通用请求方法，进一步减少重复代码：

// 枚举管理所有API端点
enum APIEndpoint {
    case userList
    case systemStatus
    // 新增端点直接加case就行
    
    private var baseURL: URL {
        URL(string: "https://api.example.com")!
    }
    
    var fullURL: URL {
        baseURL.appendingPathComponent(path)
    }
    
    private var path: String {
        switch self {
        case .userList: return "/users"
        case .systemStatus: return "/status"
        }
    }
}

// 通用请求发送方法
func sendAPIRequest<T: Encodable>(to endpoint: APIEndpoint, params: T) async throws -> Data {
    var components = URLComponents(url: endpoint.fullURL, resolvingAgainstBaseURL: true)!
    components.queryItems = try params.toQueryItems()
    
    guard let url = components.url else {
        throw NSError(domain: "APIURLBuildError", code: -2, userInfo: [NSLocalizedDescriptionKey: "URL构建失败"])
    }
    
    let (data, _) = try await URLSession.shared.data(from: url)
    return data
}

// 使用示例
let userParams = UserListParams(page: 1, pageSize: 20, sortBy: "created_at")
let userData = try await sendAPIRequest(to: .userList, params: userParams)

let statusData = try await sendAPIRequest(to: .systemStatus, params: EmptyParams())

和原有方案的对比 #

• 比逐个拼接参数：省去了大量重复的if let判断和字符串拼接代码，出错概率骤降，代码清爽很多
• 比结构体封装后逐个解析：不用手动写结构体到查询参数的转换逻辑，通用方法自动处理所有字段，新增参数零成本

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