Upload de Arquivos no FastAPI com UploadFile resolve um problema recorrente em projetos Python: Receba uploads sem confiar em nome, extensão ou tipo informado pelo cliente. Este guia mostra o mecanismo, um exemplo executável e os limites que evitam uma implementação frágil.
Conceito e caso de uso
UploadFile usa um arquivo temporário com spooling e oferece uma interface assíncrona, sendo mais adequado que bytes para arquivos que podem crescer. Formulários de upload usam multipart/form-data.
Para revisar os fundamentos relacionados, consulte também o guia de APIs com FastAPI. A integração fica mais simples quando cada função recebe dependências e dados explicitamente, em vez de depender de estado global.
Exemplo prático
from typing import Annotated
from fastapi import FastAPI, File, HTTPException, UploadFile
app = FastAPI()
@app.post("/files")
async def upload(file: UploadFile):
if file.content_type not in {"image/png", "image/jpeg"}:
raise HTTPException(415, "Unsupported media type")
data = await file.read(2_000_001)
if len(data) > 2_000_000:
raise HTTPException(413, "File too large")
return {"name": file.filename, "size": len(data)}Leia com limite, gere um nome interno e armazene fora de diretórios executáveis. O content_type é apenas uma pista; valide a assinatura real quando o formato importar.
Decisões importantes
A escolha correta depende do contrato público, do volume e do comportamento em caso de falha.
Considere como a solução se comporta sob concorrência, entradas vazias e falhas parciais. Documente qualquer limite que afete consumidores e mantenha nomes que expressem a intenção.
Erros comuns
O exemplo mínimo não substitui limites, tratamento de erros e observabilidade. Não use o nome original como caminho, não aceite extensão como prova do formato e não mantenha o arquivo inteiro em memória sem limite. Faça varredura quando o risco exigir.
Evite capturar exceções sem contexto ou retornar resultados parciais como se fossem completos. Uma falha explícita costuma ser mais segura que dados silenciosamente incorretos.
Como validar
Valide o comportamento, não apenas a linha feliz. Teste arquivo válido, vazio, acima do limite, nome com travessia de diretório e conteúdo diferente do tipo declarado. Confirme também a limpeza de temporários.