Python Sanic框架实现高效文件上传功能详解

纸上星河

发布时间：2026-10-12 | 2人浏览过

原创

本文详细介绍如何在Python异步Web框架Sanic中实现文件上传功能。内容涵盖环境配置、基础代码实现、Postman与requests库测试方法，以及文件类型验证、安全性防护、大文件进度反馈和异步处理等进阶技巧，帮助开发者构建安全高效的文件上传服务。

前言

Sanic是一个基于Python 3.5及以上版本的异步Web框架，其设计思路与Flask相近，但核心优势在于采用更高效的异步I/O处理机制。在文件上传场景中，Sanic提供了便捷且高性能的解决方案。本教程将通过具体案例，深入解析如何在Sanic框架中实现文件上传功能。

环境准备

在开始编码之前，请确保开发环境中已安装Python 3.5或更高版本，并完成Sanic框架的安装。若尚未安装，可通过pip命令执行安装操作：

pip install sanic

基本概念

在Sanic框架中，文件上传主要依赖request.files属性进行数据获取。当客户端以multipart/form-data格式发送POST请求时，开发者可通过request.files.get('filename')方法获取指定的文件对象，从而进行后续处理。

文件上传示例

1. 创建Sanic应用

首先，我们需要构建一个Sanic应用实例，并定义用于处理文件上传的路由。同时，建议预先创建用于存储上传文件的目录。

代码展示：

from sanic import Sanic
from sanic.response import json

app = Sanic("File-Upload-Example")


@app.route("/upload", methods=["POST"])
async def handle_upload(request):
    # 获取上传的文件，根据请求体中file字段获取上传的文件
    #先打印file对象
    print("files对象",request.files)
    file = request.files.get('file')
    # print("获取的文件对象名",file.name)
    print("查看file有哪些方法",dir(file))

    if file:
        # 对文件进行处理，这里简单地将文件保存到本地

        file_path = './uploads/' + file.name
        with open(file_path, 'wb') as f:
            #上传的文件在file的body中
            f.write(file.body)

        return json({"message": "File uploaded successfully", "filename": file.name})
    else:
        return json({"error": "No file uploaded"}, status=400)


if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8000)

2. 客户端上传文件

为了验证文件上传功能，我们需要一个客户端工具来发送文件请求。可以使用Postman等接口测试工具，或者利用Python的requests库编写脚本发送请求。

使用Postman

启动Postman，新建一个POST类型的请求。
在请求URL栏输入http://localhost:8000/upload。
在Headers部分，将Content-Type设置为multipart/form-data。
在Body选项卡中选择form-data类型，然后点击Add file按钮以添加要上传的文件。
随后在Value字段点击Search Files，浏览并选择需要上传的文件。
点击发送请求，并观察服务器返回的响应结果。

在Body处选择form-data类型，创建一个key为file的键值对。

点击Search Files选择需要上传的文件

选择文件

点击发送请求

上传成功

使用Python requests库

我们在桌面创建一个txt文档用于测试。

import requests

url = 'http://localhost:8000/upload'
files = {'file': open(r'C:\Users\dell\Desktop\text.txt', 'rb')}

response = requests.post(url, files=files)
print(response.text)

上传成功

文件上传的进阶用法

3. 验证上传文件的类型

为了防范用户上传不安全文件（如可执行文件或脚本），必须在服务器端对上传文件的MIME类型或扩展名进行验证。

from sanic import HTTPResponse, request, json

@app.route("/upload", methods=["POST"])
async def handle_upload(request):
    file = request.files.get("file")
    
    if not file:
        return json({"error": "没有文件被上传"}, status=400)
    
    # 检查文件类型
    allowed_types = {"image/jpeg", "image/png", "application/pdf"}
    if file.type not in allowed_types:
        return json({"error": "不允许的文件类型"}, status=400)
    
    # 保存文件（这里省略了具体的保存逻辑）
    
    return json({"message": "文件上传成功"})

在此示例中，我们检查了上传文件的type属性，该属性通常包含文件的MIME类型。我们定义了一个allowed_types集合，用于限定允许上传的文件类型。若上传文件类型不在该集合内，服务器将返回错误响应。

4. 安全性考虑

防止目录遍历：在保存上传文件时，切勿直接使用用户输入的文件名或路径，以免遭受目录遍历攻击。建议使用哈希函数或UUID生成唯一文件名。
限制上传目录权限：确保上传目录的权限设置合理，防止未授权访问或执行上传的文件。
使用HTTPS：在生产环境中，务必使用HTTPS协议，以保障用户数据和文件传输的安全性。

5. 进度反馈

对于大文件上传，用户通常希望查看上传进度。虽然Sanic本身不直接支持上传进度跟踪，但可以通过前端JavaScript（如利用XMLHttpRequest或Fetch API的upload事件）来监控上传进度。随后，通过WebSocket、Server-Sent Events (SSE) 或轮询等方式将进度信息发送至服务器，服务器再将这些信息广播给相关客户端。