FastAPI 接口设计规范#

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

何时使用#

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

项目结构#

text

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 /usersPUT全量更新PUT /users/{id}PATCH部分更新PATCH /users/{id}DELETE删除DELETE /users/{id}

3. 统一响应格式#

python

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

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

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

4. 错误处理#

python

from tkms.exception.api import ApiException

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

5. 入参校验#

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

6. 分页规范#

python

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

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

示例模板#

python

# 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)

安全与权限#

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