示例:分层架构 CRUD API
一个「商品(Product)」资源的完整增删改查,按
app/分层组织:配置、数据库、模型、Schema、Repository、Service、路由各就各位。这是第 11 章的可运行版本,也是第 18 章实战的缩小版。
学习目标
- 能把一个资源的 CRUD 拆到正确的层级
- 理解 Repository 与 Service 的分工边界
- 掌握异步会话的依赖注入与事务边界
- 能用 Alembic 建表并用 curl 走完整流程
目录结构
text
crud-api/
├── README.md
├── pyproject.toml
├── .env.example
├── alembic.ini
├── migrations/
│ ├── env.py
│ └── versions/
├── app/
│ ├── __init__.py
│ ├── main.py # create_app:装配中间件与路由
│ ├── core/
│ │ └── config.py # Settings(pydantic-settings)
│ ├── db/
│ │ ├── base.py # DeclarativeBase + TimestampMixin
│ │ └── session.py # engine / async_sessionmaker / get_db
│ ├── models/
│ │ └── product.py
│ ├── schemas/
│ │ ├── common.py # Page[T]
│ │ └── product.py # ProductCreate / ProductUpdate / ProductOut
│ ├── repositories/
│ │ └── product.py
│ ├── services/
│ │ └── product.py
│ └── api/
│ ├── deps.py # SessionDep / ProductServiceDep
│ └── v1/
│ └── products.py
└── tests/
└── test_products.py关键文件代码要点
app/core/config.py —— 配置即对象
python
from functools import lru_cache
from pydantic import computed_field
from pydantic_settings import BaseSettings, SettingsConfigDict
class Settings(BaseSettings):
model_config = SettingsConfigDict(env_file=".env", extra="ignore")
app_name: str = "CRUD API"
debug: bool = False
postgres_user: str = "demo"
postgres_password: str = "demo"
postgres_host: str = "localhost"
postgres_port: int = 5432
postgres_db: str = "demo"
@computed_field
@property
def database_url(self) -> str:
return (
f"postgresql+asyncpg://{self.postgres_user}:{self.postgres_password}"
f"@{self.postgres_host}:{self.postgres_port}/{self.postgres_db}"
)
@lru_cache
def get_settings() -> Settings:
return Settings()app/db/session.py —— 会话与事务边界
python
engine = create_async_engine(settings.database_url, pool_pre_ping=True)
SessionLocal = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
async def get_db() -> AsyncGenerator[AsyncSession, None]:
async with SessionLocal() as session:
try:
yield session
await session.commit() # 一个请求 = 一个事务
except Exception:
await session.rollback()
raiseapp/models/product.py —— SQLAlchemy 2.0 写法
python
class Product(Base, TimestampMixin):
__tablename__ = "products"
id: Mapped[int] = mapped_column(primary_key=True)
sku: Mapped[str] = mapped_column(String(32), unique=True, index=True)
name: Mapped[str] = mapped_column(String(120), index=True)
price: Mapped[Decimal] = mapped_column(Numeric(10, 2))
stock: Mapped[int] = mapped_column(default=0)
is_active: Mapped[bool] = mapped_column(default=True, server_default="true")app/schemas/product.py —— 输入模型 ≠ 输出模型
python
class ProductCreate(BaseModel):
model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
sku: str = Field(min_length=3, max_length=32, pattern=r"^[A-Z0-9-]+$")
name: str = Field(min_length=1, max_length=120)
price: Decimal = Field(gt=0, decimal_places=2)
stock: int = Field(default=0, ge=0)
class ProductUpdate(BaseModel):
model_config = ConfigDict(extra="forbid", str_strip_whitespace=True)
name: str | None = Field(default=None, min_length=1, max_length=120)
price: Decimal | None = Field(default=None, gt=0, decimal_places=2)
stock: int | None = Field(default=None, ge=0)
is_active: bool | None = None
class ProductOut(BaseModel):
model_config = ConfigDict(from_attributes=True)
id: int
sku: str
name: str
price: Decimal
stock: int
is_active: bool
created_at: datetimeapp/repositories/product.py —— 只碰 SQL
python
class ProductRepository:
def __init__(self, session: AsyncSession) -> None:
self.session = session
async def get(self, product_id: int) -> Product | None:
return await self.session.get(Product, product_id)
async def list_paged(
self, *, offset: int, limit: int, q: str | None = None
) -> tuple[list[Product], int]:
conditions = [Product.is_active.is_(True)]
if q:
conditions.append(Product.name.ilike(f"%{q}%"))
base = select(Product).where(*conditions)
total = await self.session.scalar(select(func.count()).select_from(base.subquery()))
result = await self.session.execute(
base.order_by(Product.created_at.desc(), Product.id.desc())
.offset(offset)
.limit(limit)
)
return list(result.scalars().all()), total or 0
async def create(self, data: dict[str, object]) -> Product:
product = Product(**data)
self.session.add(product)
await self.session.flush() # 拿主键,提交交给 get_db
return product
async def update(self, product: Product, data: dict[str, object]) -> Product:
for key, value in data.items():
setattr(product, key, value)
await self.session.flush()
return product
async def delete(self, product: Product) -> None:
await self.session.delete(product)
await self.session.flush()app/services/product.py —— 只碰规则
python
class ProductService:
def __init__(self, repo: ProductRepository) -> None:
self.repo = repo
async def create(self, data: ProductCreate) -> Product:
if await self.repo.get_by_sku(data.sku) is not None:
raise ConflictError(f"SKU {data.sku!r} 已存在")
return await self.repo.create(data.model_dump())
async def get_or_404(self, product_id: int) -> Product:
product = await self.repo.get(product_id)
if product is None:
raise NotFoundError("商品", product_id)
return product
async def update(self, product_id: int, data: ProductUpdate) -> Product:
product = await self.get_or_404(product_id)
# 局部更新:只写客户端真正传了的字段
return await self.repo.update(product, data.model_dump(exclude_unset=True))NotFoundError / ConflictError 是自定义领域异常,由 main.py 注册的异常处理器映射为 404 / 409——Service 层完全不 import fastapi。
app/api/v1/products.py —— 只碰 HTTP
python
router = APIRouter(prefix="/products", tags=["products"])
@router.get("", response_model=Page[ProductOut])
async def list_products(
service: ProductServiceDep,
page: Annotated[int, Query(ge=1)] = 1,
size: Annotated[int, Query(ge=1, le=100)] = 20,
q: Annotated[str | None, Query(max_length=50)] = None,
) -> Page[ProductOut]:
return await service.list_page(page=page, size=size, q=q)
@router.post("", response_model=ProductOut, status_code=status.HTTP_201_CREATED)
async def create_product(payload: ProductCreate, service: ProductServiceDep) -> ProductOut:
return ProductOut.model_validate(await service.create(payload))
@router.get("/{product_id}", response_model=ProductOut)
async def get_product(
product_id: Annotated[int, Path(ge=1)], service: ProductServiceDep
) -> ProductOut:
return ProductOut.model_validate(await service.get_or_404(product_id))
@router.patch("/{product_id}", response_model=ProductOut)
async def update_product(
product_id: Annotated[int, Path(ge=1)],
payload: ProductUpdate,
service: ProductServiceDep,
) -> ProductOut:
return ProductOut.model_validate(await service.update(product_id, payload))
@router.delete("/{product_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_product(
product_id: Annotated[int, Path(ge=1)], service: ProductServiceDep
) -> None:
await service.delete(product_id)启动与迁移
bash
cd examples/crud-api
cp .env.example .env
uv sync
uv run alembic upgrade head # 建表
uv run fastapi dev app/main.py # 启动,默认 http://127.0.0.1:8000首次生成迁移:
bash
uv run alembic revision --autogenerate -m "create products"
uv run alembic upgrade head⚠️
--autogenerate依赖migrations/env.py里的target_metadata = Base.metadata,并且所有模型都要被 import 到,否则生成DROP TABLE。
用 curl 走一遍 CRUD
bash
BASE=http://127.0.0.1:8000/api/v11. 创建(201)
bash
curl -i -X POST $BASE/products \
-H "Content-Type: application/json" \
-d '{"sku":"KB-001","name":"机械键盘","price":"499.00","stock":12}'预期 HTTP/1.1 201 Created,响应体含 "id": 1 与 created_at。
2. 详情(200)
bash
curl -s $BASE/products/13. 列表 + 分页 + 搜索(200)
bash
curl -s "$BASE/products?page=1&size=10&q=键盘"预期结构:
json
{
"items": [{"id": 1, "sku": "KB-001", "name": "机械键盘"}],
"total": 1,
"page": 1,
"size": 10,
"pages": 1
}4. 局部更新(200)
bash
curl -i -X PATCH $BASE/products/1 \
-H "Content-Type: application/json" \
-d '{"stock": 99}'name 与 price 应保持不变——这正是 model_dump(exclude_unset=True) 的效果。
5. 唯一约束冲突(409)
bash
curl -i -X POST $BASE/products \
-H "Content-Type: application/json" \
-d '{"sku":"KB-001","name":"重复的 SKU","price":"1.00"}'预期 409 Conflict。
6. 校验失败(422)
bash
curl -i -X POST $BASE/products \
-H "Content-Type: application/json" \
-d '{"sku":"ab","name":"","price":"-1"}'预期 422,detail 数组里能看到 loc 指向 body.sku 等字段。
7. 删除(204,无响应体)
bash
curl -i -X DELETE $BASE/products/1预期 HTTP/1.1 204 No Content。之后再 GET 应得 404。
对应章节
- 分层结构设计 → 第 11 章:分层架构与 CRUD 工程化
- 异步引擎与会话 → 第 10 章:数据库集成(SQLAlchemy 2.0)
- 模型与校验 → 第 4 章:请求体与 Pydantic 模型
- 响应与状态码 → 第 5 章:响应模型与状态码
- 异常映射 → 第 8 章:错误处理与异常体系
👉 返回课程目录