到了这一节，我们会开始把前面学过的类型标注、数据建模、异常处理和模块组织能力，真正带进一个现代 Python Web 框架里。FastAPI 之所以受欢迎，很大一部分原因就在于它把类型、校验和文档协同得非常自然。
这一节不会追求把一个项目一次性做完，而是先把 FastAPI 最核心的使用体验摸清楚：如何声明路由、接收参数、做数据校验、组织依赖以及维护统一的接口风格。
为什么 FastAPI 很适合作为入门框架？
FastAPI 的优势并不只是“快”，更重要的是它把现代 Python 工程里很多好习惯天然串起来了。
例如：
- 路由声明清晰；
- 类型标注直接参与参数解析和文档生成；
- Pydantic 模型让请求和响应结构更明确；
- 异步能力和现代 Web 服务场景契合度高。
所以它特别适合作为“把 Python 语言能力过渡到 Web 服务能力”的第一站。
项目初始化与目录结构
一个最小可维护的 FastAPI 项目，通常至少应该区分：
- 应用入口；
- 路由层；
- 数据模型；
- 服务层；
- 配置管理。
这意味着你不要一上来就把所有路由、模型和数据库代码都塞进 main.py。哪怕项目还小，也应该尽早给未来演进留出结构边界。
FastAPI 本身不会强迫你用某个固定目录结构，但这也意味着你更需要主动组织好边界。
如果你希望先有一个稳定起点，可以先按这种最小结构理解：
app/
main.py
schemas.py
deps.py
routers/
articles.py这个结构不算复杂，但已经足够表达几件重要的事：
main.py负责组装应用；routers/负责接口入口；schemas.py负责请求体和响应体模型；deps.py负责数据库会话、当前用户等横切依赖。
路由声明与参数接收
FastAPI 的路由体验之所以舒服，很大程度上是因为它把参数来源和类型表达结合得很自然。
路径参数
路径参数适合表达资源标识，例如文章 ID、用户 ID。
它们会直接参与路由匹配，同时也能借助类型标注完成基本转换和校验。
查询参数与请求体
查询参数适合筛选、分页、排序这类可选输入；请求体则更适合结构化创建和更新数据。
FastAPI 的优势就在于，你不用额外写很多样板解析代码，就能把参数来源和结构表达清楚。
这让接口定义本身更像一份可执行契约，而不是一堆散落判断。
为了把这几个概念放到一段能跑的代码里，可以先看一个最小示例：
from fastapi import Depends, FastAPI, HTTPException
from pydantic import BaseModel
app = FastAPI()
class ArticleIn(BaseModel):
title: str
content: str
class ArticleOut(BaseModel):
id: int
title: str
def get_current_user() -> str:
return "colin"
@app.get("/articles/{article_id}", response_model=ArticleOut)
def get_article(article_id: int):
if article_id != 1:
raise HTTPException(status_code=404, detail="article not found")
return {"id": 1, "title": "Hello FastAPI"}
@app.post("/articles", response_model=ArticleOut, status_code=201)
def create_article(data: ArticleIn, user: str = Depends(get_current_user)):
return {"id": 2, "title": f"{data.title} by {user}"}这段代码虽然小，但已经同时演示了：
- 路径参数；
- 请求体模型；
- 响应模型；
- 依赖注入；
- 统一错误响应。
Pydantic 模型与数据校验
FastAPI 和 Pydantic 的配合，是它体验特别顺滑的一大原因。
当你定义请求体模型和响应模型后，得到的不只是字段提示，还包括：
- 结构校验；
- 错误信息组织；
- 文档自动生成；
- 数据转换与默认值处理。
这意味着类型不再只是注释，而真正参与到了接口边界管理。
所以在 FastAPI 项目里，Pydantic 模型通常不只是“方便一下”，而是接口清晰度和稳定性的核心组成部分。
比如上面的 ArticleIn 看起来只是两个字段，但一旦字段缺失、类型不对，FastAPI 就会自动返回结构化校验错误，而不用你在路由里手动写一堆 if not title 之类的判断。
依赖注入、响应模型与自动文档
FastAPI 还有几个特别实用的工程能力。
依赖注入让你可以把数据库会话、当前用户、配置对象等横切能力以更清楚的方式组织起来，而不是每个路由都手动拼装。
响应模型则让返回结构更稳定，也能帮助自动过滤不该暴露的字段。
自动文档则进一步降低了联调和理解成本。只要你的路由、参数和模型定义得清晰，文档就会自然跟上。
所以 FastAPI 的一个关键价值，是让“代码定义”和“接口契约”尽量保持同源。
当你真正跑起来后，这套体验会更明显。比如用：
uvicorn app.main:app --reload启动本地服务后，路由、参数、响应模型和校验信息会直接进入自动文档页面。对初学者来说，这种“代码写完，接口文档自然跟上”的反馈非常有助于建立框架心智。
其他工程实践
配置管理
Web 项目一旦进入真实环境，就会涉及数据库地址、密钥、调试开关、第三方服务配置等内容。
所以配置不应该散在代码里，而应集中管理，并区分环境来源。
错误处理与统一响应
接口项目最怕的不是抛错，而是同类错误表现完全不一致。
统一异常处理和统一响应结构的价值，就在于让调用方和排障方都能获得稳定心智。你要清楚哪些错误直接返回，哪些包装成业务错误，哪些只记日志不暴露细节。
总结与预告
这一节我们第一次把前面学到的类型、数据建模、异常处理和模块组织真正组合进一个 Web 框架里。FastAPI 的价值不仅在于上手快，更在于它把很多现代 Python 工程实践自然地串在了一起。
下一节我们会继续补齐后端开发的另一块核心能力，也就是数据持久化与 ORM 使用，从 SQLAlchemy 的心智模型开始展开。