FastAPI：构建高性能 Web API 一个现代、快速的Web框架，用于构建API，它支持异步编码，自动化的交互文档

一、快速上手 FastAPI：构建高性能 Web API

想快速创建一个高效又安全的Web API？那FastAPI绝对是你的不二之选。这个框架不仅超级快，而且它自带了自动生成文档的功能，让你省去了很多麻烦。更重要的是，它对异步编程的支持非常好，能帮你在高并发场景下节省资源。接下来，就让我们看看怎么用FastAPI来打造一个简单的API。

1、安装 FastAPI 和 Uvicorn

要开始玩转FastAPI，你得先把它装到你的电脑里。打开命令行工具，输入下面这行代码就可以安装FastAPI和Uvicorn。Uvicorn是用来运行FastAPI应用的服务器。

pip install fastapi uvicorn

安装完成后，你就准备好开始编码啦！

2、创建第一个 API 端点

咱们从最基础的开始，创建一个返回“Hello, World!”的API端点。新建一个Python文件，比如叫main.py，然后把下面这段代码粘进去。

from fastapi import FastAPI



app = FastAPI()



@app.get("/")

def read_root():

    return {"message": "Hello, World!"}

这段代码做了啥呢？首先我们导入了FastAPI类，接着创建了一个app实例。然后通过装饰器@app.get("/")定义了一个GET请求的路由，当访问根路径时就会调用read_root函数，返回一个字典，里面包含了我们的问候语。

要启动这个API，回到命令行，运行uvicorn main:app --reload。--reload参数可以让Uvicorn在代码变化时自动重启服务器，方便调试。

3、异步函数的魅力

FastAPI天生支持异步编程，这可是个大杀器。异步函数可以同时处理多个任务，不会因为等待某个操作完成而阻塞整个程序。修改刚才的read_root函数，加上async关键字试试看。

@app.get("/")

async def read_root():

    return {"message": "Hello, async world!"}'

现在这个函数变成了异步的，虽然看起来没多大区别，但在处理I/O密集型任务（比如数据库查询、网络请求）时，它的性能提升可就不是一点两点了。

4、添加路径参数

有时候你想让API更灵活一些，比如根据不同的用户ID返回特定的信息。这时候就可以用到路径参数了。看看下面的例子：

@app.get("/items/{item_id}")

async def read_item(item_id: int):

    return {"item_id": item_id}

这里{item_id}就是路径参数，它会自动转换成整数类型。这样你就可以通过/items/1这样的URL来获取特定项的信息了。

温馨提示：记得检查路径参数的数据类型哦，要是传入了不符合要求的值，FastAPI会帮你自动返回422错误，不过最好还是自己提前做好验证。

5、查询参数与默认值

除了路径参数，你还可能需要根据用户的额外需求来调整返回的内容。查询参数就能派上用场了。来看个例子：

from typing import Union



@app.get("/items/")

async def read_item(q: Union[str, None] = None):

    if q:

        return {"q": q}

    return {"message": "No query parameter"}

q就是一个查询参数，如果用户在请求中提供了?q=something，那么q就会有值；如果没有提供，q就会是None。为了不让代码出错，我们给q设了个默认值None，并使用了typing.Union来告诉FastAPI这个参数可能是字符串也可能是None。

6、请求体与数据校验

当你要接收用户提交的数据时，就需要用到请求体了。FastAPI结合Pydantic库，可以轻松地定义数据模型，并自动进行数据校验。举个栗子：

from pydantic import BaseModel



class Item(BaseModel):

    name: str

    description: Union[str, None] = None

    price: float

    tax: Union[float, None] = None



@app.post("/items/")

async def create_item(item: Item):

    return item

Item类定义了请求体的结构，每个字段都指定了类型，还可以设置默认值。当你POST一个JSON对象到/items/时，FastAPI会自动解析并验证数据，只有符合模型定义的数据才会被接受。

7、自动化交互文档

说到这儿，不得不提一下FastAPI最酷炫的功能之一——自动化交互文档。只要你按照规范定义了API，FastAPI就会自动生成Swagger UI或ReDoc界面。这些界面上不仅可以查看API文档，还能直接测试API功能，简直不要太方便。

访问http://127.0.0.1:8000/docs或者http://127.0.0.1:8000/redoc就能看到它们了。是不是超省心？

8、安全性考量

构建API的时候，安全性绝对不能忽视。FastAPI提供了多种方式来保护你的API，比如OAuth2认证、依赖注入等。你可以根据实际需求选择合适的安全措施。比如说，想要限制某些敏感接口只能由授权用户访问，就可以用Depends来添加认证逻辑。

from fastapi import Depends, HTTPException, status

from fastapi.security import OAuth2PasswordBearer



oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")



async def get_current_user(token: str = Depends(oauth2_scheme)):

    # 这儿写你的认证逻辑

    fake_user_db = {"johndoe": "secret"}

    user = fake_user_db.get(token)

    if not user:

        raise HTTPException(

            status_code=status.HTTP_401_UNAUTHORIZED,

            detail="Invalid authentication credentials",

            headers={"WWW-Authenticate": "Bearer"},

        )

    return user



@app.get("/users/me")

async def read_users_me(current_user: str = Depends(get_current_user)):

    return {"user": current_user}

这段代码展示了如何用OAuth2PasswordBearer来获取用户提供的Token，并通过Depends将其传递给认证函数。如果认证失败，就会抛出异常，阻止未授权的访问。

二、fastapi 最佳实践方式

以下是使用FastAPI时的一些最佳实践方式，确保你在构建应用时能够遵循fastapi 最佳实践：

项目结构：
保持项目结构一致和可预测是非常重要的。一个清晰的项目结构有助于其他开发者通过查看项目结构就能对项目内容有所了解，这是fastapi 最佳实践的第一步。
使用Pydantic进行数据验证：
过度使用Pydantic进行数据验证是一个好习惯，它可以帮助确保数据的准确性和安全性，这是fastapi 最佳实践中的关键一环。
依赖注入：
使用依赖注入进行数据验证，而不是直接在路由函数中进行验证。这样可以提高代码的可重用性和可测试性，是fastapi 最佳实践中的一个重要方面。
链式依赖：
依赖可以被链式调用，并且依赖调用的结果会被缓存，这有助于提高性能，是fastapi 最佳实践中的一个高效策略。
遵循REST原则：
设计API时遵循REST原则，保持接口的无状态性、可缓存性等特性，这是fastapi 最佳实践中的基本要求。
异步路由：
如果你的路由中只有阻塞型I/O操作，那么无需将其设置为异步，这是fastapi 最佳实践中的一个性能优化技巧。
自定义基础模型：
从项目一开始就定义自定义的基础模型，这有助于保持代码的一致性和可维护性，是fastapi 最佳实践中的一个关键步骤。
文档生成：
FastAPI自动生成API文档，确保从项目开始就启用和维护这些文档，这是fastapi 最佳实践中的一个基本实践。
使用Pydantic的BaseSettings管理配置：
使用Pydantic的BaseSettings来管理项目配置，这样可以保持配置的一致性和安全性，是fastapi 最佳实践中的一个推荐做法。
数据库命名约定：
为数据库设置命名约定，以保持数据库结构的一致性，这是fastapi 最佳实践中的一个数据库管理技巧。
异步测试客户端：
从项目一开始就设置异步测试客户端，这有助于确保测试的准确性和效率，是fastapi 最佳实践中的一个测试策略。
背景任务：
使用BackgroundTasks而不是直接使用asyncio.create_task，这样可以更好地管理后台任务，是fastapi 最佳实践中的一个任务管理技巧。
类型注解：
在FastAPI中使用类型注解是非常重要的，它有助于提高代码的可读性和可维护性，是fastapi 最佳实践中的一个编码标准。
文件分块保存：
当处理大文件时，应该分块保存文件，以避免内存溢出，这是fastapi 最佳实践中的一个文件处理技巧。
动态Pydantic字段：
小心使用动态Pydantic字段，因为它们可能会增加代码的复杂性，这是fastapi 最佳实践中的一个注意事项。
SQL-first, Pydantic-second：
在设计数据库模型时，应该先考虑SQL模型，然后再考虑Pydantic模型，这是fastapi最佳实践中的一个模型设计原则。
自定义Pydantic验证器：
在自定义Pydantic验证器时，如果直接面向客户端，应该抛出ValueError，以提供更详细的错误信息，这是fastapi最佳实践中的一个验证技巧。
同步SDK的使用：
如果必须使用同步SDK，应该在线程池中运行它，以避免阻塞异步事件循环，这是fastapi 最佳实践中的一个异步处理技巧。
代码格式化和 linting：
使用代码格式化工具如black和ruff，以及linting工具来保持代码的整洁和一致性，这是fastapi 最佳实践中的一个代码管理实践。