Day 15 | FastAPI 快速入门

# 检查 Python 版本
python3 --version
# 应该输出: Python 3.9.x 或更高版本

# 确保虚拟环境已激活（提示符前有 (.venv)）
source .venv/bin/activate

#!/usr/bin/env python3
"""
Day 15 - FastAPI 快速入门
演示基础路由、路径参数和查询参数
"""

from fastapi import FastAPI

# ========== 1. 初始化 FastAPI 应用 ==========
# FastAPI 是一个类，需要实例化
# 参数说明：
# - title: API 的标题（会显示在 Swagger 文档中）
# - description: API 的描述（会显示在 Swagger 文档中）
# - version: API 的版本号
app = FastAPI(
    title="My First Ops API",
    description="这是一个用于演示 FastAPI 基础功能的文档",
    version="1.0.0"
)

# ========== 2. 定义根路由 (GET 请求) ==========
# @app.get("/") 是装饰器，表示这是一个 GET 请求的路由
# "/" 是路径，表示根路径
# 访问 http://localhost:8000/ 时触发这个函数
@app.get("/")
def read_root():
    """
    根路由：返回 API 状态信息
    
    返回:
        包含消息和状态的字典
    """
    return {
        "message": "Hello, FastAPI!",
        "status": "running"
    }

# ========== 3. 路径参数示例 ==========
# {item_id} 是路径参数，用花括号包裹
# item_id: int 是类型注解，FastAPI 会自动将 URL 中的字符串转换为整数
# 访问 http://localhost:8000/items/5 时，item_id 的值是 5
@app.get("/items/{item_id}")
def read_item(item_id: int):
    """
    获取单个项目信息
    
    参数:
        item_id: 项目 ID（路径参数）
    
    返回:
        包含项目 ID 和是否为偶数的字典
    """
    return {
        "item_id": item_id,
        "is_even": item_id % 2 == 0  # 判断是否为偶数
    }

# ========== 4. 查询参数示例 ==========
# skip 和 limit 没有在路径中，所以 FastAPI 自动识别为查询参数
# = 0 和 = 2 是默认值，如果请求中没有提供这些参数，使用默认值
# 访问 http://localhost:8000/servers?skip=1&limit=2 时：
#   - skip = 1
#   - limit = 2
# 访问 http://localhost:8000/servers 时：
#   - skip = 0（默认值）
#   - limit = 2（默认值）

# 模拟数据库数据
fake_db = [
    {"name": "Server A", "status": "running"},
    {"name": "Server B", "status": "stopped"},
    {"name": "Server C", "status": "running"},
    {"name": "Server D", "status": "running"},
]

@app.get("/servers")
def list_servers(skip: int = 0, limit: int = 2):
    """
    分页获取服务器列表
    
    参数:
        skip: 跳过多少条记录（默认 0）
        limit: 返回多少条记录（默认 2）
    
    返回:
        服务器列表（字典列表）
    """
    # 使用 Python 切片实现分页
    # fake_db[skip:skip+limit] 表示从 skip 开始，取 limit 条
    return fake_db[skip : skip + limit]