api-route-design
在 FastAPI 中設計 RESTful API
設計 API 端點需要理解 HTTP 方法、驗證模式和回應標準。此技能為在 FastAPI 中構建穩健的 RESTful API 提供專家指導,包含適當的請求驗證、分頁和一致的回應格式。
스킬 ZIP 다운로드
Claude에서 업로드
설정 → 기능 → 스킬 → 스킬 업로드로 이동
토글을 켜고 사용 시작
테스트해 보기
"api-route-design" 사용 중입니다. 為 /users/ 建立帶分頁的 GET 端點
예상 결과:
- @router.get("/users/", response_model=PaginatedResponse[UserOut])
- async def list_users(
- skip: int = Query(0, ge=0),
- limit: int = Query(100, ge=1, le=1000),
- ) -> PaginatedResponse[UserOut]:
- users, total = await get_users(skip=skip, limit=limit)
- return PaginatedResponse(
- data=users,
- total=total,
- skip=skip,
- limit=limit,
- has_more=(skip + limit) < total,
- )
"api-route-design" 사용 중입니다. 建立帶 Pydantic 驗證的 POST 端點
예상 결과:
- class ItemCreate(BaseModel):
- name: str = Field(..., min_length=1, max_length=100)
- price: float = Field(..., gt=0)
- description: str | None = Field(None, max_length=500)
- @router.post("/items/", response_model=ItemOut, status_code=201)
- async def create_item(item_in: ItemCreate) -> ItemOut:
- return await create_item_db(item_in)
"api-route-design" 사용 중입니다. 設計錯誤回應格式
예상 결과:
- class ErrorResponse(BaseModel):
- error: str
- detail: str | None = None
- code: str | None = None
- # Usage in endpoint:
- raise HTTPException(
- status_code=status.HTTP_404_NOT_FOUND,
- detail="Item not found",
- )
보안 감사
안전All 84 static findings evaluated as false positives. The skill is a legitimate FastAPI API design reference document containing documentation and a validation script. The scanner incorrectly flagged regex flags (re.MULTILINE, re.DOTALL) as crypto algorithms, markdown code backticks as shell execution, and HTTP status codes as weak crypto. No actual security risks present.
품질 점수
만들 수 있는 것
建立新的 REST API 端點
建立新的 GET 端點以檢索分頁資源,包含篩選選項、適當的狀態碼和回應模型。
驗證 API 設計一致性
審查現有端點以確保遵循 REST 慣例、使用正確的狀態碼,並包含適當的請求/回應架構。
學習 FastAPI 路由模式
理解在 FastAPI 專案中定義路由、驗證輸入和組織回應的標準模式。
이 프롬프트를 사용해 보세요
建立一個 FastAPI GET 端點 /users/{user_id} 以返回使用者詳細資訊。包含路徑參數驗證、找不到使用者時的 404 處理,以及使用者資料的回應模型。設計一個 FastAPI GET 端點 /items/ 以返回分頁的項目列表。包含 skip 和 limit 查詢參數、按狀態篩選、排序選項,以及帶有 has_more 指示器的 PaginatedResponse 包裝器。
建立一個 POST 端點 /products/ 以接受產品建立請求。使用帶有欄位約束(例如 price > 0)的 Pydantic 模型進行驗證,成功時返回 201 狀態,並包含錯誤回應格式化。
為名為 'documents' 的資源設計完整的 CRUD 路由器,包括:帶分頁的列表、按 ID 取得、帶驗證的建立、使用 PATCH 更新,以及刪除端點。包含適當的狀態碼(建立使用 201、刪除使用 204)和錯誤處理。
모범 사례
- 集合端點使用複數名詞(/users 而非 /user),多字詞路徑使用 kebab-case(/student-fees)
- POST 建立返回 201,成功的 DELETE 無回應主體時返回 204,缺失資源返回 404
- 始終使用 response_model 參數,並用元資料(total、skip、limit、has_more)包裝分頁回應
피하기
- 使用 GET 進行狀態變更操作違反了 HTTP 語義和快取預期
- 成功和錯誤情況返回不同的回應結構會混淆 API 使用者
- 跳過 response_model 會移除自動 OpenAPI 文件和驗證優勢