Starlette如何实现文件分片上传

夜静吖_9461

夜静吖_9461

2026-11-20

637人浏览

原创

starlette 本身不直接提供分片上传的专用 api,而是通过流式读取请求体来实现。开发者需要监听 receive 事件,识别客户端发送的分片数据,并根据业务逻辑将数据写入磁盘或存储桶。通常的做法是结合 http 头信息(如 content-range)来管理分片的顺序和完整性。

Starlette如何实现文件分片上传

如何解析 Content-Range 头以定位文件位置

在分片上传中,每个 HTTP 请求都会携带 Content-Range 头,用于告知服务器当前片段在整个文件中的字节偏移量。Starlette 的 Request 对象可以通过 headers.get() 方法轻松获取该值。解析这个字符串可以计算出当前片段的起始偏移量,从而确保数据被正确追加到文件的指定位置。

Starlette如何实现文件分片上传

import re
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.requests import Request
import os

# 配置
UPLOAD_DIR = "./uploads"
os.makedirs(UPLOAD_DIR, exist_ok=True)

def parse_content_range(content_range: str) -> int:
    # 格式示例: bytes 0-499/10000
    match = re.match(r"bytes (\d+)-.*", content_range)
    if match:
        return int(match.group(1))
    return 0

app = Starlette()

@app.post("/upload")
async def upload_chunk(request: Request):
    file_id = request.headers.get("X-File-ID", "default")
    content_range = request.headers.get("Content-Range")
    
    if not content_range:
        return JSONResponse({"error": "Missing Content-Range"}, status_code=400)
        
    offset = parse_content_range(content_range)
    chunk_data = await request.body()
    
    file_path = os.path.join(UPLOAD_DIR, f"{file_id}.tmp")
    
    with open(file_path, "ab") as f:
        f.seek(offset)
        f.write(chunk_data)
        
    return JSONResponse({"status": "chunk received", "offset": offset})

上述代码展示了如何从请求中提取 Content-Range 并解析出偏移量。关键点在于使用 await request.body() 获取当前请求体的二进制数据,然后使用 Python 标准库的文件操作进行定位写入。这种方式避免了将整个文件加载到内存中,适合处理大文件。

如何管理多个并发上传会话的状态

当多个用户同时上传文件时,需要一种机制来区分不同的上传会话。通常使用唯一的 file_id 作为标识符。在 Starlette 应用中,可以使用简单的字典或外部存储(如 Redis)来跟踪每个 file_id 的上传进度。对于简单的本地实现,可以在每次收到新分片时更新一个状态文件,记录已接收的最大偏移量,以便客户端查询进度或服务器在重启后恢复状态。

Starlette 1.5.1
Starlette 1.5.1

Starlette 1.5.1 是轻量级 Python ASGI 框架与工具集,提供路由、请求响应、中间件、WebSocket 和后台任务等组件,适合构建异步 Web 服务。本下载为官方 PyPI 通用 wheel 包,可使用 pip 安装,并由包管理器处理依赖;运行应用时还需配置 ASGI 服务器。

下载

Starlette如何实现文件分片上传

import json
import os
from starlette.applications import Starlette
from starlette.responses import JSONResponse
from starlette.requests import Request

STATE_DIR = "./state"
os.makedirs(STATE_DIR, exist_ok=True)

def get_state_file(file_id: str) -> str:
    return os.path.join(STATE_DIR, f"{file_id}.json")

def load_state(file_id: str) -> dict:
    path = get_state_file(file_id)
    if os.path.exists(path):
        with open(path, "r") as f:
            return json.load(f)
    return {"file_id": file_id, "total_size": 0, "received_offset": 0}

def save_state(file_id: str, state: dict):
    path = get_state_file(file_id)
    with open(path, "w") as f:
        json.dump(state, f)

app = Starlette()

@app.post("/upload")
async def upload_chunk_with_state(request: Request):
    file_id = request.headers.get("X-File-ID", "default")
    content_range = request.headers.get("Content-Range")
    total_size_header = request.headers.get("Content-Length")
    
    state = load_state(file_id)
    
    if content_range:
        offset = parse_content_range(content_range)
        chunk_data = await request.body()
        
        file_path = os.path.join(UPLOAD_DIR, f"{file_id}.tmp")
        with open(file_path, "ab") as f:
            f.seek(offset)
            f.write(chunk_data)
        
        state["received_offset"] = max(state["received_offset"], offset + len(chunk_data))
        
    if total_size_header:
        state["total_size"] = int(total_size_header)
        
    save_state(file_id, state)
    
    return JSONResponse({"status": "ok", "progress": state["received_offset"]})

这段代码引入了一个简单的状态管理机制。通过维护一个 JSON 状态文件,应用可以追踪每个分片上传的进度。虽然这不适合高并发场景,但对于理解分片上传的状态管理逻辑非常直观。在实际生产中,建议使用 Redis 等内存数据库来替代文件系统状态存储,以提高性能和可靠性。

如何验证所有分片上传完成并合并文件

分片上传的最后一步是确认所有分片都已到达并完成合并。这通常由客户端在完成所有分片上传后发送一个特定的请求(如 POST /complete)来触发。服务器端需要检查状态文件中记录的 received_offset 是否等于预期的总大小。如果相等,则可以将临时文件重命名为最终文件名,或者执行其他清理操作。如果不想依赖客户端通知,也可以定期检查状态文件,但这种方式效率较低且复杂。

@app.post("/complete")
async def complete_upload(request: Request):
    file_id = request.headers.get("X-File-ID", "default")
    state = load_state(file_id)
    
    expected_total = state.get("total_size", 0)
    received = state.get("received_offset", 0)
    
    if received == expected_total and expected_total > 0:
        src = os.path.join(UPLOAD_DIR, f"{file_id}.tmp")
        dst = os.path.join(UPLOAD_DIR, f"{file_id}.mp4") # 假设是视频文件
        if os.path.exists(src):
            os.rename(src, dst)
            # 清理状态文件
            os.remove(get_state_file(file_id))
            return JSONResponse({"status": "completed", "file_url": f"/files/{file_id}.mp4"})
        else:
            return JSONResponse({"error": "Source file missing"}, status_code=500)
    else:
        return JSONResponse({"error": "Incomplete upload", "expected": expected_total, "received": received}, status_code=400)

此代码块展示了完成上传的逻辑。它首先加载状态,然后比较已接收的字节数和预期总大小。如果匹配,就将临时文件重命名为正式文件名。这种基于状态的验证方式简单有效,确保了数据的完整性。需要注意的是,在生产环境中,应添加更多的错误处理和日志记录,以应对网络中断或服务器崩溃等异常情况。

相关文章

PHP速学视频免费教程(入门到精通)
PHP速学视频免费教程(入门到精通)

PHP怎么学习?PHP怎么入门?PHP在哪学?PHP怎么学才快?不用担心,这里为大家提供了PHP速学教程(入门到精通),有需要的小伙伴保存下载就能学习啦!

下载

本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn

相关专题

更多
Python FastAPI异步API开发_Python怎么用FastAPI构建异步API
Python FastAPI异步API开发_Python怎么用FastAPI构建异步API

Python FastAPI 异步开发利用 async/await 关键字,通过定义异步视图函数、使用异步数据库库 (如 databases)、异步 HTTP 客户端 (如 httpx),并结合后台任务队列(如 Celery)和异步依赖项,实现高效的 I/O 密集型 API,显著提升吞吐量和响应速度,尤其适用于处理数据库查询、网络请求等耗时操作,无需阻塞主线程。

2025.12.22

119

5

Python 微服务架构与 FastAPI 框架
Python 微服务架构与 FastAPI 框架

本专题系统讲解 Python 微服务架构设计与 FastAPI 框架应用,涵盖 FastAPI 的快速开发、路由与依赖注入、数据模型验证、API 文档自动生成、OAuth2 与 JWT 身份验证、异步支持、部署与扩展等。通过实际案例,帮助学习者掌握 使用 FastAPI 构建高效、可扩展的微服务应用,提高服务响应速度与系统可维护性。

2026.02.06

614

18

Python Web框架FastAPI 全栈开发教程合集
Python Web框架FastAPI 全栈开发教程合集

以 FastAPI 为核心,讲解现代 Python Web API 的高效开发方式,涵盖路由定义与路径参数/查询参数/请求体绑定、Pydantic 模型的数据校验与序列化、依赖注入(Depends)系统的分层设计、中间件与 CORS 配置、OAuth2 + JWT 认证流程、后台任务(BackgroundTasks)、WebSocket 实时通信、SQLAlchemy 异步 ORM 集成、自动生成 OpenAPI/Swagger 交互文

2026.05.09

796

23

Python FastAPI异步微服务与高性能接口设计
Python FastAPI异步微服务与高性能接口设计

本专题聚焦 Python FastAPI 框架在高性能接口与微服务开发中的应用,讲解异步请求处理、依赖注入机制、路由设计、数据库异步操作以及接口性能优化策略。结合实际项目案例,帮助开发者构建高并发、低延迟的现代化后端服务架构。

2026.06.16

699

12

Nginx CVE-2026-123007排查与防护指南
Nginx CVE-2026-123007排查与防护指南

Nginx HTTP/2漏洞该怎么修复?本专题围绕CVE-2026-123007,介绍安全版本升级、模块兼容检查和配置恢复方法,以及日志排查、权限设置等后续加固操作,方便你按实际部署情况查找对应教程。

2026.11.20

0

8

GoFrame框架Web开发与路由中间件
GoFrame框架Web开发与路由中间件

本专题聚焦GoFrame框架的Web开发,拆解路由注册与匹配规则、请求参数获取、参数校验与中间件执行顺序,说明统一响应、JWT鉴权、文件上传与接口文档生成的落地方式,并补充优雅重启与测试实践。

2026.11.17

20

15

GoFrame框架安装与gf命令行工具
GoFrame框架安装与gf命令行工具

本专题围绕GoFrame框架的安装与工具链配置展开,讲清Go版本要求、gf命令行的安装方式、代理镜像与依赖准备,说明项目初始化、热编译、交叉编译打包的做法,并整理安装阶段的常见报错与验证步骤。

2026.11.17

60

15

GoFrame框架零基础入门
GoFrame框架零基础入门

本专题整理GoFrame框架的入门知识,从模块化设计理念、环境准备到跑通第一个Web服务,讲清目录分层、配置加载、日志与中间件的用法,并对比Gin、Go-Zero的差异,帮助Go开发者建立整体认知。

2026.11.17

80

15

SQLAlchemy 一对多关系怎么建立
SQLAlchemy 一对多关系怎么建立

SQLAlchemy 一对多关系怎么建立?本专题整理父子表外键、relationship 双向映射、关联查询、级联删除和加载优化等相关文章,帮助你理解并实现常见的 ORM 关系建模。

2026.11.17

20

10

热门下载

更多
网站特效
/
网站源码
/
网站素材
/
前端模板

精品课程

更多
相关推荐
/
热门推荐
/
最新课程