GI API Design FastAPI

Design and implement RESTful API endpoints following FastAPI best practices. Use when creating new API routes, designing request/response schemas, or when th...

Security Scan

An instruction-only FastAPI API design guideline: its requirements, scope, and instructions are consistent with the described purpose and it does not request credentials or perform installs.

Purpose & Capability

The name/description (FastAPI API design) matches the SKILL.md content: routing, DTO/VO patterns, Pydantic validation, error handling, and example router code. No unrelated binaries, env vars, or permissions are requested.

Instruction Scope

SKILL.md contains design rules and example code templates referencing project paths (app/router, app/service, etc.) and the tkms framework. It does not instruct reading arbitrary system files, accessing credentials, or transmitting data to external endpoints. Scope is limited to API design/implementation guidance.

Install Mechanism

No install spec and no code files — instruction-only. Nothing will be downloaded or written to disk by an installer.

Credentials

No environment variables, credentials, or config paths are required. The skill references a 'tkms' package and project layout but does not request secrets or external service tokens.

Persistence & Privilege

always is false and the skill is user-invocable. It does not request persistent presence or attempt to modify other skills or system-wide settings.

Assessment

This skill is a template/guideline for designing FastAPI endpoints and appears coherent and low-risk: it doesn't ask for credentials or install software. Before use, confirm your codebase uses the referenced 'tkms' conventions or adapt the templates to your stack; review generated code for security (authentication, authorization, input validation, error handling, rate limiting) before deploying to production. If you don't trust the skill author, avoid copying code verbatim into sensitive systems.

FastAPI 接口设计规范

按照项目规范设计并实现 RESTful API，适用于 tkms + FastAPI 技术栈。

何时使用

• 用户请求「设计一个接口」「新增 API」「写个路由」
• 设计请求/响应结构
• 实现 app/router 下的新端点

项目结构

app/
├── router/     # 路由定义
├── service/    # 业务逻辑
├── dao/        # 数据访问
└── model/
    ├── dto/    # 入参（请求体、查询参数）
    ├── entity/ # 数据库实体
    └── vo/     # 出参（响应体）

设计原则

1. 路由命名

• 资源用复数名词：/users、/orders
• 嵌套资源：/users/{user_id}/orders
• 动作用动词：/orders/{id}/cancel（POST）

2. HTTP 方法

方法	用途	示例
GET	查询	GET /users, GET /users/{id}
POST	创建	POST /users
PUT	全量更新	PUT /users/{id}
PATCH	部分更新	PATCH /users/{id}
DELETE	删除	DELETE /users/{id}

3. 统一响应格式

# 成功
{"code": 0, "message": "success", "data": {...}}

# 分页
{"code": 0, "data": {"list": [...], "total": 100}}

# 错误（由 ApiException 统一处理）
{"code": 400, "message": "参数错误"}

4. 错误处理

from tkms.exception.api import ApiException

# 业务异常
raise ApiException(code=400, message="用户不存在")

5. 入参校验

• 使用 Pydantic 模型（dto）
• 路径参数：user_id: int
• 查询参数：Query(..., description="")
• 请求体：Body(...) 或直接声明

6. 分页规范

# 入参
page: int = Query(1, ge=1)
page_size: int = Query(20, ge=1, le=100)

# 出参
{"list": [...], "total": 100}

示例模板

# router/user.py
from fastapi import APIRouter, Depends
from app.model.dto.user_dto import UserCreateDto, UserUpdateDto
from app.model.vo.user_vo import UserVo
from app.service.user_service import UserService

router = APIRouter(prefix="/users", tags=["用户"])

@router.post("", response_model=UserVo)
async def create_user(dto: UserCreateDto, service: UserService = Depends()):
    return await service.create(dto)

@router.get("/{user_id}", response_model=UserVo)
async def get_user(user_id: int, service: UserService = Depends()):
    return await service.get_by_id(user_id)

安全与权限

• 需要登录：使用依赖注入的认证中间件
• 敏感操作：校验权限/角色
• 限流：按需配置