什么是 FastAPI？

这项技能使开发人员能够使用 FastAPI 框架构建生产级的 Python API。它专注于 Python 的现代特性，如类型提示和 async/await 语法，以交付高性能应用程序。通过将其集成到 Openclaw Skills 中，用户可以立即获得处理异步陷阱、Pydantic v2 验证和高效依赖注入的最佳实践。

无论您是在构建微服务还是复杂的 Web 后端，此技能都能确保您的代码保持可扩展、可维护且类型安全。它通过提供寿命管理、错误处理和安全性的清晰模式，弥合了快速原型设计与企业级部署之间的差距。

下载入口:https://github.com/openclaw/skills/tree/main/skills/ivangdavila/fastapi

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

FastAPI 应用场景

• 使用 asyncpg 等异步驱动程序设计高并发微服务。
• 使用 Pydantic 模型和 Field 工厂实现强大的数据验证。
• 通过 lifespan 上下文管理器管理数据库连接池等共享资源。
• 为现代 Web 应用程序构建符合 OAuth2 标准的安全身份验证系统。
• 将非阻塞操作卸载到 BackgroundTasks 以提高响应时间。

1. 使用具有定义寿命（lifespan）的 FastAPI 类初始化应用程序以进行资源管理。
2. 使用 Pydantic 定义数据模型，以确保自动请求验证和序列化。
3. 使用 async/await 语法创建异步路径操作，以防止事件循环阻塞。
4. 使用 Depends() 实现依赖注入，以管理可重用逻辑和数据库会话。
5. 配置全局或特定路由的异常处理程序来管理错误并返回标准 JSON 响应。

FastAPI 配置指南

确保您的系统上安装了 python3。此技能适用于 Openclaw Skills 支持的 Linux、macOS 和 Windows 系统。

pip install fastapi uvicorn

要初始化具有适当上下文的项目，请创建一个 main.py 文件，并在 lifespan 上下文管理器中配置您的应用程序状态，以处理启动和关闭逻辑。

FastAPI 数据架构与分类体系

name: FastAPI
description: Build fast, production-ready Python APIs with type hints, validation, and async support.
metadata: {"clawdbot":{"emoji":"?","requires":{"bins":["python3"]},"os":["linux","darwin","win32"]}}

FastAPI Patterns

Async Traps

• Mixing sync database drivers (psycopg2, PyMySQL) in async endpoints blocks the event loop — use async drivers (asyncpg, aiomysql) or run sync code in run_in_executor
• time.sleep() in async endpoints blocks everything — use await asyncio.sleep() instead
• CPU-bound work in async endpoints starves other requests — offload to ProcessPoolExecutor or background workers
• Async endpoints calling sync functions that do I/O still block — the entire call chain must be async

Pydantic Validation

• Default values in models become shared mutable state: items: list = [] shares the same list across requests — use Field(default_factory=list)
• Optional[str] doesn't make a field optional in the request — add = None or use Field(default=None)
• Pydantic v2 uses model_validate() not parse_obj(), and model_dump() not .dict() — v1 methods are deprecated
• Use Annotated[str, Field(min_length=1)] for reusable validated types instead of repeating constraints

Dependency Injection

• Dependencies run on every request by default — use lru_cache on expensive dependencies or cache in app.state for singletons
• Depends() without an argument reuses the type hint as the dependency — clean but can confuse readers
• Nested dependencies form a DAG — if A depends on B and C, and both B and C depend on D, D runs once (cached per-request)
• yield dependencies for cleanup (DB sessions, file handles) — code after yield runs even if the endpoint raises

Lifespan and Startup

• @app.on_event("startup") is deprecated — use lifespan async context manager
• Store shared resources (DB pool, HTTP client) in app.state during lifespan, not as global variables
• Lifespan runs once per worker process — with 4 Uvicorn workers you get 4 DB pools

from contextlib import asynccontextmanager
@asynccontextmanager
async def lifespan(app):
    app.state.db = await create_pool()
    yield
    await app.state.db.close()
app = FastAPI(lifespan=lifespan)

Request/Response

• Return dict from endpoints, not Pydantic models directly — FastAPI handles serialization and it's faster
• Use status_code=201 on POST endpoints returning created resources — 200 is the default but semantically wrong
• Response with media_type="text/plain" for non-JSON responses — returning a string still gets JSON-encoded otherwise
• Set response_model_exclude_unset=True to omit None fields from response — cleaner API output

Error Handling

• raise HTTPException(status_code=404) — don't return Response objects for errors, it bypasses middleware
• Custom exception handlers with @app.exception_handler(CustomError) — but remember they don't catch HTTPException
• Use detail= for user-facing messages, log the actual error separately — don't leak stack traces

Background Tasks

• BackgroundTasks runs after the response is sent but still in the same process — not suitable for long-running jobs
• Tasks execute sequentially in order added — don't assume parallelism
• If a background task fails, the client never knows — add your own error handling and alerting

Security

• OAuth2PasswordBearer is for documentation only — it doesn't validate tokens, you must implement that in the dependency
• CORS middleware must come after exception handlers in middleware order — or errors won't have CORS headers
• Depends(get_current_user) in path operation, not in router — dependencies on routers affect all routes including health checks

Testing

• TestClient runs sync even for async endpoints — use httpx.AsyncClient with ASGITransport for true async testing
• Override dependencies with app.dependency_overrides[get_db] = mock_db — cleaner than monkeypatching
• TestClient context manager ensures lifespan runs — without with TestClient(app) as client: startup/shutdown hooks don't fire