Firestore API的CURL POST转Swift URLRequest在watchOS中遇404/400错误

核心问题分析 #

你遇到的404和400错误，大概率是端点格式错误、请求头缺失或Firestore请求体格式不匹配导致的——既然CURL能正常运行，说明接口本身是通的，问题出在Swift代码的请求构造上。

常见触发原因 #

1. 端点与请求方法不匹配
   • POST创建自动ID文档必须用集合端点：https://firestore.googleapis.com/v1/projects/{项目ID}/databases/(default)/documents/{集合名}，如果带了文档ID就会返回404
   • PATCH创建/更新指定ID文档必须用具体文档端点：https://firestore.googleapis.com/v1/projects/{项目ID}/databases/(default)/documents/{集合名}/{文档ID}，还要带updateMask参数，否则会返回400
2. 请求头缺失Content-Type
   CURL会自动给-d参数的请求加上Content-Type: application/json，但Swift的URLRequest需要显式设置，不然Firestore无法解析请求体
3. JSON请求体格式错误
   Firestore REST API要求字段必须用fields包裹，每个值要指定类型（比如stringValue、integerValue），直接传原始值会导致400
4. URL转义问题
   如果集合/文档名有特殊字符，URL(string:)可能解析失败，需要用URLComponents构建

修复方案与示例代码 #

1. POST自动生成文档ID（对应你正常运行的CURL） #

func addFirestoreDocument() async throws {
    let projectID = "你的项目ID"
    let collectionName = "你的集合名"
    // 注意：这里是集合端点，不带文档ID
    let urlString = "https://firestore.googleapis.com/v1/projects/\(projectID)/databases/(default)/documents/\(collectionName)"
    
    guard let url = URL(string: urlString) else {
        throw NSError(domain: "URL错误", code: -1, userInfo: nil)
    }
    
    // 严格按照Firestore要求的格式构造请求体
    let requestBody: [String: Any] = [
        "fields": [
            "username": ["stringValue": "watchOS测试"],
            "score": ["integerValue": 99]
        ]
    ]
    
    var request = URLRequest(url: url)
    request.httpMethod = "POST"
    // 必须显式设置Content-Type
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = try JSONSerialization.data(withJSONObject: requestBody)
    
    let (responseData, response) = try await URLSession.shared.data(for: request)
    
    // 打印响应排查问题
    if let httpResp = response as? HTTPURLResponse {
        print("状态码：\(httpResp.statusCode)")
    }
    print("响应内容：\(String(data: responseData, encoding: .utf8) ?? "无内容")")
}

2. PATCH指定文档ID创建/更新 #

如果要用PATCH，必须带文档ID和updateMask参数，示例：

func updateFirestoreDocument(docID: String) async throws {
    let projectID = "你的项目ID"
    let collectionName = "你的集合名"
    // 带文档ID的端点，同时拼接updateMask参数指定要更新的字段
    let urlString = "https://firestore.googleapis.com/v1/projects/\(projectID)/databases/(default)/documents/\(collectionName)/\(docID)?updateMask.fieldPaths=username&updateMask.fieldPaths=score"
    
    guard let url = URL(string: urlString) else {
        throw NSError(domain: "URL错误", code: -1, userInfo: nil)
    }
    
    let requestBody: [String: Any] = [
        "fields": [
            "username": ["stringValue": "更新后的名称"],
            "score": ["integerValue": 100]
        ]
    ]
    
    var request = URLRequest(url: url)
    request.httpMethod = "PATCH"
    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
    request.httpBody = try JSONSerialization.data(withJSONObject: requestBody)
    
    let (responseData, response) = try await URLSession.shared.data(for: request)
    
    if let httpResp = response as? HTTPURLResponse {
        print("状态码：\(httpResp.statusCode)")
    }
    print("响应内容：\(String(data: responseData, encoding: .utf8) ?? "无内容")")
}

3. 额外排查技巧 #

• 把你的CURL请求和Swift代码做逐行对比：
  1. 复制CURL中的URL到Swift，确保完全一致
  2. 打印Swift的request.httpBody转成字符串，和CURL的-d参数内容对比，看JSON结构是否一致
  3. 打印request.allHTTPHeaderFields，确认包含Content-Type: application/json
• 如果URL有特殊字符，用URLComponents构建避免转义错误：

var components = URLComponents()
components.scheme = "https"
components.host = "firestore.googleapis.com"
components.path = "/v1/projects/\(projectID)/databases/(default)/documents/\(collectionName)"
guard let url = components.url else { /* 处理URL错误 */ }

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