一个自包含的 FastAPI 交互式学习项目——启动服务后，打开浏览器，教程本身就是"我教你怎么读我"。
| 模块 | 状态 | 说明 |
|---|---|---|
| 交互式网页教程 | 已完成 | 10 章教程页面，含概念讲解 + 交互式 API 演示 |
| REST API (CRUD) | 已完成 | Items 的增删改查，分页查询 |
| JWT 认证 | 已完成 | 注册、登录、OAuth2 Password Flow |
| 数据库 | 已完成 | SQLAlchemy 2.0 异步 ORM + SQLite |
| 中间件 | 已完成 | CORS、请求计时（X-Process-Time） |
| 全局异常处理 | 已完成 | 自定义异常层级 + 统一错误响应 |
| 文件上传 | 已完成 | UploadFile + UUID 重命名 |
| WebSocket | 已完成 | Echo 回声服务 |
| 测试 | 已完成 | 41 个测试用例，覆盖率 78% |
| Docker | 已完成 | 多阶段构建 Dockerfile |
- pixi 包管理器
- Python 3.12（由 pixi 自动管理）
# 1. 安装依赖
pixi install
# 2. 启动开发服务器
pixi run dev
# 3. 打开浏览器
# http://localhost:8000 → 教程首页
# http://localhost:8000/docs → Swagger UI
# http://localhost:8000/redoc → ReDoc无需额外配置，默认使用 SQLite，开箱即用。
复制 .env.example 为 .env，按需修改：
| 变量 | 默认值 | 说明 |
|---|---|---|
APP_NAME |
learn-fastapi |
应用名称 |
APP_ENV |
development |
运行环境 |
APP_DEBUG |
true |
调试模式 |
LOG_LEVEL |
INFO |
日志级别 |
LOG_JSON |
false |
JSON 格式日志 |
DATABASE_URL |
sqlite+aiosqlite:///./learn_fastapi.db |
数据库连接 |
SECRET_KEY |
dev-secret-key-change-in-production |
JWT 签名密钥 |
| 章节 | 主题 | 交互演示 |
|---|---|---|
| Ch1 | Python 前置知识（类型注解、装饰器、async/await、Pydantic） | - |
| Ch2 | 第一个 FastAPI 应用（路由、参数、请求体、响应模型） | 4 个 |
| Ch3 | Pydantic 深入（字段校验、验证器、422 错误） | 4 个 |
| Ch4 | 依赖注入（Depends、分页、数据库会话） | 3 个 |
| Ch5 | 数据库集成（SQLAlchemy ORM、CRUD） | 4 个 |
| Ch6 | 认证与授权（JWT、OAuth2、密码哈希） | 4 个 |
| Ch7 | 中间件与错误处理（CORS、异常处理器） | 4 个 |
| Ch8 | 测试（TestClient、依赖覆盖） | - |
| Ch9 | 进阶主题（文件上传、WebSocket） | 2 个 |
| Ch10 | 面试冲刺（15 道高频问答） | - |
每章包含：概念讲解 → 交互式演示 → 源码指引 → DevTools 技巧 → 面试要点
| 方法 | 路径 | 功能 | 认证 |
|---|---|---|---|
| GET | /health |
健康检查 | - |
| GET | /items/ |
分页列表 | - |
| GET | /items/{id} |
单条查询 | - |
| POST | /items/ |
创建 | - |
| PUT | /items/{id} |
更新 | - |
| DELETE | /items/{id} |
删除 | - |
| POST | /auth/register |
用户注册 | - |
| POST | /auth/token |
登录获取 JWT | - |
| GET | /auth/me |
当前用户 | JWT |
| POST | /upload/ |
文件上传 | - |
| WS | /ws/echo |
WebSocket 回声 | - |
src/learn_fastapi/
├── app.py # 应用工厂 + 生命周期
├── config.py # pydantic-settings 配置
├── dependencies.py # 共享依赖（分页参数）
├── middleware.py # 自定义中间件（请求计时）
├── exceptions.py # 自定义异常 + 全局处理器
├── auth/ # 认证模块
│ ├── jwt.py # JWT 编解码
│ ├── password.py # bcrypt 密码哈希
│ └── dependencies.py # OAuth2 + get_current_user
├── core/ # 核心工具
│ └── logging.py # structlog 结构化日志
├── crud/ # 数据库操作
│ ├── items.py
│ └── users.py
├── db/ # 数据库层
│ ├── base.py # SQLAlchemy 声明式基类
│ ├── engine.py # 异步引擎 + 会话管理
│ ├── models.py # Item ORM 模型
│ └── user_model.py # User ORM 模型
├── models/ # Pydantic Schema
│ ├── item.py # ItemCreate/Update/Response
│ └── user.py # UserCreate/Response/Token
├── routers/ # API 路由
│ ├── items.py # /items CRUD
│ ├── auth.py # /auth 注册/登录
│ ├── upload.py # /upload 文件上传
│ └── ws.py # /ws WebSocket
├── tutorial/ # 教程路由
│ └── router.py # /tutorial 章节页面
├── templates/ # Jinja2 HTML 模板
│ ├── base.html # 基础布局
│ ├── index.html # 教程首页
│ └── chapters/ # 10 个章节页面
└── static/ # 静态资源
├── tutorial.css # 教程样式
└── tutorial.js # 交互演示逻辑
pixi run dev # 启动开发服务器（热重载）
pixi run test # 运行测试 + 覆盖率报告
pixi run lint # Ruff 代码检查
pixi run format # Ruff 代码格式化
pixi run typecheck # MyPy 严格模式类型检查
pixi run security # pip-audit 安全漏洞扫描- Web 框架: FastAPI
- ASGI 服务器: Uvicorn
- ORM: SQLAlchemy 2.0（异步）
- 数据库: SQLite（通过 aiosqlite）
- 认证: JWT（python-jose） + bcrypt
- 配置: pydantic-settings
- 日志: structlog
- 模板: Jinja2
- 测试: pytest + httpx + pytest-asyncio
- 代码质量: Ruff + MyPy（strict）
- 包管理: pixi
MIT