FastUI 项目中实现文件下载功能的技术实践

前言

在Web应用开发中，文件下载是一个常见需求。本文将详细介绍如何在FastUI项目中实现文件下载功能，包括动态生成文件和静态文件下载的实现方式。

核心实现方案

1. 基础下载端点实现

FastUI项目可以通过创建专门的API端点来实现文件下载功能。以下是两种常见的实现方式：

流式响应下载：

@app.get("/api/dl_file_stream")
async def dl_file_stream():
    file_bytes, filename = generate_file()
    
    async def iterfile():
        yield file_bytes.getvalue()

    response = StreamingResponse(iterfile(), media_type="application/octet-stream")
    response.headers["Content-Disposition"] = f"attachment; filename={filename}"
    return response

静态文件下载：

@app.get("/api/dl_file_static")
async def dl_file_static():
    file_bytes, filename = generate_file()
    
    with tempfile.NamedTemporaryFile(delete=False) as temp_file:
        temp_file.write(file_bytes.getvalue())

    return FileResponse(temp_file.name, filename=filename)

2. 动态文件生成

在实际应用中，我们经常需要动态生成文件内容。可以创建一个通用的文件生成函数：

def generate_file(extra_text=None, override_filename=None):
    content = f"文件内容\n{extra_text or '默认内容'}"
    file_bytes = io.BytesIO(content.encode())
    filename = override_filename or "default_filename.txt"
    return file_bytes, filename

3. 统一端点实现

为了更灵活地处理不同下载需求，可以创建一个统一的端点，通过路径参数和查询参数控制下载行为：

@app.get("/api/dl_file/{source}")
async def dl_file(source: str, filename: str = None):
    file_bytes, filename = generate_file(f"生成方式: {source}", filename)
    
    if source == 'stream':
        async def iterfile():
            yield file_bytes.getvalue()
        response = StreamingResponse(iterfile(), media_type="application/octet-stream")
        response.headers["Content-Disposition"] = f"attachment; filename={filename}"
        return response
    elif source == 'static':
        with tempfile.NamedTemporaryFile(delete=False) as temp_file:
            temp_file.write(file_bytes.getvalue())
        return FileResponse(temp_file.name, filename=filename)

前端集成

在FastUI前端，可以通过Link组件创建下载链接：

c.Link(
    components=[c.Text(text='下载文件')],
    on_click=GoToEvent(url='/api/dl_file/stream', target='_blank'),
)

注意事项

1. 文件处理完成后，特别是临时文件，应该考虑清理机制
2. 对于大文件，流式响应(StreamingResponse)是更好的选择，可以降低内存消耗
3. 设置正确的Content-Disposition头部确保浏览器正确处理下载行为
4. 考虑添加用户认证和权限控制，防止未授权下载

总结

FastUI项目通过结合FastAPI的文件响应功能，可以灵活实现各种文件下载需求。开发者可以根据实际场景选择流式响应或静态文件方式，并通过参数化设计提高接口的复用性。这种实现方式既保持了FastUI的简洁性，又满足了实际业务中对文件下载的各种需求。