FastAPI 写出第一个任务 API 路由、参数校验与自动文档-北京尧图网络

下午临时接到一个需求产品只留下一句话做一个能新增、查看和完成任务的接口。要是从路由、校验、接口文档全都手写半天大概就没了。FastAPI 有意思的地方在于Python 类型标注已经把这些信息写了一半。配套代码已经放在 fastapi-task-api文章中的完整实现以main分支为准。先把服务跑起来这个系列会做一个任务管理 API。第一篇故意不接数据库数据放在内存里。这样各位能先看清一件事HTTP 请求怎样变成 Python 函数调用再谈 PostgreSQL、Redis 这些后面的东西。uv init fastapi-task-api uv add fastapiuvicorn[standard]uv run uvicorn main:app--reload新建main.py先只保留健康检查。浏览器打开http://127.0.0.1:8000/docsSwagger UI 已经出现了。自动文档不是额外配置它来自路由、参数和模型的类型信息。fromfastapiimportFastAPI appFastAPI(titleTask API)app.get(/health)asyncdefhealth()-dict[str,str]:return{status:ok}# 给容器和负载均衡做健康检查路由不是把函数挂到 URL 上就结束了任务 API 至少需要创建、列表、详情、修改和删除五个动作。HTTP 方法表达动作URL 表达资源。把动词塞进 URL例如/createTask不是不能用只是客户端以后很难猜规则。HTTP 请求路由匹配Pydantic 校验Python 函数JSON 响应FastAPI 在函数调用前完成了中间两步。路径参数、查询参数和 JSON 请求体来自不同位置写法却很接近。fromenumimportStrEnumfrompydanticimportBaseModel,FieldclassTaskStatus(StrEnum):TODOtodoDONEdoneclassTaskCreate(BaseModel):title:strField(min_length1,max_length200)description:str|NoneField(defaultNone,max_length5000)classTaskRead(TaskCreate):id:intstatus:TaskStatusTaskCreate只允许客户端传入可写字段TaskRead才带上服务端生成的id和状态。请求模型与响应模型分开是 API 以后不容易失控的第一道门。做一组真的能调用的 CRUD内存列表不适合生产却很适合把注意力放在接口契约上。下面的代码省去了并发控制单进程演示足够。fromfastapiimportHTTPException,Query,status tasks:list[TaskRead][]app.post(/tasks,response_modelTaskRead,status_codestatus.HTTP_201_CREATED)asyncdefcreate_task(payload:TaskCreate)-TaskRead:taskTaskRead(idlen(tasks)1,statusTaskStatus.TODO,**payload.model_dump())tasks.append(task)returntaskapp.get(/tasks,response_modellist[TaskRead])asyncdeflist_tasks(skip:intQuery(0,ge0),limit:intQuery(20,ge1,le100)):returntasks[skip:skiplimit]# 查询参数天然支持分页app.get(/tasks/{task_id},response_modelTaskRead)asyncdefread_task(task_id:int)-TaskRead:tasknext((itemforitemintasksifitem.idtask_id),None)iftaskisNone:raiseHTTPException(status_code404,detailTask not found)returntask试着提交一个空标题响应会是422里面带有字段路径和失败原因。这个错误不是我们手写出来的。Pydantic 在函数执行前发现min_length不满足于是请求不会碰到业务代码。参数校验解决的是边界问题很多项目一开始会把title当普通字符串收下再到数据库报错时回头补校验。这个路径很绕。输入靠近接口边界时就应该被拒绝后面的服务函数才不必反复猜测数据能不能用。状态筛选同样可以交给类型系统。枚举值以外的字符串不会进入函数。app.get(/tasks)asyncdeflist_by_status(status:TaskStatus|NoneNone)-list[TaskRead]:ifstatusisNone:returntasksreturn[taskfortaskintasksiftask.statusstatus]这里还有一个容易踩的坑。路径/tasks/{task_id}和静态路径/tasks/search同时存在时静态路径要先注册。不然search会被当成task_id然后得到很迷惑的校验错误。自动文档为什么值得认真对待/docs不只是演示页。它同时给前端、测试人员和未来的自己看。模型字段的描述、状态码、响应模型都会进入 OpenAPI 定义客户端 SDK 或接口平台也能据此生成调用代码。先把接口边界写清楚后面的数据库和鉴权才有地方落脚。到这里我们已经有一个能创建和查询任务的 API。它离上线还很远重启就丢数据多人使用也没有边界。但路由、模型、校验和文档这四根骨架已经立住了。下一篇把list换成 PostgreSQL 查询任务才真正留下来。本篇收口FastAPI 从函数签名推导参数校验和 OpenAPI 文档Pydantic 模型把可写数据和返回数据分开422用来报告不合格输入404用来报告不存在的资源内存 CRUD 只负责讲清接口形状持久化交给下一篇

FastAPI 写出第一个任务 API 路由、参数校验与自动文档

相关推荐

给初学者的后端技术栈地图，少走弯路指南

LightGBM GPU加速技术突破：实现百倍性能提升的工程实践

SpringBoot微服务架构在车辆综合服务平台中的实践

更多资讯

如何为 easy-loading-cj 添加第 28 种动画？从零实现新指示器的完整步骤

UC网盘直链解析原理：不登录下载的底层逻辑与实操

从零理解Online Judge：OJ判题原理、平台选择与刷题排错全攻略

Qt QPalette配色机制详解：从原理到实战，彻底掌控控件颜色

Blender4.2 + CLI-Anything 建模批量工程环境部署记录（二）：TaoToken 统一 Key 接入 Codex 与 BlenderMCP 的 config.toml 骨架

B站视频接口批量抓取实战：视频列表与详情数据采集全指南

今日更新

AI元人文：从工具使用到思维重构的深度探索

Python+CNN车牌识别实战：从数据预处理到模型训练与部署

Vim基础操作全攻略：保存退出、模式切换与高频命令实战

本周精选

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？