2. 开发环境搭建：Python虚拟环境配置、Flask框架安装、项目目录结构设计、依赖管理

好，咱们正式开始动手了。搭建开发环境这件事，说大不大，说小不小。我见过太多新手一上来就 pip install flask，结果项目做到一半，依赖全乱套了。嗯，咱们得从一开始就打好基础。

2.1 Python虚拟环境：为什么必须用？

说白了，虚拟环境就是给你的每个项目一个独立的“小房间”。你在里面装什么库，都不会影响到系统全局或者其他项目。

我个人习惯用 venv，它是 Python 3.3+ 自带的，不需要额外安装。为什么不用 virtualenv 或 conda？其实都行，但 venv 最轻量，也最干净。

核心原则：每个法律文书项目，都应该有自己的虚拟环境。别偷懒，一个环境用到老，迟早要出事。

创建虚拟环境

# 在项目根目录下执行
python -m venv venv

这行命令会在当前目录生成一个 venv 文件夹。里面放着独立的 Python 解释器和 pip。

激活虚拟环境

Windows 和 Mac/Linux 的命令不一样，别搞混了。

# Windows (cmd/PowerShell)
venv\Scripts\activate

# Mac / Linux
source venv/bin/activate

激活后，你会看到终端前面多了个 (venv) 标记。这时候你装的所有库，都只在这个环境里生效。

小技巧：我习惯在 VS Code 里直接选择 Python 解释器为 ./venv/bin/python，这样终端和编辑器用的都是同一个环境，不会出现「明明装了包，但导入报错」的尴尬。

2.2 Flask框架安装

Flask 是个轻量级的 Web 框架，特别适合做法律文书自动生成这种内部工具。它不像 Django 那么重，你想想看，我们只需要几个 API 接口和简单的页面，Flask 刚刚好。

# 确保虚拟环境已激活
pip install flask

装完之后，你可以验证一下：

python -c "import flask; print(flask.__version__)"

如果输出版本号，比如 2.3.2，那就说明装好了。

注意：我曾经遇到过一个问题——在虚拟环境外装了 Flask，然后在虚拟环境里运行项目，结果报 ModuleNotFoundError。排查了半天，才发现是环境搞混了。所以，每次开新终端，第一件事就是激活虚拟环境。

2.3 项目目录结构设计

好的目录结构，能让你的项目活得更久。我见过一些项目，所有代码都堆在一个 app.py 里，改起来简直要命。

下面是我个人比较推荐的结构，适合法律文书自动生成系统：

legal_doc_generator/
├── app/                    # 核心应用代码
│   ├── __init__.py         # Flask 应用工厂
│   ├── routes/             # 路由（API接口）
│   │   ├── __init__.py
│   │   └── document.py     # 文书生成相关接口
│   ├── models/             # 数据模型
│   │   ├── __init__.py
│   │   └── contract.py     # 合同模板模型
│   ├── templates/          # HTML 模板
│   │   └── index.html
│   └── static/             # 静态文件（CSS/JS）
│       └── style.css
├── venv/                   # 虚拟环境（不提交到Git）
├── requirements.txt        # 依赖清单
├── config.py               # 配置文件
└── run.py                  # 启动入口

为什么要这么分？我给你拆开讲讲：

  • app/：所有业务代码都放这里，方便管理和扩展
  • routes/：专门放 API 路由，每个文件对应一类功能
  • models/：数据模型，比如合同模板、当事人信息等
  • templates/：HTML 模板，Flask 默认会从这里找
  • static/：CSS、JavaScript、图片等静态资源
  • config.py：数据库连接、密钥等配置信息
  • run.py：就几行代码，用来启动应用

避坑指南：我曾经把配置文件直接写在 app.py 里，后来要部署到不同环境（开发、测试、生产），每次都要手动改代码。后来改成 config.py 加环境变量，省心多了。

2.4 依赖管理：requirements.txt

这个文件就是你的项目「购物清单」。别人拿到你的项目，只要执行 pip install -r requirements.txt，就能装好所有依赖。

生成 requirements.txt

# 在虚拟环境激活状态下
pip freeze > requirements.txt

打开看看，内容大概长这样：

Flask==2.3.2
Jinja2==3.1.2
Werkzeug==2.3.3
...

每个库后面都跟着版本号。为什么要锁版本？因为不同版本的库可能有兼容性问题。你想想看，如果别人装的是 Flask 1.0，而你用的是 2.0，有些 API 可能就变了。

我的习惯：每次安装新库后，都重新生成一次 requirements.txt。这样能保证清单是最新的。另外，venv/ 文件夹不要提交到 Git，但 requirements.txt 一定要提交。

2.5 知识体系总览

下面这张图，帮你把本章的核心逻辑串起来：

开发环境搭建核心流程 1. Python虚拟环境 python -m venv venv 2. Flask框架安装 pip install flask 3. 目录结构设计 app/routes/models 4. 依赖管理 pip freeze > requirements.txt 四个步骤环环相扣 虚拟环境 → 安装Flask → 设计目录 → 管理依赖

2.6 快速验证：你的环境搭好了吗？

最后，咱们写个最简单的 Flask 应用，验证一下整个环境是否通畅。

在项目根目录创建 run.py：

from app import create_app

app = create_app()

if __name__ == '__main__':
    app.run(debug=True)

再创建 app/__init__.py：

from flask import Flask

def create_app():
    app = Flask(__name__)
    
    @app.route('/')
    def hello():
        return '法律文书自动生成系统 - 环境搭建成功！'
    
    return app

然后运行：

python run.py

打开浏览器，访问 http://127.0.0.1:5000。如果看到「环境搭建成功」的提示，恭喜你，基础环境已经就绪了。

常见问题：如果报错 ModuleNotFoundError: No module named 'flask'，99% 的原因是虚拟环境没激活。检查终端前面有没有 (venv) 标记。没有的话，重新激活一下。

公众号:蓝海资料掘金营，微信deep3321

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