一、項目背景與定位

FastCRUD 是一個為 FastAPI + SQLAlchemy 場景設計的開源庫，由 Benav Labs 維護，旨在簡化 CRUD 端點搭建與數(shù)據(jù)庫操作的流程。其 GitHub 倉庫描述如下：

“FastCRUD is a Python package for FastAPI, offering robust async CRUD operations and flexible endpoint creation utilities.” ([GitHub][1])

核心特性包括：全異步、支持 SQLAlchemy 2.0、支持 joins、支持動態(tài)排序、支持 offset 和 cursor 分頁。([GitHub][1])

為什么會有這樣一個庫？

在使用 FastAPI + SQLAlchemy 時，開發(fā)典型的 CRUD 接口（Create／Read／Update／Delete）往往需要重復以下工作：

• 定義 SQLAlchemy 模型（Model）和 Pydantic 模型（Schema）
• 編寫增刪改查邏輯（Session 管理、commit/refresh、異常處理）
• 在路由里創(chuàng)立對應的 endpoint、設置依賴、處理分頁／排序／過濾
• 如果涉及多表關聯(lián)（join）或復雜查詢，則代碼量又進一步增加

FastCRUD 正是在這樣的場景下誕生：通過抽象通用的 CRUD 操作以及自動生成路由，幫助你用更少的代碼快速搭建 API 原型或輕量服務。

例如，在一篇作者介紹文章中提到：“你寫了很多重復代碼…用 FastCRUD，這些代碼可以顯著減少”。([Medium][2])

二、核心特性解析

下面逐條解析 FastCRUD 提供的主要特性，并討論其背后的價值。

2.1 全異步 (Async)

FastCRUD 建立于 FastAPI + SQLAlchemy 異步模型之上，支持 AsyncSession 等異步 API。GitHub 上標注為 “?? Fully Async”。([GitHub][1])

• 優(yōu)勢：在高并發(fā) HTTP 請求場景下，更好地利用 I/O 等待時間，不阻塞事件循環(huán)。
• 注意事項：你的數(shù)據(jù)庫驅動、SQLAlchemy 版本、session 配置必須配合異步使用，否則可能出現(xiàn)混用同步/異步問題。

2.2 支持 SQLAlchemy 2.0

FastCRUD 要求 SQLAlchemy 版本為 2.0+。([PyPI][3])

• 優(yōu)勢：利用最新 SQLAlchemy 的特性（如 2.0 風格的 API、async 支持、改進的 ORM 性能）。
• 注意事項：如果項目還在用 SQLAlchemy 1.x，升級成本可能不低。

2.3 強大的 CRUD 功能 + 自動生成端點

FastCRUD 在 CRUD 操作方面提供了：create, get, exists, count, get_multi 等通用方法。([PyPI][3]) 此外，它還提供 crud_router，允許你幾行代碼就生成一個標準的 CRUD 路由器。示例如下：([GitHub][1])

item_router = crud_router(
    session=get_session,
    model=Item,
    create_schema=ItemCreateSchema,
    update_schema=ItemUpdateSchema,
    path="/items",
    tags=["Items"],
)
app.include_router(item_router)

• 優(yōu)勢：極大縮短原型開發(fā)時間；適合 CRUD 密集型服務、后臺管理系統(tǒng)。
• 注意事項：自動生成的端點雖然方便，但在復雜業(yè)務（權限、校驗、復雜邏輯）下可能需要手工調整或替換。

2.4 復雜查詢能力：動態(tài)排序／分頁／聯(lián)表 (joins)

FastCRUD 支持以下特性：

• 自動檢測 Join 條件 (join 操作) ([GitHub][1])
• 排序 (sort_columns, sort_orders) 和分頁 (offset／cursor) ([PyPI][3])
• Cursor 分頁適合“無限滾動”場景。([PyPI][3])
• 優(yōu)勢：相比自己手寫 select + joins + pagination，這些常見需求已經封裝好。
• 注意事項：雖然支持 join，但并不是萬能（例如非常復雜的自定義 SQL、視圖、CTE、子查詢等可能還是需要手寫）。

2.5 模塊化 & 可擴展設計

FastCRUD 聲稱自己是 “Modular and Extensible”。([GitHub][1])

• 意味著你可以繼承、覆蓋默認行為（比如你想添加軟刪除字段、審計字段、特定校驗等）。
• 對于標準化服務非常有用，但一定要看文檔／源碼以了解擴展方式。

三、快速上手示例

下面通過一個簡單的 “Items” 模型示例演示如何使用 FastCRUD。

3.1 環(huán)境準備

假設你已經安裝了：

pip install fastcrud

并且項目中已有 FastAPI／SQLAlchemy 2 配置。根據(jù) PyPI 信息：FastCRUD 要求 Python 3.9+、SQLAlchemy 2.0.21+、Pydantic 2.4.1+。([PyPI][3])

3.2 定義模型與 schema

models.py：

from sqlalchemy import Column, Integer, String
from sqlalchemy.orm import DeclarativeBase

class Base(DeclarativeBase):
    pass

class Item(Base):
    __tablename__ = 'items'
    id = Column(Integer, primary_key=True)
    name = Column(String)
    description = Column(String)

schemas.py：

from pydantic import BaseModel

class ItemCreateSchema(BaseModel):
    name: str
    description: str

class ItemUpdateSchema(BaseModel):
    name: str
    description: str

3.3 應用配置 & 路由自動生成

main.py：

from fastapi import FastAPI
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
from sqlalchemy.orm import sessionmaker
from fastcrud import crud_router
from models import Base, Item
from schemas import ItemCreateSchema, ItemUpdateSchema

DATABASE_URL = "sqlite+aiosqlite:///./test.db"
engine = create_async_engine(DATABASE_URL, echo=True)
async_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)

async def get_session() -> AsyncSession:
    async with async_session() as session:
        yield session

async def lifespan(app: FastAPI):
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)
    yield

app = FastAPI(lifespan=lifespan)

item_router = crud_router(
    session=get_session,
    model=Item,
    create_schema=ItemCreateSchema,
    update_schema=ItemUpdateSchema,
    path="/items",
    tags=["Items"],
)
app.include_router(item_router)

啟動后，你就會在 /docs 中看到 CRUD 接口（例如 POST /items/, GET /items/{id}, PATCH /items/{id}, DELETE /items/{id}，列表接口等）。這個省去了大量重復代碼。文章中即有示例。([Medium][2])

3.4 在自定義路由中使用

如果你需要更靈活控制，比如在路徑、邏輯、權限等方面，F(xiàn)astCRUD 也支持直接用其 FastCRUD 類。示例：([PyPI][3])

from fastcrud import FastCRUD

item_crud = FastCRUD(Item)

@app.post("/custom/items/")
async def create_item(item_data: ItemCreateSchema, db: AsyncSession = Depends(get_session)):
    return await item_crud.create(db, item_data)

@app.get("/custom/items/{item_id}")
async def read_item(item_id: int, db: AsyncSession = Depends(get_session)):
    item = await item_crud.get(db, id=item_id)
    if not item:
        raise HTTPException(status_code=404, detail="Item not found")
    return item

這樣你保留了自定義控制流，同時利用其 CRUD 基礎邏輯。

四、深入機制剖析

4.1 CRUD 類的方法

根據(jù)文檔，F(xiàn)astCRUD 提供若干關鍵方法（摘錄自 PyPI）：

• create(db, object: CreateSchemaType) -> ModelType
• get(db, schema_to_select: Optional[...] = None, **kwargs)
• exists(db, **kwargs) -> bool
• count(db, **kwargs) -> int
• get_multi(db, offset=0, limit=100, schema_to_select=None, sort_columns=None, sort_orders=None, return_as_model=False, **kwargs) -> dict[str, Any]
• update(db, object: Union[UpdateSchemaType, dict], **kwargs)
• delete(db, db_row=None, **kwargs)（軟刪除）
• db_delete(db, **kwargs)（硬刪除）

此外還有更高級如 get_joined、get_multi_joined、get_multi_by_cursor 等用于 join 和 cursor 分頁。([PyPI][3])

4.2 自動生成 Router 的機制

crud_router 的實現(xiàn)會內部創(chuàng)建標準的 FastAPI 路由（POST、GET、PATCH、DELETE、列表等），并且使用上面 CRUD 方法作為 handler。它還接受 session factory、model、schema、path、tags 等參數(shù)。通過這層抽象，開發(fā)者并不需要每次手動寫路由定義。

4.3 Pagination & Sorting

• Offset 分頁：通過 offset + limit 參數(shù)在 get_multi 方法中支持。
• Cursor 分頁：通過 get_multi_by_cursor 支持，該方法接受 cursor, limit, sort_column, sort_order 參數(shù)。
• Sorting：可以傳入 sort_columns 和 sort_orders 對應列與方向。

這些都是常見但自己手寫較繁瑣的邏輯，使用 FastCRUD 可以省掉不少代碼。

4.4 Join 支持

get_joined 與 get_multi_joined 方法支持將主模型與其它模型做關聯(lián)查詢。對于 ORM 模型間關系（ForeignKey、relationship）或顯式 join_on 條件，F(xiàn)astCRUD 支持自動檢測 join 條件。([GitHub][1]) 不過，這里也有“隱藏成本”——如果你的 join 邏輯非常定制（如多級 join、復雜子查詢、聚合等），仍可能需要手寫 SQL。

五、優(yōu)點 & 使用場景

優(yōu)點

• 開發(fā)效率高：特別是內部后臺服務、CRUD 為主的 API，可以快速上線。
• 代碼統(tǒng)一：CRUD 操作集中到類庫里，減少重復 Boilerplate。
• 現(xiàn)代技術棧支持：異步、SQLAlchemy 2.0、Pydantic 2.x、FastAPI。
• 可擴展：可以在標準之上加入自定義邏輯。
• 自動路由生成：適合快速原型或內部工具。

使用場景

• 企業(yè)內部后臺管理系統(tǒng)（如用戶、權限、產品、訂單管理）
• 微服務中 CRUD 密集但業(yè)務邏輯相對簡單的場景
• 快速原型驗證，尤其想用 FastAPI 很快搭建接口
• 想統(tǒng)一標準 CRUD 模型、減少重復代碼的團隊

六、局限性 &注意事項

局限性

• 復雜業(yè)務邏輯的靈活性：當業(yè)務流程包含大量自定義校驗、復雜事務、跨模型操作、子查詢/聚合時，自動生成的 CRUD 路徑可能不夠，需要手寫或擴展。
• ORM 歷史或依賴限制：如果項目仍在用 SQLAlchemy 1.x 或者不同 ORM（如 Tortoise ORM、ORMlite）則不適用。
• 文檔或社區(qū)投入：雖然有基本文檔，但相比成熟框架/庫，可能在邊緣場景（例如非常復雜 join、特殊數(shù)據(jù)庫類型）支持較少。Reddit 上就有用戶反饋文檔在 “why use this” 和 “how exactly generated endpoints look” 方面資料不夠詳盡。([Reddit][4])
• 自動化可能隱藏細節(jié)：自動 endpoint 雖然方便，但你可能不清楚默認行為（如軟刪除、異常處理、返回格式）細節(jié)。建議在生產環(huán)境使用前明確行為。

注意事項

• 確保數(shù)據(jù)模型設計良好（主鍵、關系、索引、外鍵等清晰），以便 join 機制能順利工作。
• 如果數(shù)據(jù)庫字段類型比較特殊（例如使用 sqlalchemy-utils 的特殊列類型），F(xiàn)astCRUD 文檔中提到可能會拋出 NotImplementedError，需要你為該列類型添加 python_type 屬性。([GitHub][1])
• 在使用 crud_router 生成路由時，默認假設主鍵字段名為 id（至少在某些版本中如此）——根據(jù) PyPI 描述：“For now, your primary column must be named id or automatic endpoint creation will not work.” ([PyPI][3])
• 生產環(huán)境中，建議你對生成的端點加入權限驗證、訪問日志、異常統(tǒng)一處理等中間件，而不僅僅依賴自動路由。
• 針對分頁/排序/過濾的安全考慮（如防止 offset 太大、cursor 被濫用、排序字段注入等）也要做好防護。

七、實戰(zhàn)建議與最佳實踐

• 從原型階段開始使用自動 router：在項目初期快速搭建 CRUD 路由，驗證業(yè)務模型、前端交互、數(shù)據(jù)結構。
• 根據(jù)需求分層使用：對于標準 CRUD 模型（如很多后臺表格接口），使用 crud_router；對于需要復雜邏輯/權限控制的路由，使用 FastCRUD 類結合自定義邏輯。
• 注重 schema 與模型分離：仍然建議你定義清晰的 Pydantic schema（Create/Update/Read），規(guī)范輸入輸出；避免直接暴露 ORM 模型。
• 做好分頁、排序、過濾標準：即便庫封裝好了，也建議在文檔中明確你的分頁策略、最大限制、默認排序。
• 審查自動生成的路由：仔細查看自動生成的路徑、方法、返回類型、異常處理，確保滿足你團隊合同／API規(guī)范。
• 避免過早升級：雖然庫支持 SQLAlchemy 2.0，但如果你的項目還在使用 1.x，最好先評估升級影響。
• 關注社區(qū)與維護狀態(tài)：雖然目前版本可用（截至 2024 年初發(fā)布 0.1.4）([PyPI][3])，但生產環(huán)境應監(jiān)控庫更新、issue 響應情況、社區(qū)反饋。

八、總結

FastCRUD 是一個非常實用的工具，尤其適合你希望用 FastAPI 快速搭建 CRUD 接口、減少重復代碼、聚焦核心業(yè)務邏輯的場景。它通過全異步支持、SQLAlchemy 2.0、自動路由生成、分頁排序 join 支持等特性，實現(xiàn)了 “少寫代碼、快上線” 的目標。但同時，它并不是萬能——對于復雜業(yè)務、深度定制、非標準模型或者非 SQLAlchemy ORM 環(huán)境，仍需謹慎使用。

在未來，如果你的項目方向是構建一個標準化、可維護、高效的后端服務，F(xiàn)astCRUD 可以作為一個優(yōu)秀的 “CRUD 基礎層”。你可以把它作為 標準 CRUD 模型生成器 + 自定義邏輯插件層，形成 “自動化 + 可擴展” 的架構。

以上就是Python使用FastAPI+FastCRUD自動生成API接口的實現(xiàn)的詳細內容，更多關于Python FastAPI+FastCRUD生成API接口的資料請關注腳本之家其它相關文章！

最新評論