设置和环境变量¶

在很多情况下，你的应用程序可能需要一些外部设置或配置，例如密钥、数据库凭据、电子邮件服务的凭据等。

这些设置大多数是可变的（可以更改），比如数据库 URL。而许多设置可能非常敏感，比如密钥。

出于这个原因，通常将它们以环境变量的形式提供，供应用程序读取。

提示

要理解环境变量，你可以阅读环境变量。

类型和验证¶

这些环境变量只能处理文本字符串，因为它们在 Python 之外，并且必须与其他程序和系统的其余部分（甚至不同操作系统，如 Linux、Windows、macOS）兼容。

这意味着从环境变量中读取的任何值在 Python 中都将是 str 类型，任何转换为不同类型或任何验证都必须在代码中完成。

Pydantic `Settings`¶

幸运的是，Pydantic 提供了一个强大的工具，可以通过 Pydantic: Settings management 来处理来自环境变量的这些设置。

安装 `pydantic-settings`¶

首先，请确保你创建了虚拟环境，激活它，然后安装 pydantic-settings 包。

$ pip install pydantic-settings
---> 100%

当你使用 all 附加组件进行安装时，它也包含在内：

$ pip install "fastapi[all]"
---> 100%

创建 `Settings` 对象¶

从 Pydantic 导入 BaseSettings 并创建一个子类，这与 Pydantic 模型非常相似。

与 Pydantic 模型一样，你用类型注解声明类属性，并可能加上默认值。

你可以使用 Pydantic 模型的所有相同验证功能和工具，例如不同的数据类型和使用 Field() 进行的附加验证。

Python 3.9+

from fastapi import FastAPI
from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    app_name: str = "Awesome API"
    admin_email: str
    items_per_user: int = 50


settings = Settings()
app = FastAPI()


@app.get("/info")
async def info():
    return {
        "app_name": settings.app_name,
        "admin_email": settings.admin_email,
        "items_per_user": settings.items_per_user,
    }

提示

如果你想要一个可以快速复制粘贴的示例，请不要使用此示例，请使用下面的最后一个示例。

然后，当你创建该 Settings 类的实例时（在本例中，在 settings 对象中），Pydantic 将以不区分大小写的方式读取环境变量，因此，一个大写的变量 APP_NAME 仍然会为属性 app_name 读取。

接下来它将转换和验证数据。因此，当你使用该 settings 对象时，你将拥有你声明的类型的数据（例如，items_per_user 将是 int 类型）。

使用 `settings`¶

然后你就可以在你的应用程序中使用新的 settings 对象了。

Python 3.9+

from fastapi import FastAPI
from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    app_name: str = "Awesome API"
    admin_email: str
    items_per_user: int = 50


settings = Settings()
app = FastAPI()


@app.get("/info")
async def info():
    return {
        "app_name": settings.app_name,
        "admin_email": settings.admin_email,
        "items_per_user": settings.items_per_user,
    }

运行服务器¶

接下来，你将运行服务器，并将配置作为环境变量传递，例如，你可以使用以下方式设置 ADMIN_EMAIL 和 APP_NAME：

$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py

<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

提示

要为单个命令设置多个环境变量，只需用空格分隔它们，并将它们全部放在命令之前。

然后 admin_email 设置将设置为 "deadpool@example.com"。

app_name 将是 "ChimichangApp"。

而 items_per_user 将保留其默认值 50。

另一个模块中的设置¶

你可以将这些设置放在另一个模块文件中，就像你在大型应用程序 - 多个文件中看到的那样。

例如，你可能有一个名为 config.py 的文件，其中包含：

Python 3.9+

from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    app_name: str = "Awesome API"
    admin_email: str
    items_per_user: int = 50


settings = Settings()

然后在一个名为 main.py 的文件中使用它：

Python 3.9+

from fastapi import FastAPI

from .config import settings

app = FastAPI()


@app.get("/info")
async def info():
    return {
        "app_name": settings.app_name,
        "admin_email": settings.admin_email,
        "items_per_user": settings.items_per_user,
    }

提示

你还需要一个名为 __init__.py 的文件，就像你在大型应用程序 - 多个文件中看到的那样。

依赖项中的设置¶

在某些情况下，将设置从依赖项提供可能很有用，而不是拥有一个全局的 settings 对象并在任何地方都使用它。

这在测试期间尤其有用，因为它非常容易用你自己的自定义设置覆盖依赖项。

配置文件¶

承接上一个示例，你的 config.py 文件可能看起来像这样：

Python 3.9+

from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    app_name: str = "Awesome API"
    admin_email: str
    items_per_user: int = 50

🤓 其他版本和变体

Python 3.9+ - 非注解

提示

如果可能，请优先使用 Annotated 版本。

from pydantic_settings import BaseSettings


class Settings(BaseSettings):
    app_name: str = "Awesome API"
    admin_email: str
    items_per_user: int = 50

请注意，我们不再创建一个默认实例 settings = Settings()。

主应用文件¶

现在我们创建一个返回新的 config.Settings() 的依赖项。

Python 3.9+

from functools import lru_cache
from typing import Annotated

from fastapi import Depends, FastAPI

from .config import Settings

app = FastAPI()


@lru_cache
def get_settings():
    return Settings()


@app.get("/info")
async def info(settings: Annotated[Settings, Depends(get_settings)]):
    return {
        "app_name": settings.app_name,
        "admin_email": settings.admin_email,
        "items_per_user": settings.items_per_user,
    }

🤓 其他版本和变体

Python 3.9+ - 非注解

提示

如果可能，请优先使用 Annotated 版本。

from functools import lru_cache

from fastapi import Depends, FastAPI

from .config import Settings

app = FastAPI()


@lru_cache
def get_settings():
    return Settings()


@app.get("/info")
async def info(settings: Settings = Depends(get_settings)):
    return {
        "app_name": settings.app_name,
        "admin_email": settings.admin_email,
        "items_per_user": settings.items_per_user,
    }

提示

我们将在稍后讨论 @lru_cache。

现在你可以假设 get_settings() 是一个普通函数。

然后我们可以将它作为依赖项从*路径操作函数*中请求，并在需要它的任何地方使用它。

Python 3.9+

from functools import lru_cache
from typing import Annotated

from fastapi import Depends, FastAPI

from .config import Settings

app = FastAPI()


@lru_cache
def get_settings():
    return Settings()


@app.get("/info")
async def info(settings: Annotated[Settings, Depends(get_settings)]):
    return {
        "app_name": settings.app_name,
        "admin_email": settings.admin_email,
        "items_per_user": settings.items_per_user,
    }

🤓 其他版本和变体

Python 3.9+ - 非注解

提示

如果可能，请优先使用 Annotated 版本。

from functools import lru_cache

from fastapi import Depends, FastAPI

from .config import Settings

app = FastAPI()


@lru_cache
def get_settings():
    return Settings()


@app.get("/info")
async def info(settings: Settings = Depends(get_settings)):
    return {
        "app_name": settings.app_name,
        "admin_email": settings.admin_email,
        "items_per_user": settings.items_per_user,
    }

设置与测试¶

然后，通过为 get_settings 创建一个依赖项覆盖，在测试期间提供不同的设置对象将非常容易：

Python 3.9+

from fastapi.testclient import TestClient

from .config import Settings
from .main import app, get_settings

client = TestClient(app)


def get_settings_override():
    return Settings(admin_email="testing_admin@example.com")


app.dependency_overrides[get_settings] = get_settings_override


def test_app():
    response = client.get("/info")
    data = response.json()
    assert data == {
        "app_name": "Awesome API",
        "admin_email": "testing_admin@example.com",
        "items_per_user": 50,
    }

🤓 其他版本和变体

Python 3.9+ - 非注解

提示

如果可能，请优先使用 Annotated 版本。

from fastapi.testclient import TestClient

from .config import Settings
from .main import app, get_settings

client = TestClient(app)


def get_settings_override():
    return Settings(admin_email="testing_admin@example.com")


app.dependency_overrides[get_settings] = get_settings_override


def test_app():
    response = client.get("/info")
    data = response.json()
    assert data == {
        "app_name": "Awesome API",
        "admin_email": "testing_admin@example.com",
        "items_per_user": 50,
    }

在依赖项覆盖中，我们在创建新的 Settings 对象时为 admin_email 设置了一个新值，然后返回该新对象。

然后我们可以测试它是否被使用。

读取 `.env` 文件¶

如果你有很多设置，这些设置可能会在不同环境中发生很大变化，那么将它们放在一个文件中，然后从中读取，就像它们是环境变量一样，可能很有用。

这种做法足够普遍，以至于有一个名字，这些环境变量通常放在一个名为 .env 的文件中，而该文件被称为“dotenv”。

提示

在类 Unix 系统（如 Linux 和 macOS）中，以点（.）开头的文件是隐藏文件。

但一个 dotenv 文件实际上不必具有这个确切的文件名。

Pydantic 通过一个外部库支持从这些类型的文件中读取。你可以在 Pydantic Settings: Dotenv (.env) support 中了解更多。

提示

为了实现这一点，你需要 pip install python-dotenv。

`.env` 文件¶

你可以有一个包含以下内容的 .env 文件：

ADMIN_EMAIL="deadpool@example.com"
APP_NAME="ChimichangApp"

从 `.env` 读取设置¶

然后更新你的 config.py 文件，使其包含：

Python 3.9+

from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    app_name: str = "Awesome API"
    admin_email: str
    items_per_user: int = 50

    model_config = SettingsConfigDict(env_file=".env")

🤓 其他版本和变体

Python 3.9+ - 非注解

提示

如果可能，请优先使用 Annotated 版本。

from pydantic_settings import BaseSettings, SettingsConfigDict


class Settings(BaseSettings):
    app_name: str = "Awesome API"
    admin_email: str
    items_per_user: int = 50

    model_config = SettingsConfigDict(env_file=".env")

提示

model_config 属性仅用于 Pydantic 配置。你可以在 Pydantic: Concepts: Configuration 中了解更多。

在这里，我们在 Pydantic Settings 类内部定义了 env_file 配置，并将其值设置为我们要使用的 dotenv 文件的文件名。

使用 `lru_cache` 仅创建一次 `Settings`¶

从磁盘读取文件通常是一个耗时（缓慢）的操作，所以你可能希望只执行一次，然后重用相同的设置对象，而不是为每个请求都读取它。

但是每次我们执行

Settings()

都会创建一个新的 Settings 对象，并在创建时再次读取 .env 文件。

如果依赖项函数只是这样：

def get_settings():
    return Settings()

我们会在每个请求时创建该对象，并且会在每个请求时读取 .env 文件。 ⚠️

但是，因为我们使用了顶部的 @lru_cache 装饰器，所以 Settings 对象将在第一次调用时仅创建一次。 ✔️

Python 3.9+

from functools import lru_cache
from typing import Annotated

from fastapi import Depends, FastAPI

from . import config

app = FastAPI()


@lru_cache
def get_settings():
    return config.Settings()


@app.get("/info")
async def info(settings: Annotated[config.Settings, Depends(get_settings)]):
    return {
        "app_name": settings.app_name,
        "admin_email": settings.admin_email,
        "items_per_user": settings.items_per_user,
    }

🤓 其他版本和变体

Python 3.9+ - 非注解

提示

如果可能，请优先使用 Annotated 版本。

from functools import lru_cache

from fastapi import Depends, FastAPI

from . import config

app = FastAPI()


@lru_cache
def get_settings():
    return config.Settings()


@app.get("/info")
async def info(settings: config.Settings = Depends(get_settings)):
    return {
        "app_name": settings.app_name,
        "admin_email": settings.admin_email,
        "items_per_user": settings.items_per_user,
    }

然后，对于后续请求中的依赖项对 get_settings() 的任何调用，它将返回第一次调用时返回的同一个对象，而不是执行 get_settings() 的内部代码并创建一个新的 Settings 对象，一遍又一遍地返回。

`lru_cache` 技术细节¶

@lru_cache 会修改它所装饰的函数，使其返回第一次返回的值，而不是重新计算它，每次都执行函数的代码。

因此，它下面的函数将为每种参数组合执行一次。然后，当函数被调用时，每次使用完全相同的参数组合，都将使用这些参数组合返回的值，一遍又一遍。

例如，如果你有一个函数：

@lru_cache
def say_hi(name: str, salutation: str = "Ms."):
    return f"Hello {salutation} {name}"

你的程序可能这样执行：

sequenceDiagram

participant code as Code
participant function as say_hi()
participant execute as Execute function

    rect rgba(0, 255, 0, .1)
        code ->> function: say_hi(name="Camila")
        function ->> execute: execute function code
        execute ->> code: return the result
    end

    rect rgba(0, 255, 255, .1)
        code ->> function: say_hi(name="Camila")
        function ->> code: return stored result
    end

    rect rgba(0, 255, 0, .1)
        code ->> function: say_hi(name="Rick")
        function ->> execute: execute function code
        execute ->> code: return the result
    end

    rect rgba(0, 255, 0, .1)
        code ->> function: say_hi(name="Rick", salutation="Mr.")
        function ->> execute: execute function code
        execute ->> code: return the result
    end

    rect rgba(0, 255, 255, .1)
        code ->> function: say_hi(name="Rick")
        function ->> code: return stored result
    end

    rect rgba(0, 255, 255, .1)
        code ->> function: say_hi(name="Camila")
        function ->> code: return stored result
    end

在我们的依赖项 get_settings() 的情况下，该函数甚至不接受任何参数，因此它始终返回相同的值。

这样，它的行为几乎就像一个全局变量。但因为它使用了依赖项函数，所以我们可以轻松地在测试中覆盖它。

@lru_cache 是 functools 的一部分，而 functools 是 Python 标准库的一部分。你可以在 Python @lru_cache 文档中了解更多。

总结¶

你可以使用 Pydantic Settings 来处理应用程序的设置或配置，并利用 Pydantic 模型的所有强大功能。

通过使用依赖项，你可以简化测试。
你可以使用 .env 文件。
使用 @lru_cache 可以让你避免为每个请求重复读取 dotenv 文件，同时允许你在测试期间覆盖它。

设置和环境变量¶

类型和验证¶

Pydantic Settings¶

安装 pydantic-settings¶

创建 Settings 对象¶

使用 settings¶

运行服务器¶

另一个模块中的设置¶

依赖项中的设置¶

配置文件¶

主应用文件¶

设置与测试¶

读取 .env 文件¶

.env 文件¶

从 .env 读取设置¶

使用 lru_cache 仅创建一次 Settings¶

lru_cache 技术细节¶

总结¶

Pydantic `Settings`¶

安装 `pydantic-settings`¶

创建 `Settings` 对象¶

使用 `settings`¶

读取 `.env` 文件¶

`.env` 文件¶

从 `.env` 读取设置¶

使用 `lru_cache` 仅创建一次 `Settings`¶

`lru_cache` 技术细节¶