[
  {
    "path": "AGENTS.md",
    "content": "# FastAPI Best Practices for AI Agents\n\nThis document provides guidelines for AI agents working on FastAPI projects. Follow these conventions when writing or modifying code.\n\n## Project Structure\n\nOrganize code by domain, not by file type.\n\n```\nsrc/\n├── {domain}/           # e.g., auth/, posts/, aws/\n│   ├── router.py       # API endpoints\n│   ├── schemas.py      # Pydantic models\n│   ├── models.py       # Database models\n│   ├── service.py      # Business logic\n│   ├── dependencies.py # Route dependencies\n│   ├── config.py       # Environment variables\n│   ├── constants.py    # Constants and error codes\n│   ├── exceptions.py   # Domain-specific exceptions\n│   └── utils.py        # Helper functions\n├── config.py           # Global configuration\n├── models.py           # Global models\n├── exceptions.py       # Global exceptions\n├── database.py         # Database connection\n└── main.py             # FastAPI app initialization\n```\n\n**Import Convention**: Use explicit module names when importing across domains:\n```python\nfrom src.auth import constants as auth_constants\nfrom src.notifications import service as notification_service\n```\n\n## Async Routes\n\n### Rules\n- `async def` routes: Use ONLY non-blocking I/O (`await` calls)\n- `def` routes (sync): Use for blocking I/O (runs in threadpool automatically)\n- CPU-intensive work: Offload to Celery or multiprocessing\n\n### Common Mistakes to Avoid\n```python\n# WRONG: Blocking call in async route\n@router.get(\"/bad\")\nasync def bad_route():\n    time.sleep(10)  # Blocks entire event loop\n    return {\"status\": \"done\"}\n\n# CORRECT: Non-blocking in async route\n@router.get(\"/good\")\nasync def good_route():\n    await asyncio.sleep(10)\n    return {\"status\": \"done\"}\n\n# CORRECT: Sync route for blocking operations\n@router.get(\"/also-good\")\ndef sync_route():\n    time.sleep(10)  # Runs in threadpool\n    return {\"status\": \"done\"}\n```\n\n### Using Sync Libraries in Async Context\n```python\nfrom fastapi.concurrency import run_in_threadpool\n\n@router.get(\"/\")\nasync def call_sync_library():\n    result = await run_in_threadpool(sync_client.make_request, data=my_data)\n    return result\n```\n\n## Pydantic\n\n### Use Built-in Validators\n```python\nfrom pydantic import BaseModel, EmailStr, Field\n\nclass UserCreate(BaseModel):\n    username: str = Field(min_length=1, max_length=128, pattern=\"^[A-Za-z0-9-_]+$\")\n    email: EmailStr\n    age: int = Field(ge=18)\n```\n\n### Custom Base Model\nCreate a shared base model for consistent serialization:\n```python\nfrom pydantic import BaseModel, ConfigDict\n\nclass CustomModel(BaseModel):\n    model_config = ConfigDict(\n        json_encoders={datetime: datetime_to_gmt_str},\n        populate_by_name=True,\n    )\n```\n\n### Split BaseSettings by Domain\n```python\n# src/auth/config.py\nclass AuthConfig(BaseSettings):\n    JWT_ALG: str\n    JWT_SECRET: str\n    JWT_EXP: int = 5\n\nauth_settings = AuthConfig()\n```\n\n## Dependencies\n\n### Use for Validation, Not Just DI\n```python\nasync def valid_post_id(post_id: UUID4) -> dict[str, Any]:\n    post = await service.get_by_id(post_id)\n    if not post:\n        raise PostNotFound()\n    return post\n\n@router.get(\"/posts/{post_id}\")\nasync def get_post(post: dict[str, Any] = Depends(valid_post_id)):\n    return post\n```\n\n### Chain Dependencies\n```python\nasync def valid_owned_post(\n    post: dict[str, Any] = Depends(valid_post_id),\n    token_data: dict[str, Any] = Depends(parse_jwt_data),\n) -> dict[str, Any]:\n    if post[\"creator_id\"] != token_data[\"user_id\"]:\n        raise UserNotOwner()\n    return post\n```\n\n### Key Rules\n- Dependencies are cached per request (same dependency called multiple times = one execution)\n- Prefer `async` dependencies to avoid threadpool overhead\n- Use consistent path variable names to enable dependency reuse\n\n## REST Conventions\n\nUse consistent path variable names for dependency reuse:\n```python\n# Both use profile_id, enabling shared valid_profile_id dependency\nGET /profiles/{profile_id}\nGET /creators/{profile_id}\n```\n\n## Database\n\n### Naming Conventions\n- Use `lower_case_snake` format\n- Singular table names: `post`, `user`, `post_like`\n- Group related tables with prefix: `payment_account`, `payment_bill`\n- DateTime suffix: `_at` (e.g., `created_at`)\n- Date suffix: `_date` (e.g., `birth_date`)\n\n### Set Explicit Index Names\n```python\nPOSTGRES_INDEXES_NAMING_CONVENTION = {\n    \"ix\": \"%(column_0_label)s_idx\",\n    \"uq\": \"%(table_name)s_%(column_0_name)s_key\",\n    \"ck\": \"%(table_name)s_%(constraint_name)s_check\",\n    \"fk\": \"%(table_name)s_%(column_0_name)s_fkey\",\n    \"pk\": \"%(table_name)s_pkey\",\n}\n```\n\n### SQL-First Approach\nPrefer database-level operations for:\n- Complex joins\n- Data aggregation\n- Building nested JSON responses\n\n## Migrations (Alembic)\n\n- Keep migrations static and reversible\n- Use descriptive file names: `2022-08-24_post_content_idx.py`\n- Configure in alembic.ini:\n  ```ini\n  file_template = %%(year)d-%%(month).2d-%%(day).2d_%%(slug)s\n  ```\n\n## API Documentation\n\n### Hide Docs in Production\n```python\nSHOW_DOCS_ENVIRONMENT = (\"local\", \"staging\")\n\napp_configs = {\"title\": \"My API\"}\nif ENVIRONMENT not in SHOW_DOCS_ENVIRONMENT:\n    app_configs[\"openapi_url\"] = None\n\napp = FastAPI(**app_configs)\n```\n\n### Document Endpoints Properly\n```python\n@router.post(\n    \"/endpoints\",\n    response_model=DefaultResponseModel,\n    status_code=status.HTTP_201_CREATED,\n    description=\"Description of the endpoint\",\n    tags=[\"Category\"],\n    responses={\n        status.HTTP_201_CREATED: {\"model\": CreatedResponse},\n        status.HTTP_400_BAD_REQUEST: {\"model\": ErrorResponse},\n    },\n)\n```\n\n## Testing\n\nUse async test client from the start:\n```python\nimport pytest\nfrom httpx import AsyncClient, ASGITransport\n\n@pytest.fixture\nasync def client():\n    async with AsyncClient(\n        transport=ASGITransport(app=app),\n        base_url=\"http://test\"\n    ) as client:\n        yield client\n\n@pytest.mark.asyncio\nasync def test_endpoint(client: AsyncClient):\n    resp = await client.post(\"/posts\")\n    assert resp.status_code == 201\n```\n\n## Linting\n\nUse ruff for formatting and linting:\n```shell\nruff check --fix src\nruff format src\n```\n\n## Quick Reference\n\n| Scenario | Solution |\n|----------|----------|\n| Non-blocking I/O | `async def` route with `await` |\n| Blocking I/O | `def` route (sync) |\n| Sync library in async | `run_in_threadpool()` |\n| CPU-intensive | Celery/multiprocessing |\n| Request validation | Dependencies with DB checks |\n| Shared validation | Chain dependencies |\n| Config per domain | Separate `BaseSettings` classes |\n| Complex DB queries | SQL with JSON aggregation |\n"
  },
  {
    "path": "README.md",
    "content": "## FastAPI Best Practices <!-- omit from toc -->\nOpinionated list of best practices and conventions we use at our startups.\n\nAfter several years of building production systems,\nwe've made both good and bad decisions that significantly impacted our developer experience.\nHere are some lessons worth sharing.\n\n*[简体中文](./README_ZH.md)*\n\n## Contents  <!-- omit from toc -->\n- [Project Structure](#project-structure)\n- [Async Routes](#async-routes)\n  - [I/O Intensive Tasks](#io-intensive-tasks)\n  - [CPU Intensive Tasks](#cpu-intensive-tasks)\n- [Pydantic](#pydantic)\n  - [Excessively use Pydantic](#excessively-use-pydantic)\n  - [Custom Base Model](#custom-base-model)\n  - [Decouple Pydantic BaseSettings](#decouple-pydantic-basesettings)\n- [Dependencies](#dependencies)\n  - [Beyond Dependency Injection](#beyond-dependency-injection)\n  - [Chain Dependencies](#chain-dependencies)\n  - [Decouple \\& Reuse dependencies. Dependency calls are cached](#decouple--reuse-dependencies-dependency-calls-are-cached)\n  - [Prefer `async` dependencies](#prefer-async-dependencies)\n- [Miscellaneous](#miscellaneous)\n  - [Follow the REST](#follow-the-rest)\n  - [FastAPI response serialization](#fastapi-response-serialization)\n  - [If you must use sync SDK, then run it in a thread pool.](#if-you-must-use-sync-sdk-then-run-it-in-a-thread-pool)\n  - [ValueErrors might become Pydantic ValidationError](#valueerrors-might-become-pydantic-validationerror)\n  - [Docs](#docs)\n  - [Set DB keys naming conventions](#set-db-keys-naming-conventions)\n  - [Migrations. Alembic](#migrations-alembic)\n  - [Set DB naming conventions](#set-db-naming-conventions)\n  - [SQL-first. Pydantic-second](#sql-first-pydantic-second)\n  - [Set tests client async from day 0](#set-tests-client-async-from-day-0)\n  - [Use ruff](#use-ruff)\n- [Bonus Section](#bonus-section)\n\n## Project Structure\nThere are many ways to structure a project, but the best structure is one that is consistent, straightforward, and free of surprises.\n\nMany example projects and tutorials organize projects by file type (e.g., crud, routers, models), which works well for microservices or smaller projects. However, this approach didn't scale well for our monolith with many domains and modules.\n\nThe structure I found more scalable and evolvable is inspired by Netflix's [Dispatch](https://github.com/Netflix/dispatch), with some minor modifications.\n```\nfastapi-project\n├── alembic/\n├── src\n│   ├── auth\n│   │   ├── router.py\n│   │   ├── schemas.py  # pydantic models\n│   │   ├── models.py  # db models\n│   │   ├── dependencies.py\n│   │   ├── config.py  # local configs\n│   │   ├── constants.py\n│   │   ├── exceptions.py\n│   │   ├── service.py\n│   │   └── utils.py\n│   ├── aws\n│   │   ├── client.py  # client model for external service communication\n│   │   ├── schemas.py\n│   │   ├── config.py\n│   │   ├── constants.py\n│   │   ├── exceptions.py\n│   │   └── utils.py\n│   ├── posts\n│   │   ├── router.py\n│   │   ├── schemas.py\n│   │   ├── models.py\n│   │   ├── dependencies.py\n│   │   ├── constants.py\n│   │   ├── exceptions.py\n│   │   ├── service.py\n│   │   └── utils.py\n│   ├── config.py  # global configs\n│   ├── models.py  # global models\n│   ├── exceptions.py  # global exceptions\n│   ├── pagination.py  # global module e.g. pagination\n│   ├── database.py  # db connection related stuff\n│   └── main.py\n├── tests/\n│   ├── auth\n│   ├── aws\n│   └── posts\n├── templates/\n│   └── index.html\n├── requirements\n│   ├── base.txt\n│   ├── dev.txt\n│   └── prod.txt\n├── .env\n├── .gitignore\n├── logging.ini\n└── alembic.ini\n```\n1. Store all domain directories inside `src` folder\n   1. `src/` - highest level of an app, contains common models, configs, and constants, etc.\n   2. `src/main.py` - root of the project, which inits the FastAPI app\n2. Each package has its own router, schemas, models, etc.\n   1. `router.py` - is a core of each module with all the endpoints\n   2. `schemas.py` - for pydantic models\n   3. `models.py` - for db models\n   4. `service.py` - module specific business logic  \n   5. `dependencies.py` - router dependencies\n   6. `constants.py` - module specific constants and error codes\n   7. `config.py` - e.g. env vars\n   8. `utils.py` - non-business logic functions, e.g. response normalization, data enrichment, etc.\n   9. `exceptions.py` - module specific exceptions, e.g. `PostNotFound`, `InvalidUserData`\n3. When package requires services or dependencies or constants from other packages - import them with an explicit module name\n```python\nfrom src.auth import constants as auth_constants\nfrom src.notifications import service as notification_service\nfrom src.posts.constants import ErrorCode as PostsErrorCode  # in case we have Standard ErrorCode in constants module of each package\n```\n\n## Async Routes\nFastAPI is an async-first framework—it's designed to work with async I/O operations, which is why it's so fast.\n\nHowever, FastAPI doesn't restrict you to only `async` routes; you can use `sync` routes too. This might confuse beginners into thinking they're the same, but they're not.\n\n### I/O Intensive Tasks\nUnder the hood, FastAPI can [effectively handle](https://fastapi.tiangolo.com/async/#path-operation-functions) both async and sync I/O operations:\n- FastAPI runs `sync` routes in a [threadpool](https://en.wikipedia.org/wiki/Thread_pool), so blocking I/O operations won't stop the [event loop](https://docs.python.org/3/library/asyncio-eventloop.html) from executing other tasks.\n- If the route is defined as `async`, it's called via `await` and FastAPI trusts you to only perform non-blocking I/O operations.\n\nThe caveat is that if you violate that trust and execute blocking operations within async routes, the event loop won't be able to run other tasks until the blocking operation completes.\n```python\nimport asyncio\nimport time\n\nfrom fastapi import APIRouter\n\n\nrouter = APIRouter()\n\n\n@router.get(\"/terrible-ping\")\nasync def terrible_ping():\n    time.sleep(10) # I/O blocking operation for 10 seconds, the whole process will be blocked\n    \n    return {\"pong\": True}\n\n@router.get(\"/good-ping\")\ndef good_ping():\n    time.sleep(10) # I/O blocking operation for 10 seconds, but in a separate thread for the whole `good_ping` route\n\n    return {\"pong\": True}\n\n@router.get(\"/perfect-ping\")\nasync def perfect_ping():\n    await asyncio.sleep(10) # non-blocking I/O operation\n\n    return {\"pong\": True}\n\n```\n**What happens when we call:**\n1. `GET /terrible-ping`\n   1. FastAPI server receives a request and starts handling it\n   2. Server's event loop and all queued tasks wait until `time.sleep()` finishes\n      1. Since the route is `async`, the server doesn't offload it to a threadpool—it blocks the entire event loop\n      2. Server won't accept any new requests while waiting\n   3. Server returns the response\n      1. Only after responding does the server resume accepting new requests\n2. `GET /good-ping`\n   1. FastAPI server receives a request and starts handling it\n   2. FastAPI sends the entire `good_ping` route to the threadpool, where a worker thread runs the function\n   3. While `good_ping` executes, the event loop continues processing other tasks (e.g., accepting new requests, calling the database)\n      - The worker thread waits for `time.sleep` to finish, independently of the main thread\n      - The sync operation blocks only the worker thread, not the main event loop\n   4. When `good_ping` finishes, the server returns a response to the client\n3. `GET /perfect-ping`\n   1. FastAPI server receives a request and starts handling it\n   2. FastAPI awaits `asyncio.sleep(10)`\n   3. Event loop continues processing other tasks from the queue (e.g., accepting new requests, calling the database)\n   4. When `asyncio.sleep(10)` completes, the server finishes executing the route and returns a response to the client\n\n> [!WARNING]\n> Notes on the thread pool:\n> - Threads require more resources than coroutines, so they are not as cheap as async I/O operations.\n> - Thread pool has a limited number of threads, i.e. you might run out of threads and your app will become slow. [Read more](https://github.com/Kludex/fastapi-tips?tab=readme-ov-file#2-be-careful-with-non-async-functions) (external link)\n\n### CPU Intensive Tasks\nThe second caveat is that non-blocking awaitables and threadpool offloading are only beneficial for I/O intensive tasks (e.g., file operations, database calls, external API requests).\n- Awaiting CPU-intensive tasks (e.g., heavy calculations, data processing, video transcoding) provides no benefit since the CPU must actively work to complete them. In contrast, I/O operations are external—the server just waits for a response and can handle other tasks in the meantime.\n- Running CPU-intensive tasks in other threads is also ineffective due to the [GIL](https://realpython.com/python-gil/). In short, the GIL allows only one thread to execute Python bytecode at a time, making threads ineffective for CPU-bound work.\n- To optimize CPU-intensive tasks, you should offload them to worker processes (e.g., using `multiprocessing` or a task queue like Celery).\n\n**Related StackOverflow questions of confused users**\n1. https://stackoverflow.com/questions/62976648/architecture-flask-vs-fastapi/70309597#70309597\n   - Here you can also check [my answer](https://stackoverflow.com/a/70309597/6927498)\n2. https://stackoverflow.com/questions/65342833/fastapi-uploadfile-is-slow-compared-to-flask\n3. https://stackoverflow.com/questions/71516140/fastapi-runs-api-calls-in-serial-instead-of-parallel-fashion\n\n## Pydantic\n### Excessively use Pydantic\nPydantic has a rich set of features to validate and transform data. \n\nIn addition to standard features like required and optional fields with default values,\nPydantic has built-in data processing tools like regex validation, enums, string manipulation, email validation, and more.\n```python\nfrom enum import StrEnum\nfrom pydantic import AnyUrl, BaseModel, EmailStr, Field\n\n\nclass MusicBand(StrEnum):\n   AEROSMITH = \"AEROSMITH\"\n   QUEEN = \"QUEEN\"\n   ACDC = \"AC/DC\"\n\n\nclass UserBase(BaseModel):\n    first_name: str = Field(min_length=1, max_length=128)\n    username: str = Field(min_length=1, max_length=128, pattern=\"^[A-Za-z0-9-_]+$\")\n    email: EmailStr\n    age: int = Field(ge=18, default=None)  # must be greater or equal to 18\n    favorite_band: MusicBand | None = None  # only \"AEROSMITH\", \"QUEEN\", \"AC/DC\" values are allowed to be inputted\n    website: AnyUrl | None = None\n```\n### Custom Base Model\nHaving a controllable global base model allows us to customize all the models within the app. For instance, we can enforce a standard datetime format or introduce a common method for all subclasses of the base model.\n```python\nfrom datetime import datetime\nfrom zoneinfo import ZoneInfo\n\nfrom fastapi.encoders import jsonable_encoder\nfrom pydantic import BaseModel, ConfigDict\n\n\ndef datetime_to_gmt_str(dt: datetime) -> str:\n    if not dt.tzinfo:\n        dt = dt.replace(tzinfo=ZoneInfo(\"UTC\"))\n\n    return dt.strftime(\"%Y-%m-%dT%H:%M:%S%z\")\n\n\nclass CustomModel(BaseModel):\n    model_config = ConfigDict(\n        json_encoders={datetime: datetime_to_gmt_str},\n        populate_by_name=True,\n    )\n\n    def serializable_dict(self, **kwargs):\n        \"\"\"Return a dict which contains only serializable fields.\"\"\"\n        default_dict = self.model_dump()\n\n        return jsonable_encoder(default_dict)\n\n\n```\nIn the example above, we have decided to create a global base model that:\n- Serializes all datetime fields to a standard format with an explicit timezone\n- Provides a method to return a dict with only serializable fields\n### Decouple Pydantic BaseSettings\nBaseSettings is great for reading environment variables, but a single BaseSettings for the whole app gets messy. Split it across modules and domains.\n```python\n# src.auth.config\nfrom datetime import timedelta\n\nfrom pydantic_settings import BaseSettings\n\n\nclass AuthConfig(BaseSettings):\n    JWT_ALG: str\n    JWT_SECRET: str\n    JWT_EXP: int = 5  # minutes\n\n    REFRESH_TOKEN_KEY: str\n    REFRESH_TOKEN_EXP: timedelta = timedelta(days=30)\n\n    SECURE_COOKIES: bool = True\n\n\nauth_settings = AuthConfig()\n\n\n# src.config\nfrom pydantic import PostgresDsn, RedisDsn, model_validator\nfrom pydantic_settings import BaseSettings\n\nfrom src.constants import Environment\n\n\nclass Config(BaseSettings):\n    DATABASE_URL: PostgresDsn\n    REDIS_URL: RedisDsn\n\n    SITE_DOMAIN: str = \"myapp.com\"\n\n    ENVIRONMENT: Environment = Environment.PRODUCTION\n\n    SENTRY_DSN: str | None = None\n\n    CORS_ORIGINS: list[str]\n    CORS_ORIGINS_REGEX: str | None = None\n    CORS_HEADERS: list[str]\n\n    APP_VERSION: str = \"1.0\"\n\n\nsettings = Config()\n\n```\n\n## Dependencies\n### Beyond Dependency Injection\nPydantic is a great schema validator, but for complex validations that require database or external service calls, it's not enough.\n\nFastAPI docs mostly present dependencies as DI for endpoints, but they're also great for request validation.\n\nDependencies can validate data against database constraints (e.g., checking if an email already exists, ensuring a user exists, etc.).\n```python\n# dependencies.py\nasync def valid_post_id(post_id: UUID4) -> dict[str, Any]:\n    post = await service.get_by_id(post_id)\n    if not post:\n        raise PostNotFound()\n\n    return post\n\n\n# router.py\n@router.get(\"/posts/{post_id}\", response_model=PostResponse)\nasync def get_post_by_id(post: dict[str, Any] = Depends(valid_post_id)):\n    return post\n\n\n@router.put(\"/posts/{post_id}\", response_model=PostResponse)\nasync def update_post(\n    update_data: PostUpdate,  \n    post: dict[str, Any] = Depends(valid_post_id), \n):\n    updated_post = await service.update(id=post[\"id\"], data=update_data)\n    return updated_post\n\n\n@router.get(\"/posts/{post_id}/reviews\", response_model=list[ReviewsResponse])\nasync def get_post_reviews(post: dict[str, Any] = Depends(valid_post_id)):\n    post_reviews = await reviews_service.get_by_post_id(post[\"id\"])\n    return post_reviews\n```\nIf we didn't put data validation in a dependency, we would have to validate that `post_id` exists\nin every endpoint and write the same tests for each of them. \n\n### Chain Dependencies\nDependencies can use other dependencies and avoid code repetition for similar logic.\n```python\n# dependencies.py\nfrom fastapi.security import OAuth2PasswordBearer\nfrom jose import JWTError, jwt\n\nasync def valid_post_id(post_id: UUID4) -> dict[str, Any]:\n    post = await service.get_by_id(post_id)\n    if not post:\n        raise PostNotFound()\n\n    return post\n\n\nasync def parse_jwt_data(\n    token: str = Depends(OAuth2PasswordBearer(tokenUrl=\"/auth/token\"))\n) -> dict[str, Any]:\n    try:\n        payload = jwt.decode(token, \"JWT_SECRET\", algorithms=[\"HS256\"])\n    except JWTError:\n        raise InvalidCredentials()\n\n    return {\"user_id\": payload[\"id\"]}\n\n\nasync def valid_owned_post(\n    post: dict[str, Any] = Depends(valid_post_id), \n    token_data: dict[str, Any] = Depends(parse_jwt_data),\n) -> dict[str, Any]:\n    if post[\"creator_id\"] != token_data[\"user_id\"]:\n        raise UserNotOwner()\n\n    return post\n\n# router.py\n@router.get(\"/users/{user_id}/posts/{post_id}\", response_model=PostResponse)\nasync def get_user_post(post: dict[str, Any] = Depends(valid_owned_post)):\n    return post\n\n```\n### Decouple & Reuse dependencies. Dependency calls are cached\nDependencies can be reused multiple times, and they won't be recalculated - FastAPI caches dependency's result within a request's scope by default,\ni.e. if `valid_post_id` gets called multiple times in one route, it will be called only once.\n\nKnowing this, we can decouple dependencies onto multiple smaller functions that operate on a smaller domain and are easier to reuse in other routes.\nFor example, in the code below we are using `parse_jwt_data` three times:\n1. `valid_owned_post`\n2. `valid_active_creator`\n3. `get_user_post`,\n\nbut `parse_jwt_data` is called only once, in the very first call.\n\n```python\n# dependencies.py\nfrom fastapi import BackgroundTasks\nfrom fastapi.security import OAuth2PasswordBearer\nfrom jose import JWTError, jwt\n\nasync def valid_post_id(post_id: UUID4) -> Mapping:\n    post = await service.get_by_id(post_id)\n    if not post:\n        raise PostNotFound()\n\n    return post\n\n\nasync def parse_jwt_data(\n    token: str = Depends(OAuth2PasswordBearer(tokenUrl=\"/auth/token\"))\n) -> dict:\n    try:\n        payload = jwt.decode(token, \"JWT_SECRET\", algorithms=[\"HS256\"])\n    except JWTError:\n        raise InvalidCredentials()\n\n    return {\"user_id\": payload[\"id\"]}\n\n\nasync def valid_owned_post(\n    post: Mapping = Depends(valid_post_id), \n    token_data: dict = Depends(parse_jwt_data),\n) -> Mapping:\n    if post[\"creator_id\"] != token_data[\"user_id\"]:\n        raise UserNotOwner()\n\n    return post\n\n\nasync def valid_active_creator(\n    token_data: dict = Depends(parse_jwt_data),\n):\n    user = await users_service.get_by_id(token_data[\"user_id\"])\n    if not user[\"is_active\"]:\n        raise UserIsBanned()\n    \n    if not user[\"is_creator\"]:\n       raise UserNotCreator()\n    \n    return user\n        \n\n# router.py\n@router.get(\"/users/{user_id}/posts/{post_id}\", response_model=PostResponse)\nasync def get_user_post(\n    worker: BackgroundTasks,\n    post: Mapping = Depends(valid_owned_post),\n    user: Mapping = Depends(valid_active_creator),\n):\n    \"\"\"Get post that belong the active user.\"\"\"\n    worker.add_task(notifications_service.send_email, user[\"id\"])\n    return post\n\n```\n\n### Prefer `async` dependencies\nFastAPI supports both `sync` and `async` dependencies. It's tempting to use `sync` when you don't need to await anything, but that's not the best choice.\n\nJust like routes, `sync` dependencies run in a threadpool. Threads have overhead that's unnecessary for small non-I/O operations.\n\n[See more](https://github.com/Kludex/fastapi-tips?tab=readme-ov-file#9-your-dependencies-may-be-running-on-threads) (external link)\n\n\n## Miscellaneous\n### Follow the REST\nDeveloping RESTful API makes it easier to reuse dependencies in routes like these:\n   1. `GET /courses/:course_id`\n   2. `GET /courses/:course_id/chapters/:chapter_id/lessons`\n   3. `GET /chapters/:chapter_id`\n\nThe only caveat is having to use the same variable names in the path:\n- If you have two endpoints `GET /profiles/:profile_id` and `GET /creators/:creator_id`\nthat both validate whether the given `profile_id` exists,  but `GET /creators/:creator_id`\nalso checks if the profile is creator, then it's better to rename `creator_id` path variable to `profile_id` and chain those two dependencies.\n```python\n# src.profiles.dependencies\nasync def valid_profile_id(profile_id: UUID4) -> Mapping:\n    profile = await service.get_by_id(profile_id)\n    if not profile:\n        raise ProfileNotFound()\n\n    return profile\n\n# src.creators.dependencies\nasync def valid_creator_id(profile: Mapping = Depends(valid_profile_id)) -> Mapping:\n    if not profile[\"is_creator\"]:\n       raise ProfileNotCreator()\n\n    return profile\n\n# src.profiles.router.py\n@router.get(\"/profiles/{profile_id}\", response_model=ProfileResponse)\nasync def get_user_profile_by_id(profile: Mapping = Depends(valid_profile_id)):\n    \"\"\"Get profile by id.\"\"\"\n    return profile\n\n# src.creators.router.py\n@router.get(\"/creators/{profile_id}\", response_model=ProfileResponse)\nasync def get_user_profile_by_id(\n     creator_profile: Mapping = Depends(valid_creator_id)\n):\n    \"\"\"Get creator's profile by id.\"\"\"\n    return creator_profile\n\n```\n### FastAPI response serialization\nYou might think you can return a Pydantic object that matches your route's `response_model` and skip some processing steps, but you'd be wrong.\n\nFastAPI first converts the Pydantic object to a dict using `jsonable_encoder`, then validates the data against your `response_model`, and only then serializes it to JSON.\n\nThis means your Pydantic model object is created twice:\n- First, when you explicitly create it to return from your route.\n- Second, implicitly by FastAPI to validate the response data according to the response_model.\n\n```python\nfrom fastapi import FastAPI\nfrom pydantic import BaseModel, model_validator\n\napp = FastAPI()\n\n\nclass ProfileResponse(BaseModel):\n    @model_validator(mode=\"after\")\n    def debug_usage(self):\n        print(\"created pydantic model\")\n\n        return self\n\n\n@app.get(\"/\", response_model=ProfileResponse)\nasync def root():\n    return ProfileResponse()\n```\n**Logs Output:**\n```\n[INFO] [2022-08-28 12:00:00.000000] created pydantic model\n[INFO] [2022-08-28 12:00:00.000020] created pydantic model\n```\n\n### If you must use sync SDK, then run it in a thread pool.\nIf you must use a library that's not `async`, run the HTTP calls in an external worker thread.\n\nUse `run_in_threadpool` from Starlette.\n```python\nfrom fastapi import FastAPI\nfrom fastapi.concurrency import run_in_threadpool\nfrom my_sync_library import SyncAPIClient \n\napp = FastAPI()\n\n\n@app.get(\"/\")\nasync def call_my_sync_library():\n    my_data = await service.get_my_data()\n\n    client = SyncAPIClient()\n    await run_in_threadpool(client.make_request, data=my_data)\n```\n\n### ValueErrors might become Pydantic ValidationError\nIf you raise a `ValueError` in a Pydantic schema that's used directly in a request body, FastAPI will return a detailed validation error response to users.\n```python\n# src.profiles.schemas\nfrom pydantic import BaseModel, field_validator\n\nclass ProfileCreate(BaseModel):\n    username: str\n    password: str\n    \n    @field_validator(\"password\", mode=\"after\")\n    @classmethod\n    def valid_password(cls, password: str) -> str:\n        if not re.match(STRONG_PASSWORD_PATTERN, password):\n            raise ValueError(\n                \"Password must contain at least \"\n                \"one lower character, \"\n                \"one upper character, \"\n                \"digit or \"\n                \"special symbol\"\n            )\n\n        return password\n\n\n# src.profiles.routes\nfrom fastapi import APIRouter\n\nrouter = APIRouter()\n\n\n@router.post(\"/profiles\")\nasync def create_profile(profile_data: ProfileCreate):\n   pass\n```\n**Response Example:**\n\n<img src=\"images/value_error_response.png\" width=\"400\" height=\"auto\">\n\n### Docs\n1. Unless your API is public, hide docs by default. Show it explicitly on the selected envs only.\n```python\nfrom fastapi import FastAPI\nfrom starlette.config import Config\n\nconfig = Config(\".env\")  # parse .env file for env variables\n\nENVIRONMENT = config(\"ENVIRONMENT\")  # get current env name\nSHOW_DOCS_ENVIRONMENT = (\"local\", \"staging\")  # explicit list of allowed envs\n\napp_configs = {\"title\": \"My Cool API\"}\nif ENVIRONMENT not in SHOW_DOCS_ENVIRONMENT:\n   app_configs[\"openapi_url\"] = None  # set url for docs as null\n\napp = FastAPI(**app_configs)\n```\n2. Help FastAPI to generate an easy-to-understand docs\n   1. Set `response_model`, `status_code`, `description`, etc.\n   2. If models and statuses vary, use `responses` route attribute to add docs for different responses\n```python\nfrom fastapi import APIRouter, status\n\nrouter = APIRouter()\n\n@router.post(\n    \"/endpoints\",\n    response_model=DefaultResponseModel,  # default response pydantic model \n    status_code=status.HTTP_201_CREATED,  # default status code\n    description=\"Description of the well documented endpoint\",\n    tags=[\"Endpoint Category\"],\n    summary=\"Summary of the Endpoint\",\n    responses={\n        status.HTTP_200_OK: {\n            \"model\": OkResponse, # custom pydantic model for 200 response\n            \"description\": \"Ok Response\",\n        },\n        status.HTTP_201_CREATED: {\n            \"model\": CreatedResponse,  # custom pydantic model for 201 response\n            \"description\": \"Creates something from user request\",\n        },\n        status.HTTP_202_ACCEPTED: {\n            \"model\": AcceptedResponse,  # custom pydantic model for 202 response\n            \"description\": \"Accepts request and handles it later\",\n        },\n    },\n)\nasync def documented_route():\n    pass\n```\nWill generate docs like this:\n![FastAPI Generated Custom Response Docs](images/custom_responses.png \"Custom Response Docs\")\n\n### Set DB keys naming conventions\nExplicitly setting the indexes' namings according to your database's convention is preferable over sqlalchemy's. \n```python\nfrom sqlalchemy import MetaData\n\nPOSTGRES_INDEXES_NAMING_CONVENTION = {\n    \"ix\": \"%(column_0_label)s_idx\",\n    \"uq\": \"%(table_name)s_%(column_0_name)s_key\",\n    \"ck\": \"%(table_name)s_%(constraint_name)s_check\",\n    \"fk\": \"%(table_name)s_%(column_0_name)s_fkey\",\n    \"pk\": \"%(table_name)s_pkey\",\n}\nmetadata = MetaData(naming_convention=POSTGRES_INDEXES_NAMING_CONVENTION)\n```\n### Migrations. Alembic\n1. Migrations must be static and reversible. If your migrations depend on dynamically generated data, make sure only the data itself is dynamic, not its structure.\n2. Generate migrations with descriptive names and slugs. The slug is required and should explain the changes.\n3. Set a human-readable file template for new migrations. We use the `*date*_*slug*.py` pattern, e.g., `2022-08-24_post_content_idx.py`\n```\n# alembic.ini\nfile_template = %%(year)d-%%(month).2d-%%(day).2d_%%(slug)s\n```\n### Set DB naming conventions\nBeing consistent with names is important. Some rules we followed:\n1. lower_case_snake\n2. singular form (e.g. `post`, `post_like`, `user_playlist`)\n3. group similar tables with module prefix, e.g. `payment_account`, `payment_bill`, `post`, `post_like`\n4. stay consistent across tables, but concrete namings are ok, e.g.\n   1. use `profile_id` in all tables, but if some of them need only profiles that are creators, use `creator_id`\n   2. use `post_id` for all abstract tables like `post_like`, `post_view`, but use concrete naming in relevant modules like `course_id` in `chapters.course_id`\n5. `_at` suffix for datetime\n6. `_date` suffix for date\n### SQL-first. Pydantic-second\n- Usually, database handles data processing much faster and cleaner than CPython will ever do. \n- It's preferable to do all the complex joins and simple data manipulations with SQL.\n- It's preferable to aggregate JSONs in DB for responses with nested objects.\n```python\n# src.posts.service\nfrom typing import Any\n\nfrom pydantic import UUID4\nfrom sqlalchemy import desc, func, select, text\nfrom sqlalchemy.sql.functions import coalesce\n\nfrom src.database import database, posts, profiles, post_review, products\n\nasync def get_posts(\n    creator_id: UUID4, *, limit: int = 10, offset: int = 0\n) -> list[dict[str, Any]]: \n    select_query = (\n        select(\n            (\n                posts.c.id,\n                posts.c.slug,\n                posts.c.title,\n                func.json_build_object(\n                   text(\"'id', profiles.id\"),\n                   text(\"'first_name', profiles.first_name\"),\n                   text(\"'last_name', profiles.last_name\"),\n                   text(\"'username', profiles.username\"),\n                ).label(\"creator\"),\n            )\n        )\n        .select_from(posts.join(profiles, posts.c.owner_id == profiles.c.id))\n        .where(posts.c.owner_id == creator_id)\n        .limit(limit)\n        .offset(offset)\n        .group_by(\n            posts.c.id,\n            posts.c.type,\n            posts.c.slug,\n            posts.c.title,\n            profiles.c.id,\n            profiles.c.first_name,\n            profiles.c.last_name,\n            profiles.c.username,\n            profiles.c.avatar,\n        )\n        .order_by(\n            desc(coalesce(posts.c.updated_at, posts.c.published_at, posts.c.created_at))\n        )\n    )\n    \n    return await database.fetch_all(select_query)\n\n# src.posts.schemas\nfrom typing import Any\n\nfrom pydantic import BaseModel, UUID4\n\n   \nclass Creator(BaseModel):\n    id: UUID4\n    first_name: str\n    last_name: str\n    username: str\n\n\nclass Post(BaseModel):\n    id: UUID4\n    slug: str\n    title: str\n    creator: Creator\n\n    \n# src.posts.router\nfrom fastapi import APIRouter, Depends\n\nrouter = APIRouter()\n\n\n@router.get(\"/creators/{creator_id}/posts\", response_model=list[Post])\nasync def get_creator_posts(creator: dict[str, Any] = Depends(valid_creator_id)):\n   posts = await service.get_posts(creator[\"id\"])\n\n   return posts\n```\n### Set tests client async from day 0\nWriting integration tests with DB will likely lead to messed up event loop errors in the future.\nSet the async test client immediately, e.g. [httpx](https://github.com/encode/starlette/issues/652)\n```python\nimport pytest\nfrom async_asgi_testclient import TestClient\n\nfrom src.main import app  # inited FastAPI app\n\n\n@pytest.fixture\nasync def client() -> AsyncGenerator[TestClient, None]:\n    host, port = \"127.0.0.1\", \"9000\"\n\n    async with AsyncClient(transport=ASGITransport(app=app, client=(host, port)), base_url=\"http://test\") as client:\n        yield client\n\n\n@pytest.mark.asyncio\nasync def test_create_post(client: TestClient):\n    resp = await client.post(\"/posts\")\n\n    assert resp.status_code == 201\n```\nUnless you have synchronous database connections (excuse me?) or don't plan to write integration tests.\n\n### Use ruff\nWith linters, you can forget about formatting the code and focus on writing the business logic.\n\n[Ruff](https://github.com/astral-sh/ruff) is \"blazingly-fast\" new linter that replaces black, autoflake, isort, and supports more than 600 lint rules.\n\nIt's a popular good practice to use pre-commit hooks, but just using the script was ok for us.\n```shell\n#!/bin/sh -e\nset -x\n\nruff check --fix src\nruff format src\n```\n\n## Bonus Section\nSome very kind people shared their own experience and best practices that are definitely worth reading.\nCheck them out at [issues](https://github.com/zhanymkanov/fastapi-best-practices/issues) section of the project.\n\nFor instance, [lowercase00](https://github.com/zhanymkanov/fastapi-best-practices/issues/4) \nhas described in details their best practices working with permissions & auth, class-based services & views, \ntask queues, custom response serializers, configuration with dynaconf, etc.  \n\nIf you have something to share about your experience working with FastAPI, whether it's good or bad, \nyou are very welcome to create a new issue. It is our pleasure to read it. \n"
  },
  {
    "path": "README_ZH.md",
    "content": "# Fast Api最佳实践指南\n\n这是我在初创公司使用的一系列最佳实践和约定。\n\n在过去几年的生产实践中，我们做过一些好的和不好的决策，这些决策极大地影响了开发者体验。其中一些经验值得分享。\n\n## 目录\n- [Fast Api最佳实践指南](#fast-api最佳实践指南)\n  - [目录](#目录)\n  - [项目结构](#项目结构)\n  - [异步路由](#异步路由)\n    - [I/O密集型任务](#io密集型任务)\n    - [CPU密集型任务](#cpu密集型任务)\n  - [Pydantic](#pydantic)\n    - [大量使用Pydantic](#大量使用pydantic)\n    - [自定义基础模型](#自定义基础模型)\n    - [拆分Pydantic BaseSettings](#拆分pydantic-basesettings)\n  - [依赖项](#依赖项)\n    - [超越依赖注入](#超越依赖注入)\n    - [链式依赖](#链式依赖)\n    - [拆分并复用依赖项。依赖调用会被缓存](#拆分并复用依赖项依赖调用会被缓存)\n    - [优先使用`async`依赖项](#优先使用async依赖项)\n  - [其他](#其他)\n    - [遵循REST规范](#遵循rest规范)\n    - [FastAPI响应序列化](#fastapi响应序列化)\n    - [如果必须使用同步SDK，请在线程池中运行它。](#如果必须使用同步sdk请在线程池中运行它)\n    - [ValueErrors可能会变成Pydantic ValidationError](#valueerrors可能会变成pydantic-validationerror)\n    - [文档](#文档)\n    - [迁移工具Alembic](#迁移工具alembic)\n    - [设置数据库键命名约定](#设置数据库键命名约定)\n    - [SQL优先，Pydantic次之](#sql优先pydantic次之)\n    - [从一开始就设置异步测试客户端](#从一开始就设置异步测试客户端)\n    - [使用ruff](#使用ruff)\n  - [额外部分](#额外部分)\n  \n## 项目结构\n\n项目结构有很多种，但最好的结构是一致、直观且没有意外的。\n\n许多示例项目和教程按文件类型（如crud、routers、models）划分项目，这种方式对于微服务或范围较小的项目很有效。但是，这种方法并不适合我们这个包含许多领域和模块的单体应用。\n\n我发现对于这类情况，更具可扩展性和可演进性的结构是受Netflix的[Dispatch](https://github.com/Netflix/dispatch)启发，并做了一些小修改。\n\n```\nfastapi-project\n├── alembic/\n├── src\n│   ├── auth\n│   │   ├── router.py\n│   │   ├── schemas.py  # pydantic模型\n│   │   ├── models.py  # 数据库模型\n│   │   ├── dependencies.py\n│   │   ├── config.py  # 本地配置\n│   │   ├── constants.py\n│   │   ├── exceptions.py\n│   │   ├── service.py\n│   │   └── utils.py\n│   ├── aws\n│   │   ├── client.py  # 用于外部服务通信的客户端模型\n│   │   ├── schemas.py\n│   │   ├── config.py\n│   │   ├── constants.py\n│   │   ├── exceptions.py\n│   │   └── utils.py\n│   ├── posts\n│   │   ├── router.py\n│   │   ├── schemas.py\n│   │   ├── models.py\n│   │   ├── dependencies.py\n│   │   ├── constants.py\n│   │   ├── exceptions.py\n│   │   ├── service.py\n│   │   └── utils.py\n│   ├── config.py  # 全局配置\n│   ├── models.py  # 全局模型\n│   ├── exceptions.py  # 全局异常\n│   ├── pagination.py  # 全局模块，如分页\n│   ├── database.py  # 数据库连接相关内容\n│   └── main.py\n├── tests/\n│   ├── auth\n│   ├── aws\n│   └── posts\n├── templates/\n│   └── index.html\n├── requirements\n│   ├── base.txt\n│   ├── dev.txt\n│   └── prod.txt\n├── .env\n├── .gitignore\n├── logging.ini\n└── alembic.ini\n```\n\n\n1. 将所有领域目录存储在`src`文件夹中\n   1. `src/` - 应用的最高级别，包含通用模型、配置和常量等。\n   2. `src/main.py` - 项目的根文件，用于初始化FastAPI应用\n\n2. 每个包都有自己的路由、模式、模型等。\n   1. `router.py` - 每个模块的核心，包含所有端点\n   2. `schemas.py` - 用于pydantic模型\n   3. `models.py` - 用于数据库模型\n   4. `service.py` - 模块特定的业务逻辑\n   5. `dependencies.py` - 路由依赖项\n   6. `constants.py` - 模块特定的常量和错误代码\n   7. `config.py` - 例如环境变量\n   8. `utils.py` - 非业务逻辑函数，例如响应规范化、数据丰富等\n   9. `exceptions.py` - 模块特定的异常，例如`PostNotFound`、`InvalidUserData`\n\n3. 当包需要其他包的服务、依赖项或常量时，使用显式的模块名导入\n```python\nfrom src.auth import constants as auth_constants\nfrom src.notifications import service as notification_service\nfrom src.posts.constants import ErrorCode as PostsErrorCode  # 以防每个包的constants模块中都有标准的ErrorCode\n```\n\n## 异步路由\n\nFastAPI首先是一个异步框架。它设计用于处理异步I/O操作，这也是它如此快速的原因。\n\n然而，FastAPI并不限制你只能使用`async`路由，开发者也可以使用同步路由。这可能会让初学者误以为它们是一样的，但实际上并非如此。\n\n### I/O密集型任务\n\n在底层，FastAPI可以有效地处理异步和同步I/O操作。\n\n- FastAPI在线程池中运行同步路由，阻塞的I/O操作不会阻止事件循环执行任务。\n- 如果路由定义为`async`，那么它会通过`await`正常调用，FastAPI相信你只会执行非阻塞的I/O操作。\n\n需要注意的是，如果你违反了这种信任，在异步路由中执行阻塞操作，事件循环将无法在阻塞操作完成之前运行后续任务。\n\n```python\nimport asyncio\nimport time\n\nfrom fastapi import APIRouter\n\nrouter = APIRouter()\n\n@router.get(\"/terrible-ping\")\nasync def terrible_ping():\n    time.sleep(10) # 10秒的I/O阻塞操作，整个进程都会被阻塞\n\n    return {\"pong\": True}\n\n@router.get(\"/good-ping\")\ndef good_ping():\n    time.sleep(10) # 10秒的I/O阻塞操作，但在单独的线程中运行整个`good_ping`路由\n\n    return {\"pong\": True}\n\n@router.get(\"/perfect-ping\")\nasync def perfect_ping():\n    await asyncio.sleep(10) # 非阻塞I/O操作\n\n    return {\"pong\": True}\n```\n\n**当我们调用时会发生什么：**\n\n1. `GET /terrible-ping`\n    1. FastAPI服务器接收请求并开始处理\n    2. 服务器的事件循环和队列中的所有任务都将等待`time.sleep()`完成\n        1. 服务器认为`time.sleep()`不是I/O任务，所以会等待它完成\n        2. 等待期间，服务器不会接受任何新请求\n    3. 服务器返回响应。\n        1. 响应之后，服务器开始接受新请求\n2. `GET /good-ping`\n    1. FastAPI服务器接收请求并开始处理\n    2. FastAPI将整个路由`good_ping`发送到线程池，工作线程将在那里运行该函数\n    3. 在`good_ping`执行期间，事件循环从队列中选择下一个任务并处理它们（例如接受新请求、调用数据库）\n        - 独立于主线程（即我们的FastAPI应用），工作线程将等待`time.sleep`完成。\n        - 同步操作只阻塞子线程，而不是主线程。\n    4. 当`good_ping`完成工作后，服务器向客户端返回响应\n3. `GET /perfect-ping`\n    1. FastAPI服务器接收请求并开始处理\n    2. FastAPI等待`asyncio.sleep(10)`\n    3. 事件循环从队列中选择下一个任务并处理它们（例如接受新请求、调用数据库）\n    4. 当`asyncio.sleep(10)`完成后，服务器完成路由的执行并向客户端返回响应\n\n> [!WARNING]\n关于线程池的注意事项：\n> \n> - 线程比协程需要更多资源，因此它们不像异步I/O操作那样轻量。\n> - 线程池的线程数量是有限的，也就是说，你可能会耗尽线程，导致应用变慢。[了解更多](https://github.com/Kludex/fastapi-tips?tab=readme-ov-file#2-be-careful-with-non-async-functions)（外部链接）\n\n### CPU密集型任务\n\n第二个需要注意的是，非阻塞的可等待对象或发送到线程池的操作必须是I/O密集型任务（例如打开文件、数据库调用、外部API调用）。\n\n- 等待CPU密集型任务（例如繁重的计算、数据处理、视频转码）是没有意义的，因为CPU必须工作才能完成这些任务，而I/O操作是外部的，服务器在等待这些操作完成时什么也不做，因此它可以处理下一个任务。\n- 在其他线程中运行CPU密集型任务也不是有效的，因为[GIL（全局解释器锁）](https://realpython.com/python-gil/)的存在。简而言之，GIL只允许一个线程同时工作，这使得它对CPU任务毫无用处。\n- 如果你想优化CPU密集型任务，你应该将它们发送到另一个进程中的工作节点。\n\n**困惑用户的相关StackOverflow问题**\n\n1. [https://stackoverflow.com/questions/62976648/architecture-flask-vs-fastapi/70309597#70309597](https://stackoverflow.com/questions/62976648/architecture-flask-vs-fastapi/70309597#70309597)\n    - 在这里你也可以查看[我的回答](https://stackoverflow.com/a/70309597/6927498)\n2. [https://stackoverflow.com/questions/65342833/fastapi-uploadfile-is-slow-compared-to-flask](https://stackoverflow.com/questions/65342833/fastapi-uploadfile-is-slow-compared-to-flask)\n3. [https://stackoverflow.com/questions/71516140/fastapi-runs-api-calls-in-serial-instead-of-parallel-fashion](https://stackoverflow.com/questions/71516140/fastapi-runs-api-calls-in-serial-instead-of-parallel-fashion)\n\n## Pydantic\n\n### 大量使用Pydantic\n\nPydantic有丰富的功能来验证和转换数据。\n\n除了常规功能（如带有默认值的必填和非必填字段），Pydantic还有内置的综合数据处理工具，如正则表达式、枚举、字符串操作、电子邮件验证等。\n\n```python\nfrom enum import Enum\nfrom pydantic import AnyUrl, BaseModel, EmailStr, Field\n\nclass MusicBand(str, Enum):\n   AEROSMITH = \"AEROSMITH\"\n   QUEEN = \"QUEEN\"\n   ACDC = \"AC/DC\"\n\nclass UserBase(BaseModel):\n    first_name: str = Field(min_length=1, max_length=128)\n    username: str = Field(min_length=1, max_length=128, pattern=\"^[A-Za-z0-9-_]+$\")\n    email: EmailStr\n    age: int = Field(ge=18, default=None)  # 必须大于或等于18\n    favorite_band: MusicBand | None = None  # 只允许输入\"AEROSMITH\"、\"QUEEN\"、\"AC/DC\"值\n    website: AnyUrl | None = None\n```\n\n### 自定义基础模型\n\n拥有一个可控制的全局基础模型允许我们自定义应用中的所有模型。例如，我们可以强制使用标准的 datetime 格式，或者为基础模型的所有子类引入一个通用方法。\n\n```python\nfrom datetime import datetime\nfrom zoneinfo import ZoneInfo\n\nfrom fastapi.encoders import jsonable_encoder\nfrom pydantic import BaseModel, ConfigDict\n\ndef datetime_to_gmt_str(dt: datetime) -> str:\n    if not dt.tzinfo:\n        dt = dt.replace(tzinfo=ZoneInfo(\"UTC\"))\n\n    return dt.strftime(\"%Y-%m-%dT%H:%M:%S%z\")\n\nclass CustomModel(BaseModel):\n    model_config = ConfigDict(\n        json_encoders={datetime: datetime_to_gmt_str},\n        populate_by_name=True,\n    )\n\n    def serializable_dict(self, **kwargs):\n        \"\"\"返回仅包含可序列化字段的字典。\"\"\"\n        default_dict = self.model_dump()\n\n        return jsonable_encoder(default_dict)\n```\n\n在上面的例子中，我们决定创建一个全局基础模型，它：\n\n- 将所有datetime字段序列化为具有显式时区的标准格式\n- 提供一个方法来返回仅包含可序列化字段的字典\n\n### 拆分Pydantic BaseSettings\n\nBaseSettings是读取环境变量的一项伟大创新，但为整个应用使用单个BaseSettings随着时间的推移可能会变得混乱。为了提高可维护性和组织性，我们将BaseSettings拆分到不同的模块和领域中。\n\n```python\n# src.auth.config\nfrom datetime import timedelta\n\nfrom pydantic_settings import BaseSettings\n\nclass AuthConfig(BaseSettings):\n    JWT_ALG: str\n    JWT_SECRET: str\n    JWT_EXP: int = 5  # 分钟\n\n    REFRESH_TOKEN_KEY: str\n    REFRESH_TOKEN_EXP: timedelta = timedelta(days=30)\n\n    SECURE_COOKIES: bool = True\n\nauth_settings = AuthConfig()\n\n# src.config\nfrom pydantic import PostgresDsn, RedisDsn, model_validator\nfrom pydantic_settings import BaseSettings\n\nfrom src.constants import Environment\n\nclass Config(BaseSettings):\n    DATABASE_URL: PostgresDsn\n    REDIS_URL: RedisDsn\n\n    SITE_DOMAIN: str = \"myapp.com\"\n\n    ENVIRONMENT: Environment = Environment.PRODUCTION\n\n    SENTRY_DSN: str | None = None\n\n    CORS_ORIGINS: list[str]\n    CORS_ORIGINS_REGEX: str | None = None\n    CORS_HEADERS: list[str]\n\n    APP_VERSION: str = \"1.0\"\n\nsettings = Config()\n```\n\n## 依赖项\n\n### 超越依赖注入\n\nPydantic是一个很棒的模式验证器，但对于涉及调用数据库或外部服务的复杂验证，它还不够。\n\nFastAPI文档主要将依赖项展示为端点的依赖注入，但它们也非常适合请求验证。\n\n依赖项可用于根据数据库约束验证数据（例如，检查电子邮件是否已存在、确保找到用户等）。\n\n```python\n# dependencies.py\nasync def valid_post_id(post_id: UUID4) -> dict[str, Any]:\n    post = await service.get_by_id(post_id)\n    if not post:\n        raise PostNotFound()\n\n    return post\n\n# router.py\n@router.get(\"/posts/{post_id}\", response_model=PostResponse)\nasync def get_post_by_id(post: dict[str, Any] = Depends(valid_post_id)):\n    return post\n\n@router.put(\"/posts/{post_id}\", response_model=PostResponse)\nasync def update_post(\n    update_data: PostUpdate,  \n    post: dict[str, Any] = Depends(valid_post_id), \n):\n    updated_post = await service.update(id=post[\"id\"], data=update_data)\n    return updated_post\n\n@router.get(\"/posts/{post_id}/reviews\", response_model=list[ReviewsResponse])\nasync def get_post_reviews(post: dict[str, Any] = Depends(valid_post_id)):\n    post_reviews = await reviews_service.get_by_post_id(post[\"id\"])\n    return post_reviews\n```\n\n如果我们没有将数据验证放入依赖项中，我们将不得不为每个端点验证`post_id`是否存在，并为每个端点编写相同的测试。\n\n### 链式依赖\n\n依赖项可以使用其他依赖项，避免类似逻辑的代码重复。\n\n```python\n# dependencies.py\nfrom fastapi.security import OAuth2PasswordBearer\nfrom jose import JWTError, jwt\n\nasync def valid_post_id(post_id: UUID4) -> dict[str, Any]:\n    post = await service.get_by_id(post_id)\n    if not post:\n        raise PostNotFound()\n\n    return post\n\nasync def parse_jwt_data(\n    token: str = Depends(OAuth2PasswordBearer(tokenUrl=\"/auth/token\"))\n) -> dict[str, Any]:\n    try:\n        payload = jwt.decode(token, \"JWT_SECRET\", algorithms=[\"HS256\"])\n    except JWTError:\n        raise InvalidCredentials()\n\n    return {\"user_id\": payload[\"id\"]}\n\nasync def valid_owned_post(\n    post: dict[str, Any] = Depends(valid_post_id), \n    token_data: dict[str, Any] = Depends(parse_jwt_data),\n) -> dict[str, Any]:\n    if post[\"creator_id\"] != token_data[\"user_id\"]:\n        raise UserNotOwner()\n\n    return post\n\n# router.py\n@router.get(\"/users/{user_id}/posts/{post_id}\", response_model=PostResponse)\nasync def get_user_post(post: dict[str, Any] = Depends(valid_owned_post)):\n    return\n```\n\n### 拆分并复用依赖项。依赖调用会被缓存\n\n依赖项可以多次复用，并且它们不会被重新计算——FastAPI默认在请求的范围内缓存依赖项的结果，也就是说，如果`valid_post_id`在一个路由中被多次调用，它只会被调用一次。\n\n了解这一点后，我们可以将依赖项拆分为多个更小的函数，这些函数在更小的领域上运行，并且更容易在其他路由中复用。\n\n例如，在下面的代码中，我们三次使用`parse_jwt_data`：\n\n1. `valid_owned_post`\n2. `valid_active_creator`\n3. `get_user_post`\n\n但`parse_jwt_data`只在第一次调用时被调用一次。\n\n```python\n# dependencies.py\nfrom fastapi import BackgroundTasks\nfrom fastapi.security import OAuth2PasswordBearer\nfrom jose import JWTError, jwt\n\nasync def valid_post_id(post_id: UUID4) -> Mapping:\n    post = await service.get_by_id(post_id)\n    if not post:\n        raise PostNotFound()\n\n    return post\n\nasync def parse_jwt_data(\n    token: str = Depends(OAuth2PasswordBearer(tokenUrl=\"/auth/token\"))\n) -> dict:\n    try:\n        payload = jwt.decode(token, \"JWT_SECRET\", algorithms=[\"HS256\"])\n    except JWTError:\n        raise InvalidCredentials()\n\n    return {\"user_id\": payload[\"id\"]}\n\nasync def valid_owned_post(\n    post: Mapping = Depends(valid_post_id), \n    token_data: dict = Depends(parse_jwt_data),\n) -> Mapping:\n    if post[\"creator_id\"] != token_data[\"user_id\"]:\n        raise UserNotOwner()\n\n    return post\n\nasync def valid_active_creator(\n    token_data: dict = Depends(parse_jwt_data),\n):\n    user = await users_service.get_by_id(token_data[\"user_id\"])\n    if not user[\"is_active\"]:\n        raise UserIsBanned()\n    \n    if not user[\"is_creator\"]:\n       raise UserNotCreator()\n    \n    return user\n        \n\n# router.py\n@router.get(\"/users/{user_id}/posts/{post_id}\", response_model=PostResponse)\nasync def get_user_post(\n    worker: BackgroundTasks,\n    post: Mapping = Depends(valid_owned_post),\n    user: Mapping = Depends(valid_active_creator),\n):\n    \"\"\"Get post that belong the active user.\"\"\"\n    worker.add_task(notifications_service.send_email, user[\"id\"])\n    return post\n```\n\n### 优先使用`async`依赖项\n\nFastAPI同时支持同步和异步依赖项，当你不需要等待任何东西时，很容易会想使用同步依赖项，但这可能不是最佳选择。\n\n与路由一样，同步依赖项在线程池中运行。这里的线程也有代价和限制，如果只是进行小的非I/O操作，这些代价和限制是多余的。\n\n[了解更多](https://github.com/Kludex/fastapi-tips?tab=readme-ov-file#9-your-dependencies-may-be-running-on-threads)（外部链接）\n\n## 其他\n\n### 遵循REST规范\n\n开发RESTful API可以更轻松地在如下路由中复用依赖项：\n\n1. `GET /courses/:course_id`\n2. `GET /courses/:course_id/chapters/:chapter_id/lessons`\n3. `GET /chapters/:chapter_id`\n\n唯一需要注意的是必须在路径中使用相同的变量名：\n\n- 如果你有两个端点`GET /profiles/:profile_id`和`GET /creators/:creator_id`，它们都验证给定的`profile_id`是否存在，但`GET /creators/:creator_id`还检查该个人资料是否是创作者，那么最好将`creator_id`路径变量重命名为`profile_id`并链接这两个依赖项。\n\n```python\n# src.profiles.dependencies\nasync def valid_profile_id(profile_id: UUID4) -> Mapping:\n    profile = await service.get_by_id(profile_id)\n    if not profile:\n        raise ProfileNotFound()\n\n    return profile\n\n# src.creators.dependencies\nasync def valid_creator_id(profile: Mapping = Depends(valid_profile_id)) -> Mapping:\n    if not profile[\"is_creator\"]:\n       raise ProfileNotCreator()\n\n    return profile\n\n# src.profiles.router.py\n@router.get(\"/profiles/{profile_id}\", response_model=ProfileResponse)\nasync def get_user_profile_by_id(profile: Mapping = Depends(valid_profile_id)):\n    \"\"\"Get profile by id.\"\"\"\n    return profile\n\n# src.creators.router.py\n@router.get(\"/creators/{profile_id}\", response_model=ProfileResponse)\nasync def get_user_profile_by_id(\n     creator_profile: Mapping = Depends(valid_creator_id)\n):\n    \"\"\"Get creator's profile by id.\"\"\"\n    return creator_profile\n\n```\n\n### FastAPI响应序列化\n\n你可能认为可以返回与路由的`response_model`匹配的Pydantic对象来进行一些优化，但你错了。\n\nFastAPI首先使用其`jsonable_encoder`将该pydantic对象转换为字典，然后使用你的`response_model`验证数据，最后才将你的对象序列化为JSON。\n\n这意味着你的Pydantic模型对象会被创建两次：\n\n- 第一次，当你显式创建它以从路由返回时。\n- 第二次，FastAPI隐式创建它以根据response_model验证响应数据。\n\n```python\nfrom fastapi import FastAPI\nfrom pydantic import BaseModel, root_validator\n\napp = FastAPI()\n\nclass ProfileResponse(BaseModel):\n    @model_validator(mode=\"after\")\n    def debug_usage(self):\n        print(\"created pydantic model\")\n\n        return self\n\n@app.get(\"/\", response_model=ProfileResponse)\nasync def root():\n    return ProfileResponse()\n\n```\n\n**日志输出：**\n\n```\n[INFO] [2022-08-28 12:00:00.000000] created pydantic model\n[INFO] [2022-08-28 12:00:00.000020] created pydantic model\n\n```\n\n### 如果必须使用同步SDK，请在线程池中运行它。\n\n如果你必须使用一个库与外部服务交互，并且它不是异步的，那么在外部工作线程中进行HTTP调用。\n\n我们可以使用starlette中著名的`run_in_threadpool`。\n\n```python\nfrom fastapi import FastAPI\nfrom fastapi.concurrency import run_in_threadpool\nfrom my_sync_library import SyncAPIClient \n\napp = FastAPI()\n\n@app.get(\"/\")\nasync def call_my_sync_library():\n    my_data = await service.get_my_data()\n\n    client = SyncAPIClient()\n    await run_in_threadpool(client.make_request, data=my_data)\n```\n\n### ValueErrors可能会变成Pydantic ValidationError\n\n如果你在直接面向客户端的Pydantic模式中引发`ValueError`，它将向用户返回一个详细的响应。\n\n```python\n# src.profiles.schemas\nfrom pydantic import BaseModel, field_validator\n\nclass ProfileCreate(BaseModel):\n    username: str\n    \n    @field_validator(\"password\", mode=\"after\")\n    @classmethod\n    def valid_password(cls, password: str) -> str:\n        if not re.match(STRONG_PASSWORD_PATTERN, password):\n            raise ValueError(\n                \"Password must contain at least \"\n                \"one lower character, \"\n                \"one upper character, \"\n                \"digit or \"\n                \"special symbol\"\n            )\n\n        return password\n\n# src.profiles.routes\nfrom fastapi import APIRouter\n\nrouter = APIRouter()\n\n@router.post(\"/profiles\")\nasync def get_creator_posts(profile_data: ProfileCreate):\n   pass\n```\n\n**响应示例：**\n\n<img src=\"images/value_error_response.png\" width=\"400\" height=\"auto\">\n\n### 文档\n\n1. 除非你的API是公共的，否则默认隐藏文档。只在选定的环境中显式显示它。\n\n```python\nfrom fastapi import FastAPI\nfrom starlette.config import Config\n\nconfig = Config(\".env\")  # parse .env file for env variables\n\nENVIRONMENT = config(\"ENVIRONMENT\")  # get current env name\nSHOW_DOCS_ENVIRONMENT = (\"local\", \"staging\")  # explicit list of allowed envs\n\napp_configs = {\"title\": \"My Cool API\"}\nif ENVIRONMENT not in SHOW_DOCS_ENVIRONMENT:\n   app_configs[\"openapi_url\"] = None  # set url for docs as null\n\napp = FastAPI(**app_configs)\n```\n\n1. 帮助FastAPI生成易于理解的文档\n    1. 设置`response_model`、`status_code`、`description`等。\n    2. 如果模型和状态不同，使用`responses`路由属性为不同的响应添加文档\n\n```python\nfrom fastapi import APIRouter, status\n\nrouter = APIRouter()\n\n@router.post(\n    \"/endpoints\",\n    response_model=DefaultResponseModel,  # default response pydantic model \n    status_code=status.HTTP_201_CREATED,  # default status code\n    description=\"Description of the well documented endpoint\",\n    tags=[\"Endpoint Category\"],\n    summary=\"Summary of the Endpoint\",\n    responses={\n        status.HTTP_200_OK: {\n            \"model\": OkResponse, # custom pydantic model for 200 response\n            \"description\": \"Ok Response\",\n        },\n        status.HTTP_201_CREATED: {\n            \"model\": CreatedResponse,  # custom pydantic model for 201 response\n            \"description\": \"Creates something from user request\",\n        },\n        status.HTTP_202_ACCEPTED: {\n            \"model\": AcceptedResponse,  # custom pydantic model for 202 response\n            \"description\": \"Accepts request and handles it later\",\n        },\n    },\n)\nasync def documented_route():\n    pass\n```\n\n将生成如下文档：\n\n<img src=\"images/custom_responses.png\" width=\"400\" height=\"auto\">\n\n**设置数据库键命名约定**\n\n根据数据库的约定显式设置索引命名比使用sqlalchemy的默认命名方式更好。\n\n```jsx\nfrom sqlalchemy import MetaData\n\nPOSTGRES_INDEXES_NAMING_CONVENTION = {\n    \"ix\": \"%(column_0_label)s_idx\",\n    \"uq\": \"%(table_name)s_%(column_0_name)s_key\",\n    \"ck\": \"%(table_name)s_%(constraint_name)s_check\",\n    \"fk\": \"%(table_name)s_%(column_0_name)s_fkey\",\n    \"pk\": \"%(table_name)s_pkey\",\n}\nmetadata = MetaData(naming_convention=POSTGRES_INDEXES_NAMING_CONVENTION)\n```\n\n### 迁移工具Alembic\n\n1. 迁移必须是静态的且可回滚的。如果你的迁移依赖于动态生成的数据，那么确保只有数据本身是动态的，而不是其结构。\n2. 生成具有描述性名称和slug的迁移。slug是必需的，应该解释所做的更改。\n3. 为新迁移设置人类可读的文件模板。我们使用`date*_*slug*.py`模式，例如`2022-08-24_post_content_idx.py`\n\n```\n# alembic.ini\nfile_template = %%(year)d-%%(month).2d-%%(day).2d_%%(slug)s\n```\n\n### 设置数据库键命名约定\n\n保持名称的一致性很重要。我们遵循的一些规则：\n\n1. 小写蛇形命名（lower_case_snake）\n2. 单数形式（例如`post`、`post_like`、`user_playlist`）\n3. 用模块前缀对类似的表进行分组，例如`payment_account`、`payment_bill`、`post`、`post_like`\n4. 在表之间保持一致，但具体命名也可以，例如\n    1. 在所有表中使用`profile_id`，但如果其中一些表只需要作为创作者的个人资料，则使用`creator_id`\n    2. 在`post_like`、`post_view`等抽象表中使用`post_id`，但在相关模块中使用具体命名，如`chapters.course_id`中的`course_id`\n5. datetime类型字段使用`_at`后缀\n6. date类型字段使用`_date`后缀\n\n### SQL优先，Pydantic次之\n\n- 通常，数据库处理数据的速度比CPython快得多，也更简洁。\n- 最好使用SQL进行所有复杂的连接和简单的数据操作。\n- 最好在数据库中为具有嵌套对象的响应聚合JSON。\n\n```python\n# src.posts.service\nfrom typing import Any\n\nfrom pydantic import UUID4\nfrom sqlalchemy import desc, func, select, text\nfrom sqlalchemy.sql.functions import coalesce\n\nfrom src.database import database, posts, profiles, post_review, products\n\nasync def get_posts(\n    creator_id: UUID4, *, limit: int = 10, offset: int = 0\n) -> list[dict[str, Any]]: \n    select_query = (\n        select(\n            (\n                posts.c.id,\n                posts.c.slug,\n                posts.c.title,\n                func.json_build_object(\n                   text(\"'id', profiles.id\"),\n                   text(\"'first_name', profiles.first_name\"),\n                   text(\"'last_name', profiles.last_name\"),\n                   text(\"'username', profiles.username\"),\n                ).label(\"creator\"),\n            )\n        )\n        .select_from(posts.join(profiles, posts.c.owner_id == profiles.c.id))\n        .where(posts.c.owner_id == creator_id)\n        .limit(limit)\n        .offset(offset)\n        .group_by(\n            posts.c.id,\n            posts.c.type,\n            posts.c.slug,\n            posts.c.title,\n            profiles.c.id,\n            profiles.c.first_name,\n            profiles.c.last_name,\n            profiles.c.username,\n            profiles.c.avatar,\n        )\n        .order_by(\n            desc(coalesce(posts.c.updated_at, posts.c.published_at, posts.c.created_at))\n        )\n    )\n    \n    return await database.fetch_all(select_query)\n\n# src.posts.schemas\nfrom typing import Any\n\nfrom pydantic import BaseModel, UUID4\n\n   \nclass Creator(BaseModel):\n    id: UUID4\n    first_name: str\n    last_name: str\n    username: str\n\nclass Post(BaseModel):\n    id: UUID4\n    slug: str\n    title: str\n    creator: Creator\n\n    \n# src.posts.router\nfrom fastapi import APIRouter, Depends\n\nrouter = APIRouter()\n\n@router.get(\"/creators/{creator_id}/posts\", response_model=list[Post])\nasync def get_creator_posts(creator: dict[str, Any] = Depends(valid_creator_id)):\n   posts = await service.get_posts(creator[\"id\"])\n\n   return posts\n```\n\n### 从一开始就设置异步测试客户端\n\n使用数据库编写集成测试很可能在将来导致混乱的事件循环错误。立即设置异步测试客户端，例如[httpx](https://github.com/encode/starlette/issues/652)\n\n```python\nimport pytest\nfrom async_asgi_testclient import TestClient\n\nfrom src.main import app  # inited FastAPI app\n\n@pytest.fixture\nasync def client() -> AsyncGenerator[TestClient, None]:\n    host, port = \"127.0.0.1\", \"9000\"\n\n    async with AsyncClient(transport=ASGITransport(app=app, client=(host, port)), base_url=\"http://test\") as client:\n        yield client\n\n@pytest.mark.asyncio\nasync def test_create_post(client: TestClient):\n    resp = await client.post(\"/posts\")\n\n    assert resp.status_code == 201\n```\n\n除非你有同步数据库连接（抱歉？）或者不打算编写集成测试。\n\n### 使用ruff\n\n有了代码检查工具，你可以忘记代码格式化，专注于编写业务逻辑。\n\n[Ruff](https://github.com/astral-sh/ruff)是一个“速度极快”的新代码检查工具，它替代了black、autoflake、isort，并支持600多个检查规则。\n\n使用pre-commit钩子是一种流行的最佳实践，但对我们来说，只使用脚本就足够了。\n\n```bash\n#!/bin/sh -e\nset -x\n\nruff check --fix src\nruff format src\n```\n\n## 额外部分\n\n一些非常善良的人分享了他们自己的经验和最佳实践，绝对值得一读。\n\n查看项目的[issues（问题）](https://github.com/zhanymkanov/fastapi-best-practices/issues)部分。\n\n例如，[lowercase00](https://github.com/zhanymkanov/fastapi-best-practices/issues/4)详细描述了他们在权限和认证、基于类的服务和视图、任务队列、自定义响应序列化器、使用dynaconf进行配置等方面的最佳实践。\n\n如果你有关于使用FastAPI的经验要分享，无论是好是坏，都非常欢迎创建一个新的issue。我们很乐意阅读它。\n"
  }
]