在日常开发工作中，利用 FastAPI 实现文件上传已经非常便捷，但如果后端存储采用 HDFS（Hadoop 分布式文件系统），同时还要兼顾异步非阻塞的特性，就需要将多个组件串联起来。本文提供一套经过实战验证的完整流程，从环境配置到路由实现，再到生产环境的关键注意事项，逐层拆解清楚，帮助你快速搭建 FastAPI 异步文件上传至 HDFS 的服务。
整个方案大致需要完成以下几个环节：先安装基础依赖库，接着搭建 FastAPI 应用框架，然后配置一个支持异步调用的 HDFS 客户端，最后定义路由实现文件从客户端到 HDFS 的异步写入。下面逐一展开说明。
1. 环境准备与依赖安装
首先确保 Python 环境中已安装必要的库。使用 pip 一次性完成安装：
pip install fastapi uvicorn hdfs[async]
其中 hdfs[async] 会安装异步支持的扩展模块，这样才能在 FastAPI 的异步路由中不阻塞事件循环，保证高并发场景下的性能。
2. FastAPI 应用基础设置
新建一个 main.py 文件，编写基础框架代码：
from fastapi import FastAPI, File, UploadFile from fastapi.responses import JSONResponse import asyncio from hdfs import InsecureClient app = FastAPI() # HDFS 配置 HDFS_HOST = 'your_hdfs_host' HDFS_PORT = 'your_hdfs_port' # 默认端口为8020，除非你修改过 HDFS_USER = 'your_hdfs_user'
请将上述占位值替换为你实际环境的 HDFS 地址和用户名。注意，InsecureClient 不带认证功能，适用于开发测试阶段；生产环境必须换成带 Kerberos 认证的 Client。
3. 异步 HDFS 客户端配置
需要编写一个异步工厂函数来创建客户端实例，这样在路由中可以直接使用 await 调用：
async def get_hdfs_client():
client = InsecureClient(HDFS_HOST, HDFS_PORT, user=HDFS_USER)
return client
虽然 InsecureClient 本身并非异步实现，但通过 async def 封装，为后续可能的异步操作预留了扩展空间。实际文件上传操作可以依赖 hdfs[async] 提供的异步接口。
4. 实现文件上传的异步路由
核心逻辑集中在此——定义一个 /upload/ 路由，接收上传文件并异步写入 HDFS：
@app.post("/upload/")
async def upload_file(file: UploadFile = File(...)):
try:
client = await get_hdfs_client()
# 使用临时文件作为中介（可选），也可以直接用流式写入避免磁盘 I/O
with tempfile.NamedTemporaryFile(delete=False) as tmp_file:
tmp_file.write(await file.read())
tmp_filename = tmp_file.name
await client.upload(tmp_filename, f'/user/your_hdfs_user/{file.filename}')
os.remove(tmp_filename)
return JSONResponse(content={"message": "File uploaded successfully", "filename": file.filename})
except Exception as e:
return JSONResponse(content={"message": str(e)}, status_code=500)
这段代码先将上传的文件内容全部读入内存，再写入临时文件，最后通过 client.upload 推送到 HDFS。使用临时文件落地的好处是容错性较高，但如果文件体积很大，建议跳过临时文件，直接从 UploadFile 对象流式读取并写入 HDFS，避免内存和磁盘的双重开销。这需要更精细的流控制，后文会给出建议。
5. 运行你的 FastAPI 应用
使用 uvicorn 启动服务，开发阶段可加上 --reload 参数方便调试：
uvicorn main:app --reload
生产环境注意事项
- 安全认证：上述示例中使用的
InsecureClient没有认证机制，仅适合本地或内网开发。生产环境必须替换为hdfs.Client并配置 Kerberos 认证，否则任何客户端都可以向你的 HDFS 写入文件。 - 错误处理与日志：示例中仅用简单的 try-except 返回 500 错误，实际项目应加入结构化日志和更细粒度的异常分类，例如 HDFS 连接超时、权限不足、文件已存在等场景。
- 性能优化：对于超大文件，临时文件可能成为性能瓶颈。建议直接使用
UploadFile.file对象读取流，并结合 HDFS 客户端的流式写入方法（如client.write），边读边写，从而降低内存占用并提升吞吐量。
以上框架已经跑通基本上传链路，你可根据业务需求调整文件存储路径、认证方式、错误响应格式等。真正投入生产时，别忘了补充限流、文件类型校验、大小限制等常规防护措施。做好这些，一个健壮的 FastAPI 异步文件上传至 HDFS 的服务就基本成型了。
