神奇大蟒蛇
有一条大蟒蛇，它只能存活在虚拟环境里，virtual env 里面，神奇大蟒蛇会用python3 -m venv venv 给自己开出一个幻境出来。
使用咒语“source venv/bin/activate”进入环境。
但是幻境里面啥也没有，最好就是用“poetry”咒语来添加基础的设施。这样下次别的神奇大蟒蛇也能创建相同的幻境。
# 初始化项目
poetry init
# 装包（自动记录）
poetry add fastapi
poetry add uvicorn
# 同事clone后
poetry install # 一键安装所有依赖
🤔main.py很重要，是神奇大蟒蛇的实验室。
🤔 为啥FastAPI 这个一定要呢？
FastAPI 是一本会自己更新的魔法手帐，记录着实验室里所有魔药配方。访问 /docs 就能翻开手帐，看到所有魔药的材料和效果，甚至能直接试验！
🤔 那为啥要Uvicorn呢？
Uvicorn 是一座带显示屏的魔药炼丹炉。
当客人来访，炉子翻开手帐找配方，开始炼制。
正面的显示屏实时展示每个魔药的炼制过程和结果。
所有魔药都要在这里走一遭，才能交付给客人。 实验室改了配方，手帐自动更新，炼丹炉自动重启（--reload），一切重新开始！
📖 指导手册：从创建幻境到离开幻境
第一章：开辟幻境
python3 -m venv venv
大蟒蛇Python念动咒语（-m venv），创造出一个独立的幻境（venv文件夹）
⚠️注意：如果使用poetry咒语，大蟒蛇可以跳过开辟幻境这步，直接用 poetry shell 让poetry自动创建幻境！
# 流派A：手动创建venv + poetry管理依赖
python3 -m venv venv
source venv/bin/activate
poetry init
poetry add fastapi
# 流派B：poetry全包（推荐）
poetry init
poetry add fastapi
poetry shell # poetry自动创建并进入虚拟环境
第二章：进入幻境
source venv/bin/activate
大蟒蛇穿越进幻境，这时命令行前面会出现 (venv) 标记，说明你已经在幻境里了！
第三章：在幻境里施法（安装法术/包）
# 初始化项目
poetry init
# 装包（自动记录）
poetry add fastapi
poetry add uvicorn
在幻境里，大蟒蛇可以学习各种魔法（安装包），这些魔法只在幻境里有效，不会污染外面的世界（系统Python）
第四章：离开幻境
deactivate
大蟒蛇穿越回现实世界，(venv) 标记消失
为什么要幻境？
- 每个项目都是一个独立的幻境
- 项目A的魔法（fastapi 0.120）不会影响项目B的魔法（fastapi 0.100）
- 就像平行宇宙，互不干扰！
为什么用poetry？
1.上古时期
上古时期的神奇大蟒蛇其实不用“poetry咒语”，
他们直接用
# 生成
pip freeze > requirements.txt
# 下载
pip install -r requirements.txt
但是有的大蟒蛇会粗心，忘记生成文本清单，导致别的大蟒蛇进入混沌世界。
2.发展时期
贤者大蟒蛇发明了"pipenv"咒语，避免了混乱。
# 初始化（自动创建虚拟环境 + Pipfile）
pipenv install
# 添加依赖
pipenv install fastapi uvicorn
# 进入虚拟环境
pipenv shell
# 安装已有的Pipfile
pipenv install
exit # 退出
# 查看所有已装的包
pip list
3.现代时期
现代研究者大蟒蛇发明了“poetry”咒语，最终会生成两个文件
一个是物件清单（pyproject.toml），另外一个是魔法强制锁（poetry.lock）
这样既能够让其他大蟒蛇进入准确的幻境，甚至不会因为物件差异，导致魔药炼制失败。
# 初始化项目（会生成 pyproject.toml）
poetry init
# 添加依赖（会自动更新两个文件）
poetry add fastapi
poetry add uvicorn
# 安装所有依赖
poetry install
# 进入虚拟环境
poetry shell
exit # 退出
🎓 大蟒蛇法师 VS 灵狐法师
📦 依赖管理：前端 vs 后端对比
前端：
package.json ← 依赖列表 + 项目配置
node_modules/ ← 安装的包
npm install ← 安装命令
Python后端：
pyproject.toml ← 依赖列表（纯文本）
venv/ ← 虚拟环境（类似node_modules）
poetry install ← 安装命令
代码对比：
from fastapi import FastAPI # 导入框架（类似require）
app = FastAPI() # 创建应用实例
@app.get("/") # 装饰器 = 定义GET路由
def hello(): # 路由处理函数
return {"message": "Hello"} # 自动转JSON返回
# // 前端Node.js (Express)
# const express = require('express')
# const app = express()
# app.get('/', (req, res) => {
# res.json({ message: 'Hello World' })
# })
# app.listen(3000)
# 区别：
# @app.get("/") 是Python装饰器语法（相当于JS的 app.get('/', ...)）
# Python直接 return 字典，FastAPI自动转JSON
🤔 为什么FastAPI代码里没有 app.listen() ？
上面的代码是这么启动的：
uvicorn main:app --reload --port 8000
如果非要一模一样，代码需要这么写：
# main.py
from fastapi import FastAPI
app = FastAPI()
@app.get("/")
def hello():
return {"message": "Hello"}
# 👇 加上这段，类似 app.listen(3000)
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
然后启动要用：
python main.py # 直接运行，端口在代码里
但是，需要额外配置热重载，总之不管生产还是开发环境，都没有方案1来的方便。
总结：对于灵狐法师来说炼丹炉的启动咒语是写在配方里的，但是大蟒蛇法师的炼丹炉启动咒语在配方之外。
uvicorn main:app
= 召唤炼丹炉（Uvicorn）
炼丹炉读取实验室配方（main.py）
找到魔药台（app）
开始运行
🏗️ Python项目标准结构
backend/
├── venv/ # 虚拟环境（隔离依赖，类似node_modules，如果使用poetry就没有这个文件夹了）
├── main.py # 主程序入口（类似index.js）
├── pyproject.toml # 依赖列表（类似package.json的dependencies部分）
├── .env # 环境变量（和前端一样）
└── app/ # 应用代码（如果项目大的话）
├── __init__.py
├── routes/ # 路由（类似前端router）
├── models/ # 数据模型（类似TypeScript interface）
└── utils/ # 工具函数
🎯 Uvicorn的作用
Uvicorn ≈ Vite Dev Server
# 前端
npm run dev → Vite启动，监听5173端口，等待HTTP请求
# 后端
uvicorn main:app → Uvicorn启动，监听8000端口，等待HTTP请求
具体流程：
1. 浏览器/前端发请求
GET http://localhost:8000/api/user?id=123
↓
2. Uvicorn监听8000端口，收到请求
↓
3. Uvicorn读取 main.py，找到对应的路由函数
@app.get("/api/user")
def get_user(id: int):
↓
4. 执行你的代码，返回结果
↓
5. Uvicorn把结果转成HTTP响应，返回给浏览器
所以Uvicorn是：
- HTTP服务器（监听端口）
- 路由分发器（找到对应函数）
- 热重载工具（
--reload监听文件变化）
———一个炼丹术士的技术笔记：001 《大蟒蛇的炼丹术：Python 后端魔法入门》
