环境准备与基础框架搭建

说实话，很多自动化项目死在第一步——环境没搭好。我见过太多团队，代码写得挺漂亮，结果换台机器就跑不起来。诊断流程自动化更是如此，依赖关系复杂，版本冲突频繁。今天咱们就把这块地基打扎实。

Python虚拟环境：隔离是美德

你想想看，一个项目用Django 3.2，另一个用4.0，装在一起会怎样？我曾经在一个服务器上同时维护五个项目，pip list一拉出来两百多个包，根本分不清哪个是哪个的。后来我学乖了——每个项目独立虚拟环境。

Python自带的venv模块就够用：

# 创建虚拟环境
python -m venv .venv

# 激活（Windows）
.venv\Scripts\activate

# 激活（Linux/Mac）
source .venv/bin/activate

# 退出
deactivate

我个人习惯把虚拟环境放在项目根目录下，命名为.venv。这样一眼就能看到，而且.gitignore里顺手就把它排除掉了。

小技巧： 在VS Code里，打开项目后按Ctrl+Shift+P，搜索"Python: Select Interpreter"，直接选.venv里的那个。这样终端和编辑器用的就是同一个环境。

依赖管理：Poetry vs pip

说到依赖管理，我得坦白——早期我用pip freeze > requirements.txt，结果被坑惨了。有一次升级了某个库，requirements.txt里锁死了旧版本，但新版本有安全漏洞，我手动改了半天才搞定。后来换成了Poetry，世界清净了。

Poetry的好处很明显：

  • 自动解析依赖树——不会出现A依赖B 1.0、C依赖B 2.0这种尴尬
  • 锁定文件——poetry.lock保证所有人装的一样
  • 分组管理——开发依赖和运行依赖分开

安装Poetry：

# 官方推荐方式
curl -sSL https://install.python-poetry.org | python3 -

# 验证安装
poetry --version

初始化项目：

poetry new diagnosis-toolkit
cd diagnosis-toolkit
poetry add requests pydantic
poetry add --dev pytest black mypy

嗯，这里要注意——poetry add会自动创建虚拟环境，你都不用手动venv了。它会把依赖写进pyproject.toml，同时生成poetry.lock。

核心对比：
特性 pip + requirements.txt Poetry
依赖解析 手动解决冲突 自动解析
锁定版本 需要手动维护 自动生成lock文件
环境隔离 需额外venv 内置
发布包 需额外工具 poetry build/publish

如果你团队里有人不习惯Poetry，也可以用pip+虚拟环境。但我建议——新项目直接上Poetry，省心。

日志系统搭建：别等出事了再后悔

诊断流程自动化，说白了就是靠日志活着的。流程跑没跑对、哪一步卡住了、数据传没传过去——全看日志。我曾经接手过一个项目，日志全用print()，生产环境一出问题，运维小哥翻半天终端输出，眼睛都快瞎了。

Python标准库的logging模块其实够用，但得配置好：

import logging
import sys
from pathlib import Path

def setup_logger(name: str = "diagnosis", log_dir: str = "logs"):
    """配置日志系统"""
    # 创建日志目录
    log_path = Path(log_dir)
    log_path.mkdir(exist_ok=True)
    
    # 创建logger
    logger = logging.getLogger(name)
    logger.setLevel(logging.DEBUG)
    
    # 格式：时间 - 级别 - 模块 - 消息
    formatter = logging.Formatter(
        "%(asctime)s - %(levelname)s - %(name)s - %(message)s",
        datefmt="%Y-%m-%d %H:%M:%S"
    )
    
    # 文件处理器（记录所有级别）
    file_handler = logging.FileHandler(
        log_path / f"{name}.log",
        encoding="utf-8"
    )
    file_handler.setLevel(logging.DEBUG)
    file_handler.setFormatter(formatter)
    
    # 控制台处理器（只记录INFO及以上）
    console_handler = logging.StreamHandler(sys.stdout)
    console_handler.setLevel(logging.INFO)
    console_handler.setFormatter(formatter)
    
    # 添加处理器
    logger.addHandler(file_handler)
    logger.addHandler(console_handler)
    
    return logger

# 使用示例
logger = setup_logger()
logger.info("诊断流程启动")
logger.debug("加载配置文件: config.yaml")
logger.error("连接数据库失败: 超时")
避坑指南： 我曾经在生产环境上忘记设置日志轮转，结果一个月后日志文件撑爆了磁盘。建议加上RotatingFileHandler，按大小或时间自动切割。

更完善的配置可以加上日志轮转：

from logging.handlers import RotatingFileHandler

# 替换上面的file_handler
file_handler = RotatingFileHandler(
    log_path / f"{name}.log",
    maxBytes=10*1024*1024,  # 10MB
    backupCount=5,           # 保留5个备份
    encoding="utf-8"
)

我个人习惯把日志级别分三层：

  • DEBUG：开发时用，记录变量值、函数调用细节
  • INFO：正常流程信息，比如"开始执行步骤3"
  • ERROR：出错了，必须人工介入

你想想看，如果每个步骤都打INFO日志，出问题时你能精确知道卡在哪一步。如果只打ERROR，你只知道"出错了"，还得去翻代码猜原因。说白了，日志就是你的第二双眼睛。

整合到一起：项目骨架

最后，我给出一个诊断流程自动化项目的标准目录结构：

diagnosis-toolkit/
├── .venv/                  # 虚拟环境
├── logs/                   # 日志目录
├── src/
│   ├── __init__.py
│   ├── logger.py           # 日志配置
│   ├── config.py           # 配置管理
│   └── core/               # 核心逻辑
├── tests/                  # 测试
├── pyproject.toml          # Poetry配置
├── poetry.lock             # 锁定文件
└── README.md

初始化命令：

poetry new diagnosis-toolkit
cd diagnosis-toolkit
poetry add pydantic pyyaml
poetry add --dev pytest pytest-cov black mypy
mkdir -p logs

好了，环境搭好了，日志系统也配好了。下一步咱们就可以开始写真正的诊断流程了。记住——基础框架决定了项目能走多远。别嫌麻烦，这一步值得花时间。

← 上一章 📖 返回目录 下一章 →