FastAPI新手避坑指南：从Hello World到自动文档生成的5个常见错误

FastAPI新手避坑指南：从Hello World到自动文档生成的5个常见错误

当你第一次接触FastAPI时，可能会被它的简洁和强大所吸引。这个现代Python框架确实能让API开发变得异常简单，但新手在从Hello World到自动文档生成的路上，往往会踩中一些"坑"。本文将带你避开这些常见陷阱，让你的FastAPI之旅更加顺畅。

1. 异步函数定义不当导致的性能陷阱

很多新手在编写FastAPI路由时，对async def和普通def的区别感到困惑。不当使用异步函数可能导致性能不升反降。

# 错误示例：在同步IO操作中使用async def
@app.get("/sync-operation")
async def read_file():
    # 这是一个同步文件读取操作
    with open("large_file.txt") as f:
        content = f.read()  # 这会阻塞事件循环
    return {"content": content}

正确做法：

• 对于CPU密集型或同步IO操作，使用普通def
• 对于真正的异步IO操作（如数据库查询、HTTP请求），使用async def

# 正确示例1：同步操作使用def
@app.get("/sync-operation")
def read_file():
    with open("large_file.txt") as f:
        content = f.read()
    return {"content": content}

# 正确示例2：异步操作使用async def
@app.get("/async-operation")
async def fetch_data():
    as