FastAPI入门教程：日志配置与结构化日志

为什么需要日志？

想象一下你在驾驶汽车时，仪表盘显示速度、油量和故障警告，帮助你了解车辆状态。日志就像是你的Web应用的“仪表盘”，它记录应用运行中的事件，让你能调试问题、监控性能，就像看日记一样回顾发生了什么。

基础概念：日志级别

在Python的logging模块中，日志有不同级别，就像是生活中的警报级别：

• DEBUG：详细信息，好比记录每个步骤，用于调试。
• INFO：正常操作记录，比如“用户登录成功”。
• WARNING：潜在问题警告，比如“磁盘空间不足”。
• ERROR：错误发生，比如“数据库连接失败”。
• CRITICAL：严重错误，可能导致应用崩溃，比如“服务器宕机”。

结构化日志则是将日志数据格式化为键值对，就像填写表格一样，使日志更易于机器解析和搜索。

快速上手：在FastAPI中配置日志

FastAPI基于Starlette，使用Python标准库的logging，设置起来非常简单。让我们一步步来，确保每个“成功时刻”都清晰可见。

步骤1：安装必要库

首先，确保你已经安装了Python。然后，在终端中运行以下命令安装FastAPI和Uvicorn（一个ASGI服务器）：

pip install fastapi uvicorn

成功时刻：看到安装完成的消息，你就迈出了第一步！

步骤2：创建你的第一个FastAPI应用

创建一个新文件，命名为 app.py，并添加以下代码。别担心，我会用注释解释每部分：

# 导入必要的模块
from fastapi import FastAPI
import logging

# 配置日志：设置日志级别为INFO，并定义输出格式
logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(message)s')

# 创建FastAPI应用实例
app = FastAPI()

# 定义一个简单的路由，当访问根路径时触发
@app.get("/")
def read_root():
    logging.info("访问根路径")  # 记录一条INFO级别的日志
    return {"message": "Hello, World!"}

# 另一个路由，带参数的路由
@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id < 0:
        logging.warning(f"物品ID为负数：{item_id}")  # 记录WARNING日志
        return {"error": "ID不能为负数"}
    logging.info(f"获取物品ID：{item_id}")  # 记录INFO日志
    return {"item_id": item_id}

步骤3：运行应用并查看日志

在终端中，导航到 app.py 所在目录，运行：

uvicorn app:app --reload

• app:app 表示从 app.py 文件导入 app 实例。
• --reload 参数让服务器在代码更改时自动重启，方便调试。

现在，打开浏览器访问 http://127.0.0.1:8000/。你应该在终端控制台看到类似这样的输出：

2023-10-01 12:00:00,123 - INFO - 访问根路径

成功时刻：太棒了！你刚刚配置了日志，并看到了第一个日志输出。这证明你的应用正在运行并记录事件。

尝试访问 http://127.0.0.1:8000/items/5，你会看到另一条日志；访问负数ID如 http://127.0.0.1:8000/items/-1，会看到WARNING日志。每次看到新日志，都是一个小胜利！

进阶：结构化日志

结构化日志让日志更像数据表格，易于分析和处理。我们来看两种方法：使用Python标准库和第三方库structlog。

方法1：使用Python标准库实现结构化日志

修改 app.py，添加结构化日志格式。我们将日志输出为JSON格式，便于机器读取。

from fastapi import FastAPI
import logging
import json

# 自定义日志格式化器，将日志转换为JSON格式
class StructuredFormatter(logging.Formatter):
    def format(self, record):
        # 创建一个字典来存储日志信息
        log_record = {
            'timestamp': self.formatTime(record),  # 时间戳
            'level': record.levelname,            # 日志级别
            'message': record.getMessage(),        # 日志消息
            'module': record.module,               # 模块名
            'function': record.funcName,           # 函数名
            'line': record.lineno                  # 行号
        }
        return json.dumps(log_record)  # 转换为JSON字符串

# 配置日志
handler = logging.StreamHandler()  # 输出到控制台
formatter = StructuredFormatter()
handler.setFormatter(formatter)

logger = logging.getLogger()
logger.setLevel(logging.INFO)
logger.addHandler(handler)

app = FastAPI()

@app.get("/")
def read_root():
    logger.info("访问根路径")  # 使用配置好的logger记录日志
    return {"message": "Hello, World!"}

运行应用并访问根路径，现在日志输出会是这样的JSON格式：

{"timestamp": "2023-10-01 12:00:00,123", "level": "INFO", "message": "访问根路径", "module": "app", "function": "read_root", "line": 25}

成功时刻：日志现在更结构化了！你可以轻松地解析这些JSON数据，用于日志分析工具。

方法2：使用第三方库structlog

structlog简化了结构化日志的配置。首先安装它：

pip install structlog

然后，在 app.py 中使用structlog：

from fastapi import FastAPI
import structlog

# 配置structlog以输出JSON格式
structlog.configure(
    processors=[
        structlog.processors.JSONRenderer()  # 渲染为JSON
    ]
)

# 获取一个logger实例
logger = structlog.get_logger()

app = FastAPI()

@app.get("/log")
def log_example():
    # 记录结构化日志，可以添加额外字段
    logger.info("这是一个结构化日志", user="Alice", action="访问页面")
    return {"status": "logged"}

运行应用并访问 http://127.0.0.1:8000/log，控制台输出会是：

{"event": "这是一个结构化日志", "user": "Alice", "action": "访问页面"}

成功时刻：通过structlog，你轻松地添加了自定义字段，使日志更加丰富和有用。

总结与鼓励

通过这个教程，你已经学会了：

1. 为什么日志重要——就像汽车的仪表盘，帮助你监控应用。
2. 如何在FastAPI中配置基本日志——使用Python标准库的logging。
3. 如何实现结构化日志——通过自定义格式化器或使用structlog库，使日志更易于处理。

每个示例都设计为“复制-粘贴-运行”，确保你能立即看到成果。日志是Web开发的基础工具，掌握它能让你在调试和监控时事半功倍。

保持信心：Web开发可能一开始看起来复杂，但通过动手实践，你会逐渐积累经验。FastAPI以其简单和快速著称，日志配置只是开始。建议下一步探索FastAPI的更多功能，如路由、请求处理和数据库集成。

如需深入学习，查看FastAPI官方文档和Python logging文档。继续编码，享受每个小成功！