快速
- 作者仓库星标 0
- 作者仓库 skills-registry
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @tomevault-io · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- Python
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# FastAPI Conventions
## Route Handlers Are Thin
Validate input, call a service, return output. No business logic.
```python
router = APIRouter(prefix="/sessions", tags=["sessions"])
@router.post("", status_code=201, response_model=SessionResponse)
async def create_session(
body: CreateSessionRequest,
service: SessionService = Depends(get_session_service),
) -> SessionResponse:
return await service.create(body.topic)
```
## Dependency Injection
All dependencies in `app/core/dependencies.py`. Never instantiate services inside route handlers.
```python
@lru_cache
def get_settings() -> Settings:
return Settings()
async def get_session_service(
pool: asyncpg.Pool = Depends(get_db_pool),
settings: Settings = Depends(get_settings),
) -> SessionService:
return SessionService(pool=pool, settings=settings)
```
## Lifespan for Startup and Shutdown
```python
@asynccontextmanager
async def lifespan(app: FastAPI):
app.state.db_pool = await asyncpg.create_pool(settings.database_url)
yield
await app.state.db_pool.close()
app = FastAPI(lifespan=lifespan)
```
Do not use the deprecated `@app.on_event("startup")`.
## Response Model
Always declare `response_model=SomePydanticModel`. Never return raw dicts.
## Middleware Order
Register in this order (FastAPI processes in reverse registration order):
1. Correlation ID middleware (outermost)
2. CORS middleware
3. Rate limiting middleware
4. Request logging middleware (innermost)
## Global Exception Handlers
Register domain-to-HTTP mappings once in `app/core/middleware.py`:
```python
@app.exception_handler(SessionNotFoundError)
async def handler(request: Request, exc: SessionNotFoundError):
return JSONResponse(status_code=404, content={"code": "session_not_found", "message": str(exc)})
```
## Exception Hierarchy
Define in `app/core/exceptions.py`:
```python
class AppError(Exception):
"""Base exception for all application errors."""
class SessionNotFoundError(AppError): ...
class ReasoningValidationError(AppError):
def __init__(self, reason: str) -> None:
self.reason = reason
super().__init__(reason)
class InvalidEventTypeError(ReasoningValidationError): ...
```
- Services raise domain exceptions; global handlers map them to HTTP — never per-route
- Never raise `HTTPException` inside a service layer
- Never swallow exceptions silently with bare `except:`
---
> Source: [cheneeheng/agent-skills](https://github.com/cheneeheng/agent-skills) — distributed by [TomeVault](https://tomevault.io).
<!-- tomevault:4.0:skill_md:2026-05-22 -->
章节与文件索引
按说明文件中的顺序排列。
依赖注入
启动和关闭的寿命
响应模型
中间件订单
全局异常处理程序
文件/命令 -> app/core/dependencies.py · @app.on_event("startup") · response_model=SomePydanticModel · app/core/middleware.py · app/core/exceptions.py · HTTPException · except:
内容校验值 -> 8e4e8239c5c0
当前原文的自动摘译,尚未人工审校。
依赖注入
app/core/dependencies.py中的所有依赖项。切勿在路由处理程序内实例化服务。启动和关闭的寿命
不要使用已弃用的
@app.on_event("startup")。响应模型
始终声明
response_model=SomePydanticModel。永远不要返回原始字典。中间件订单
按此顺序注册(FastAPI按照相反的注册顺序处理): 关联 ID 中间件(最外层) CORS 中间件 限速中间件 请求记录中间件(最内层)
全局异常处理程序
在
app/core/middleware.py中注册一次域到 HTTP 映射: