Python requests上传文件教程

requests库文件上传的核心机制是将文件数据封装成符合multipart/form-data规范的请求体，并自动设置正确的Content-Type头部。它通过生成边界符分隔字段，构建包含Content-Disposition、Content-Type和文件内容的请求块，再拼接成完整请求体。该机制支持单个或多个文件上传、内存中二进制数据上传及与普通表单数据混合提交，同时提供对MIME类型指定、超时控制和SSL验证等配置的支持，简化了复杂性并提升开发效率。

Python的requests库在文件上传这块，用起来其实非常直观。它的核心思想就是把文件数据包装进一个files参数里，requests会自动帮你处理好背后复杂的multipart/form-data编码，省去了我们手动构建请求体的麻烦。简单来说，你只需要告诉requests哪个字段对应哪个文件，它就能帮你搞定一切。

解决方案

使用requests上传文件，最直接的方式就是将文件对象（或者二进制数据）传递给requests.post()或requests.put()方法的files参数。这个参数通常是一个字典，键是服务器期望接收的文件字段名，值则是你的文件数据。

import requests
from io import BytesIO

# 假设我们有一个名为 'my_document.txt' 的文本文件要上传
# 实际操作中，请确保该文件存在于当前目录下或提供完整路径
# 为了演示，我们先创建一个虚拟文件
with open('my_document.txt', 'w') as f:
    f.write('这是一段测试文本，用于文件上传。')

# 1. 上传单个文件
url = "http://httpbin.org/post" # 一个常用的测试POST请求的公共服务

print("--- 上传单个文件 ---")
try:
    with open('my_document.txt', 'rb') as f: # 以二进制读取模式打开文件
        files = {'upload_file': f} # 'upload_file' 是服务器期望接收的文件字段名
        response = requests.post(url, files=files)

    if response.status_code == 200:
        print("文件上传成功！")
        print(response.json()) # 打印服务器返回的JSON数据
    else:
        print(f"文件上传失败，状态码: {response.status_code}")
        print(response.text)

except FileNotFoundError:
    print("错误：my_document.txt 文件不存在。")
except requests.exceptions.RequestException as e:
    print(f"请求发生错误: {e}")


# 2. 上传多个文件
print("\n--- 上传多个文件 ---")
# 假设我们还有另一个文件 'another_doc.pdf'
with open('another_doc.pdf', 'w') as f:
    f.write('这是另一个测试文件。')

try:
    files_to_upload = {
        'doc1': ('my_document.txt', open('my_document.txt', 'rb'), 'text/plain'),
        'doc2': ('another_doc.pdf', open('another_doc.pdf', 'rb'), 'application/pdf')
    }
    # 注意：这里我们使用了元组形式，可以指定文件名、文件对象/二进制数据、MIME类型
    # requests会自动关闭文件对象，但显式管理更好

    response_multi = requests.post(url, files=files_to_upload)

    if response_multi.status_code == 200:
        print("多个文件上传成功！")
        print(response_multi.json())
    else:
        print(f"多个文件上传失败，状态码: {response_multi.status_code}")
        print(response_multi.text)

finally:
    # 确保文件被关闭，即使上传失败
    for file_info in files_to_upload.values():
        if isinstance(file_info, tuple) and hasattr(file_info[1], 'close'):
            file_info[1].close()
    import os
    os.remove('my_document.txt')
    os.remove('another_doc.pdf')


# 3. 上传内存中的二进制数据（比如从数据库或网络获取的图片）
print("\n--- 上传内存中的二进制数据 ---")
image_data = b"This is some simulated image data." # 假设这是从某个地方读取到的图片二进制数据
image_filename = "in_memory_image.jpg"
image_mimetype = "image/jpeg"

files_in_memory = {'image_field': (image_filename, image_data, image_mimetype)}

try:
    response_mem = requests.post(url, files=files_in_memory)
    if response_mem.status_code == 200:
        print("内存数据上传成功！")
        print(response_mem.json())
    else:
        print(f"内存数据上传失败，状态码: {response_mem.status_code}")
        print(response_mem.text)
except requests.exceptions.RequestException as e:
    print(f"请求发生错误: {e}")

在上面的例子里，files字典的值可以是：

• 一个文件对象（如open('file.txt', 'rb')的返回值）。
• 一个包含文件名、文件内容（二进制字符串或文件对象）、可选的MIME类型和自定义请求头的元组。

requests会智能地根据你提供的数据类型来构造正确的Content-Type头部，通常是multipart/form-data。

requests库文件上传的核心机制是什么？

说实话，刚开始接触文件上传时，我总是对那些HTTP请求头和数据格式感到头疼，尤其是multipart/form-data。但requests库的厉害之处就在于它把这些复杂性都隐藏起来了。它的核心机制可以概括为：将文件数据封装成符合HTTP multipart/form-data规范的请求体，并自动设置正确的Content-Type头部。

当你把一个文件对象或者一个包含文件信息的元组传给files参数时，requests会在内部做几件事：

1. 识别文件字段： 它会知道你希望把哪个Python对象当作哪个HTTP表单字段的文件来处理。
2. 构建边界符（Boundary）： multipart/form-data请求体需要一个独特的边界符来分隔不同的表单字段和文件内容。requests会自动生成一个随机且足够复杂的边界符。
3. 格式化文件块： 对于每一个文件，requests会构建一个包含以下信息的块：
   • Content-Disposition头部：通常是form-data; name="field_name"; filename="original_filename"，这告诉服务器这个块是一个表单数据，它的字段名是什么，以及原始文件名是什么。
   • Content-Type头部：指定文件的MIME类型（例如image/jpeg, text/plain等）。如果你没有明确指定，requests会尝试根据文件名后缀猜测，或者默认使用application/octet-stream。
   • 文件内容：文件的实际二进制数据。
4. 拼接请求体： 所有这些文件块以及可能存在的普通表单数据（通过data参数传递的）会被边界符分隔，最终拼接成一个完整的HTTP请求体。
5. 设置请求头： 最后，requests会设置请求的Content-Type头部为multipart/form-data; boundary=YOUR_GENERATED_BOUNDARY，确保服务器能正确解析。

我个人觉得，理解这个机制能帮助我们更好地调试问题，比如当服务器抱怨Content-Type不对或者文件字段名不匹配时，我们就能知道大概是哪个环节出了问题。requests把这些细节都处理得很好，让我们的代码看起来非常简洁。

如何处理不同类型的文件上传场景？

文件上传的需求其实挺多变的，requests在这方面提供了足够的灵活性来应对。

1. 单个文件上传： 这是最常见的场景，就像上面解决方案里演示的那样。你只需要open()文件，然后把它传给files字典。

   # 假设 upload.txt 存在
   with open('upload.txt', 'rb') as f:
       files = {'my_file_field': f}
       response = requests.post(url, files=files)

   这里my_file_field就是服务器端接收文件的字段名。

2. 多个文件上传： 如果你需要一次性上传多个文件，并且它们可能对应不同的表单字段名，或者对应同一个字段名但服务器期望接收一个文件列表，requests也能处理。

   • 不同字段名： files字典里直接放多个键值对。

     files_multiple_fields = {
         'document': open('doc.pdf', 'rb'),
         'image': open('photo.jpg', 'rb')
     }
     response = requests.post(url, files=files_multiple_fields)

   • 相同字段名（作为列表）： files字典的值可以是一个列表，列表的每个元素都是一个文件信息元组。

     files_list = [
         ('images', ('pic1.png', open('pic1.png', 'rb'), 'image/png')),
         ('images', ('pic2.jpg', open('pic2.jpg', 'rb'), 'image/jpeg'))
     ]
     response = requests.post(url, files=files_list)

     这种方式服务器通常会收到一个名为images的文件列表。

3. 上传内存中的二进制数据： 有时候文件不是来自本地磁盘，而是通过网络获取、或者在程序中动态生成的二进制数据（比如图片处理后的结果）。这时，你可以直接传递二进制字符串或io.BytesIO对象。

   from io import BytesIO
   # 模拟一张图片数据
   fake_image_bytes = b'\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x06\x00\x00\x00\x1f\x15\xc4\x89\x00\x00\x00\nIDATx\xda\xed\xc1\x01\x01\x00\x00\x00\xc2\xa0\xf7Om\x00\x00\x00\x00IEND\xaeB`\x82'
   
   files_memory = {
       'image_data': ('my_generated_image.png', fake_image_bytes, 'image/png')
   }
   response = requests.post(url, files=files_memory)

   这里通过元组指定了文件名和MIME类型，确保服务器能正确识别。

4. 与普通表单数据混合上传： 文件上传往往伴随着一些文本表单字段，比如文件的描述、作者信息等。你可以同时使用data参数（用于普通表单字段）和files参数（用于文件）。

   data_payload = {
       'description': '这是一份重要的报告',
       'author': '张三'
   }
   files_mixed = {
       'report_file': ('report.docx', open('report.docx', 'rb'), 'application/vnd.openxmlformats-officedocument.wordprocessingml.document')
   }
   response = requests.post(url, data=data_payload, files=files_mixed)

   requests会很智能地把data里的数据也一并打包进multipart/form-data请求体中。

文件上传过程中可能遇到的常见问题及解决策略？

即使requests已经把文件上传简化了很多，但在实际操作中，我们还是会遇到一些让人挠头的问题。

1. 文件路径或权限问题：

   • 问题： FileNotFoundError是最常见的，通常是因为你提供的文件路径不对，或者程序没有权限读取该文件。
   • 策略： 仔细检查文件路径是否正确，特别是相对路径。确保运行Python脚本的用户有读取文件的权限。在Linux/macOS上，可以用ls -l查看文件权限；在Windows上，右键文件属性查看安全选项卡。

2. Content-Type不匹配：

   • 问题： 服务器可能会拒绝上传，因为它期望的文件类型和你实际发送的不一致。比如服务器只接受image/jpeg，但你发送的是image/png。
   • 策略： 在files参数中使用元组形式明确指定文件的MIME类型。

     files = {'image': ('my_photo.jpg', open('my_photo.jpg', 'rb'), 'image/jpeg')}

     如果不知道MIME类型，可以尝试使用mimetypes库来猜测：

     import mimetypes
     file_path = 'my_document.pdf'
     mime_type, _ = mimetypes.guess_type(file_path)
     # 如果猜测失败，mime_type可能是None，此时可以设为 'application/octet-stream'
     files = {'file_field': (file_path, open(file_path, 'rb'), mime_type or 'application/octet-stream')}

3. 大文件上传时的内存消耗：

   • 问题： 如果你尝试一次性读取一个非常大的文件到内存（比如几个GB），可能会导致程序崩溃或性能问题。
   • 策略： requests在处理files参数时，如果传入的是文件对象，它会以流式方式读取文件内容，而不是一次性加载到内存。所以，通常只要你使用with open(...) as f:的方式，内存消耗不会成为大问题。但如果你是先f.read()把整个文件读进一个变量，再把这个变量传进去，那内存问题就可能出现。对于超大文件，更高级的策略是实现分块上传（chunked upload），但这通常需要服务器端也支持，并且需要我们手动管理每个块的上传和合并，超出了requests库直接提供的范畴。

4. 服务器响应错误或无响应：

   • 问题： 上传后收到非200的状态码（如400 Bad Request, 500 Internal Server Error），或者请求超时。
   • 策略：
     • 检查状态码和响应内容： response.status_code和response.text或response.json()会告诉你服务器具体返回了什么错误信息。这是排查问题的首要步骤。
     • 日志记录： 在开发阶段，可以打印出请求的URL、头部和响应内容，帮助定位问题。
     • 超时设置： 使用timeout参数防止请求无限期等待。

       response = requests.post(url, files=files, timeout=30) # 30秒超时

       超时后会抛出requests.exceptions.Timeout异常，你需要捕获它。

5. SSL证书验证问题：

   • 问题： 当上传到HTTPS服务器时，如果服务器的SSL证书有问题或者自签名，可能会遇到SSLError。
   • 策略： 在开发或测试环境中，可以通过verify=False来禁用SSL证书验证，但强烈不建议在生产环境中使用，因为它会带来安全风险。

     response = requests.post(url, files=files, verify=False)

     更好的做法是配置正确的证书，或者将自签名证书添加到系统的信任列表中。

总的来说，文件上传虽然看起来简单，但细节不少。关键在于理解HTTP协议的multipart/form-data机制，并善用requests提供的灵活性和错误处理机制。多看服务器端的日志和API文档，往往能更快地找到问题所在。