zhanymkanov /fastapi-best-practices
FastAPI Best Practices and Conventions we used at our startup
★ 18,323⑂ 1,333👁 172⑃ 32● 64▤ 0
-2
日增长
+35
周增长
+151
月增长
18,323
stars
1,333
forks
172
watchers
32
prs
64
issues
0
releases
README
FastAPI Best Practices Opinionated list of best practices and conventions we use at our startups. After several years of building production systems, we've made both good and bad decisions that significantly impacted our developer experience. Here are some lessons worth sharing. Working with an AI agent? See AGENTS.md for the same rules in a terse, machine-readable format with a version matrix, Do/Don't blocks, and an anti-patterns checklist. 简体中文 Contents - Project Structure - Async Routes - I/O Intensive Tasks - CPU Intensive Tasks - Pydantic - Excessively use Pydantic - Custom Base Model - Decouple Pydantic BaseSettings - Dependencies - Beyond Dependency Injection - Chain Dependencies - Decouple \& Reuse dependencies. Dependency calls are cached - Prefer async dependencies - Miscellaneous - Follow the REST - FastAPI response serialization - If you must use sync SDK, then run it in a thread pool. - BackgroundTasks vs a real task queue - ValueErrors might become Pydantic ValidationError - Docs - Set DB keys naming conventions - Migrations. Alembic - Set DB naming conventions - SQL-first. Pydantic-second - Set tests client async from day 0 - Use ruff - Bonus Section Project Structure There are many ways to structure a project, but the best structure is one that is consistent, straightforward, and free of surprises. Many 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. The structure I found more scalable and evolvable is inspired by Netflix's Dispatch, with some minor modifications. fastapi-project ├── alembic/ ├── src │ ├── auth │ │ ├── router.py │ │ ├── schemas.py pydantic models │ │ ├── models.py db models │ │ ├── dependencies.py │ │ ├── config.py local configs │ │ ├── constants.py │ │ ├── exceptions.py │ │ ├── service.py │ │ └── utils.py │ ├── aws │ │ ├── client.py client model for external service communication │ │ ├── schemas.py │ │ ├── config.py │ │ ├── constants.py │ │ ├── exceptions.py │ │ └── utils.py │ ├── posts │ │ ├── router.py │ │ ├── schemas.py │ │ ├── models.py │ │ ├── dependencies.py │ │ ├── constants.py │ │ ├── exceptions.py │ │ ├── service.py │ │ └── utils.py │ ├── config.py global configs │ ├── models.py global models │ ├── exceptions.py global exceptions │ ├── pagination.py global module e.g. pagination │ ├── database.py db connection related stuff │ └── main.py ├── tests/ │ ├── auth │ ├── aws │ └── posts ├── templates/ │ └── index.html ├── requirements │ ├── base.txt │ ├── dev.txt │ └── prod.txt ├── .env ├── .gitignore ├── logging.ini └── alembic.ini 1. Store all domain directories inside src folder 1. src/ - highest level of an app, contai
Top issues
#4Our Experiences with a similar structure44 comments · 2022-08-26#63Fintech api structure, large api's5 comments · 2025-03-24#84[Decouple Pydantic BaseSettings] New way to read all needed settings, decoupled by project structure.2 comments · 2026-01-24#88How should API versioning (v1, v2) be handled in this project structure?1 comments · 2026-03-31#66Rename `router.py` to `routes.py` for better clarity1 comments · 2025-04-05#92README_ZH.md is missing several sections from the English version0 comments · 2026-07-20#87Incorrect statement: Pydantic model is created twice, actually it's validated twice and initialized once0 comments · 2026-03-22#86Object existence validation alternative0 comments · 2026-03-14