Python基于FastAPI与HDFS的异步文件上传实现

在日常开发工作中，利用 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 的服务就基本成型了。