從環境搭建到項目運行：Python 和 Flask 快速上手指南
個簡單的 Web 項目。
環境
- 操作系統：Mac 13.0
- Python：3.11.7
- 包管理：poetry1.8.3
- Web 框架：Flask3.1
Python 中的包管理工具有 conda、pip、poetry、PyPI 等，Web 框架也有 Django、Flask、FastAPI ，為什么選擇的是 poetry 和 Flask 呢？
因為現在研究的 RAGFlow 的源碼中使用的就是 poetry 和 Flask 。帶著目的去學習效率會高很多。
安裝
1.安裝 Python
直接在官網下載安裝就可以：https://www.python.org/downloads/，我很早前就安裝了，一直沒有升級，所以版本還是 3.11.7 。
2.安裝 poetry
如果你了解過 Python，一定知道 pip，但 pip 在包的依賴管理和版本沖突管理上做的不是很好，而 poetry 就是為了解決這兩個問題而生。
我在本機是使用 pipx 來安裝的 poetry ，先使用 homebrew 安裝 pipx：
brew install pipx
pipx ensurepath
接著使用 pipx 安裝 poetry，命令如下：
pipx 安裝 poetry
安裝完成后，可以通過以下命令驗證 poetry 是否安裝成功：
poetry --version出現下圖所示，說明安裝成功：
3.使用 poetry
可以使用 poetry 創建一個新的項目:
poetry new poetry-project也可以在現有項目的目錄中初始化 poetry：
cd exist-project
poetry init使用 poetry 創建的項目目錄如下：
在 pyproject.toml 文件中進行包版本的管理。這時如果我要給項目添加相關的依賴包，有兩種方式：
直接使用 poetry 命令:
poetry add six:1.16.0使用命令安裝完成后，pyproject.toml 文件中會自動添加 six = "1.16.0" ，如下圖：
另一種方式就是先修改配置，在 pyproject.toml 中添加 six = "1.16.0" 或其他的包，然后執行下面命令進行安裝：
poetry install在使用 poetry 之前，先使用下面命令設置虛擬環境在項目內：
poetry config virtualenvs.in-project true經過上面的設置后，不管是使用 poetry install 還是使用 poetry add 添加的包，會在項目根目錄下的 .venv 目錄中，便于管理：
4.安裝 flask
poetry add flask上面命令會將 Flask 添加到 pyproject.toml 并安裝到虛擬環境中。
使用 flask
使用 poetry 初始化一個項目并添加 flask 后，項目的目錄結構如下：
可以看到到多了 __init__.py 和 poetry.lock 兩個文件：
- __init__.py：可以將這個文件所在目錄標記為一個 Python 包，使得這個目錄可以被當作模塊導入。
- poetry.lock：鎖定項目所有依賴包的具體版本，確保項目在不同環境中使用完全相同的依賴版本，記錄了每個包的詳細信息，包括其哈希值、依賴關系等。
在上面的基礎上，我們讓 windsurf 來完成一個示例程序，在 windsurf 中輸入：按照flask的最佳實踐，創建 get 和 post 的接口示例，創建的目錄結構如下：
從上往下來看看每個文件的內容：
__init__.py
"""Flask 應用工廠模塊"""
from flask import Flask
from .config import config
def create_app(config_name='default'):
"""
創建 Flask 應用實例
:param config_name: 配置名稱，可選值：development, production, default
:return: Flask 應用實例
"""
# 創建應用實例
app = Flask(__name__)
# 加載配置
app.config.from_object(config[config_name])
# 注冊藍圖
from .api import api_bp
app.register_blueprint(api_bp)
# 添加一個測試路由
@app.route('/')
def index():
return 'Welcome to Flask API'
return appconfig.py
"""Flask 應用配置文件"""
class Config:
"""基礎配置類"""
SECRET_KEY = 'dev-key' # 開發環境密鑰
JSON_AS_ASCII = False # 支持中文返回
class DevelopmentConfig(Config):
"""開發環境配置"""
DEBUG = True
ENV = 'development'
class ProductionConfig(Config):
"""生產環境配置"""
DEBUG = False
ENV = 'production'
SECRET_KEY = 'your-production-secret-key' # 生產環境應使用強密鑰
# 配置映射
config = {
'development': DevelopmentConfig,
'production': ProductionConfig,
'default': DevelopmentConfig
}api__init__.py
from flask import Blueprint
# 創建 API 藍圖
api_bp = Blueprint('api', __name__, url_prefix='/api')
# 導入視圖函數
from . import views # 這行很重要，確保視圖函數被注冊到藍圖api_views.py
"""API 視圖函數"""
from flask import jsonify, request
from . import api_bp
@api_bp.route('/hello', methods=['GET'])
def hello():
"""GET 請求示例"""
return jsonify({
'code': 200,
'message': 'Hello, World!',
'data': None
})
@api_bp.route('/echo', methods=['POST'])
def echo():
"""POST 請求示例"""
try:
# 獲取 JSON 數據
data = request.get_json()
if not data:
return jsonify({
'code': 400,
'message': 'No JSON data provided',
'data': None
}), 400
# 返回接收到的數據
return jsonify({
'code': 200,
'message': 'Data received successfully',
'data': data
})
except Exception as e:
return jsonify({
'code': 500,
'message': str(e),
'data': None
}), 500run.py
"""應用啟動入口"""
from poetry_project import create_app
app = create_app('development')
if __name__ == '__main__':
app.run(host='0.0.0.0', port=5005)在項目更目錄下執行下面命令運行和測試：
poetry run python run.py
curl http://localhost:5005/api/hello
curl -X POST -H "Content-Type: application/json" -d '{"message":"test"}' http://localhost:5005/api/echo擴展
到這里，一個簡單的例子就跑起來了。
但例子中有些地方看不明白，直接在 windsurf 中去問就可以了，比如 api 目錄中的 __init__.py 文件中有這樣一行代碼：
api_bp = Blueprint('api', __name__, url_prefix='/api')
了解了一個簡單的 Flask 項目結構，也知道怎么去抽絲剝繭搞清楚不懂的問題。我們就可以去閱讀 RAGFlow 的源碼了。
常用命令
1.升級 Poetry
如果需要升級 Poetry，可以使用以下命令：
pipx upgrade poetry2.卸載 Poetry
如果不再需要 Poetry，可以通過以下命令卸載：
pipx uninstall poetry3.創建虛擬環境
Poetry 默認會在你安裝依賴時自動創建虛擬環境。如果你想手動創建虛擬環境，可以運行以下命令：
poetry env use python這會使用系統默認的 Python 版本創建虛擬環境。如果你想指定 Python 版本，可以這樣做：
poetry env use python3.94.查看虛擬環境信息
創建虛擬環境后，可以通過以下命令查看虛擬環境的路徑和信息：
poetry env info5.激活虛擬環境
如果你想手動激活虛擬環境，可以運行以下命令：
poetry shell這會啟動一個新的 shell 并激活虛擬環境。激活后，你可以直接運行 Python 腳本或命令。
6.刪除虛擬環境
如果你想刪除虛擬環境，可以運行以下命令：
poetry env remove python
