Skip to content

示例:分层架构 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()
            raise

app/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: datetime

app/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/v1

1. 创建(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/1

3. 列表 + 分页 + 搜索(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。


对应章节 ​


👉 返回课程目录

本文阅读--次|全站访问--次|访客--人