Skip to main content
实战日：Day 20 是 Python Web 阶段的”毕业大考”。我们将把 Week 3 所有的知识点串联起来，构建一个名为 InsightOps-API 的微服务。今天不只是写代码，而是要彻底理解 “如何设计一个完整的 API 项目”、“如何组织项目结构” 以及 “如何让代码具备生产级质量”。

​
实战目标 | Project Goal

开发一个用于查询服务器监控数据的 RESTful API。

1. 核心功能

  • POST /servers: 注册新服务器（自动校验 IP 格式）
  • GET /servers: 分页查询服务器列表
  • GET /servers/: 查询特定服务器详情
  • PUT /servers/: 更新服务器信息
  • DELETE /servers/: 删除服务器

2. 技术栈

  • Web 框架: FastAPI
  • 数据验证: Pydantic
  • 数据库: SQLAlchemy (Async) + MySQL
  • 部署: Docker + Docker Compose
  • 配置管理: pydantic-settings

​
代码任务 (120 mins)

1

环境准备

确保所有依赖已安装：
# 确保虚拟环境已激活
source .venv/bin/activate

# 安装所有依赖
pip install fastapi uvicorn gunicorn \
    pydantic-settings python-dotenv \
    sqlalchemy aiomysql

# 确保 MySQL 服务正在运行
# docker run -d -p 3306:3306 --name mysql-learn -e MYSQL_ROOT_PASSWORD=root mysql:8.0
2

项目结构规划

一个标准的 Python 后端项目结构：
insightops_api/
├── app/
│   ├── __init__.py
│   ├── main.py          # 入口文件
│   ├── models.py        # 数据库模型 (ORM)
│   ├── schemas.py       # Pydantic 模型 (Validation)
│   ├── database.py      # 数据库连接
│   └── config.py        # 配置读取
├── requirements.txt
├── Dockerfile
├── docker-compose.yaml
└── .env                 # 环境变量（不提交到 Git）
为什么这样组织？
  • 模块化：每个文件负责一个功能，便于维护
  • 可扩展：易于添加新功能（如认证、缓存）
  • 标准化：符合 Python 项目的最佳实践
3

编写核心代码

按照项目结构，逐步实现各个模块。
#!/usr/bin/env python3
"""配置管理"""

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = "InsightOps API"
    debug: bool = False
    database_url: str
    
    class Config:
        env_file = ".env"
        case_sensitive = False

settings = Settings()
项目结构说明：
  • app/：应用主目录
  • models.py：数据库模型（ORM）
  • schemas.py：Pydantic 模型（验证）
  • database.py：数据库连接配置
  • config.py：配置管理
  • main.py：FastAPI 应用入口
运行项目：
# 使用 Docker Compose 启动
docker-compose up --build

# 或者本地运行
uvicorn app.main:app --reload
验证步骤：
  1. 访问 http://localhost:8000/docs 打开 Swagger UI
  2. 测试创建服务器：
    • 点击 POST /servers/
    • 输入数据，执行，应该返回 201
  3. 测试查询服务器列表：
    • 点击 GET /servers/
    • 执行，应该看到服务器列表
  4. 测试查询单个服务器：
    • 点击 GET /servers/{server_id}
    • 输入服务器 ID，执行，应该看到服务器详情

​
拓展任务 (30 mins)

挑战 1：添加认证

任务：为 API 添加 Token 认证，只有认证用户才能创建服务器。提示：使用 Day 17 学到的依赖注入实现。

挑战 2：添加日志

任务：添加请求日志中间件，记录每个请求的详细信息。提示：使用 Day 17 学到的中间件实现。

​
今日产出物

  • 完整的 InsightOps-API 项目
  • Docker 镜像和 Docker Compose 配置
  • 生产级 API 服务

​
参考代码

查看参考代码

在 GitHub 查看完整的 InsightOps API 项目

项目结构

查看标准项目目录结构

​
实际应用场景

FastAPI 在生产环境中的应用

  • 微服务架构：构建轻量级微服务
  • API 网关：作为 API 网关，统一管理接口
  • 数据查询服务：提供数据查询和操作接口
  • 自动化工具：为运维工具提供 RESTful API
  • 监控系统：提供监控数据的查询接口

项目设计最佳实践

  • 模块化设计：按功能拆分模块，便于维护
  • 配置外置：使用环境变量管理配置
  • 容器化部署：使用 Docker 实现可移植性
  • 文档完善：利用 FastAPI 自动生成文档
  • 错误处理：统一的错误处理和响应格式
与 Day 21 的关联：今天完成的综合项目，明天会进行复盘和总结，回顾第三周学到的所有知识点。

上一天: 生产部署

Day 19 | 生产部署与配置

下一天: 第三阶段复盘

Day 21 | 第三阶段复盘