Rodin
73 lines
2.6 KiB
Markdown
73 lines
2.6 KiB
Markdown
# FastAPI Conventions
|
|
|
|
**Descriptive first, prescriptive second.** This repo captures how mature FastAPI-adjacent codebases structure web services, then distills the conventions worth following.
|
|
|
|
Use this repo for framework and service-boundary concerns that do **not** belong in a language-level Python patterns repo.
|
|
|
|
## Structure
|
|
|
|
- `patterns/` — route, dependency, schema, persistence, error, and testing conventions
|
|
- `comparison/` — where FastAPI conventions differ from broader Python patterns
|
|
- `sources/` — upstream notes, code excerpts, and rationale
|
|
- `PROCESS.md` — the repeatable extraction/refinement workflow used to build this repo
|
|
|
|
## Current source base
|
|
|
|
Primary upstreams mined so far:
|
|
- `fastapi/fastapi`
|
|
- `encode/starlette`
|
|
- `pydantic/pydantic`
|
|
- `encode/httpx`
|
|
- `fastapi-users/fastapi-users`
|
|
- `fastapi/full-stack-fastapi-template`
|
|
|
|
Why this mix works:
|
|
- FastAPI: router composition, dependencies, semantic exceptions, override-based testing seams
|
|
- Starlette: lifespan, middleware, exception-layer mechanics, application assembly
|
|
- Pydantic: request/response model boundaries and validation/serialization caveats
|
|
- HTTPX: ASGI and transport-based testing seams
|
|
- FastAPI Users: dependency-driven auth and router factory patterns
|
|
- Full-stack FastAPI Template: real service module structure, session/auth wiring, and schema transitions
|
|
|
|
## Current convention set
|
|
|
|
- `patterns/routes.md`
|
|
- `patterns/dependencies.md`
|
|
- `patterns/pydantic-boundaries.md`
|
|
- `patterns/errors.md`
|
|
- `patterns/persistence.md`
|
|
- `patterns/testing.md`
|
|
- `comparison/fastapi-vs-python.md`
|
|
|
|
## What belongs here
|
|
|
|
Examples:
|
|
- thin route handlers vs embedded business logic
|
|
- request/response schema boundaries
|
|
- dependency injection shape and lifetime
|
|
- error envelope and exception translation
|
|
- app startup/shutdown and resource wiring
|
|
- sync/async boundaries at the HTTP layer
|
|
|
|
## What does **not** belong here
|
|
|
|
Do not duplicate generic Python rules unless FastAPI deliberately bends them. Link back to `python-patterns` instead.
|
|
|
|
## Reviewing this repo
|
|
|
|
Recommended review order:
|
|
1. `README.md`
|
|
2. `PROCESS.md`
|
|
3. `sources/*.md` for evidence quality
|
|
4. `patterns/*.md` for synthesis quality
|
|
5. `comparison/*.md` for split-of-concerns clarity
|
|
|
|
Questions to ask during review:
|
|
- Is the guidance actually FastAPI/service-boundary specific?
|
|
- Are framework seams described where the framework really owns behavior?
|
|
- Are testing and dependency claims grounded in real source and tests?
|
|
- Are caveats preserved instead of over-generalized?
|
|
|
|
## Core rule
|
|
|
|
Do not write convention docs from memory. First collect repeated upstream examples with `file:line` citations, then synthesize the convention. |