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)
安全与权限
- 需要登录：使用依赖注入的认证中间件
- 敏感操作：校验权限/角色
- 限流：按需配置