下午临时接到一个需求产品只留下一句话做一个能新增、查看和完成任务的接口。要是从路由、校验、接口文档全都手写半天大概就没了。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 只负责讲清接口形状持久化交给下一篇