# Python FastAPI 學習筆記

[常見標準的 FastAPI 專案架構](https://ithelp.ithome.com.tw/m/articles/10316905)

FastAPI 作為一個非常方便的後端框架，除了 API 保持 REST API 的風格，方便前後端方離之外，也具備非同步機制 `async/await` 做到多使用者同時使用亦可處理的狀況。

### 必備元素

- 啟動 app，通常是 `app = FastAPI()`
- 設立環境變數：存在 `.env` 並且用 `load_dotenv()` 載入，再配合 `os.getenv("key")` 來取得
- 路由：`@app.<http method>("/path")` 代表我們使用該 http method 打這支 API 的路徑時，底下相對應的 function 以及其行為。
- 參數 `response_model=...`，FastAPI 會自動把你回傳的 `pydantic` 模型物件轉成 `JSON`（用 `.model_dump()`），並自動驗證與過濾不在 `schemas.py` 中的欄位。
- `uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload`

### 常用元素

- `sqlalchemy`：資料庫操作套件，資料庫通常分開成 `models.py` 和 `database.py` 來放。前者用來定義資料表，後者則是定義資料庫的 CRUD 等操作。
- `pydantic`：資料驗證用的套件，現在常用裡面的 `BaseModel` 繼承其資料型態。
- `httpx`：具備異步操作的 `request`，模擬 http 客戶端，讓我們的 API 被打到之後還可以繼續去和其他 API 溝通。
- `HTTPException`：在 `fastapi` 裡面，用來報錯誤訊息以及回傳 http 代碼。

## 套件管理：`uv`

[參考資料](https://dev.to/codemee/shi-yong-uv-guan-li-python-huan-jing-53hg)

`uv` 是一套包含所有環境管理功能的套件，一般來說 `conda` 可能管理環境，`poetry` 管理純 python 專案，但 `uv` 一次包辦以上！

### 安裝（建議別透過`pip`）

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
$env:Path = "C:\Users\User\.local\bin;$env:Path"

### 使用 uv 替代 python/pip 工具

- `uv run <file_path>`：原本跑程式會用 `python <file_path>`，現在可改用此命令，`uv` 會自己依照以下順序尋找可執行的 Python 環境，而不需手動啟動
- 目前資料夾下的 .python-version 檔內設定的版本。
- 目前啟用的虛擬環境。
- 目前資料夾下的 .venv 資料夾內設定的虛擬環境。
- uv 自己安裝的 Python。
- 系統環境變數設定的 Python 環境。

### 管理虛擬環境與套件

- `uv venv`：建立虛擬環境，`uv` 預設都是使用 `venv` 這個名稱，並且將虛擬環境建立在當前資料夾的 `.venv` 資料夾下。
- 可以在後面接上 `--python 3.10` 來指定虛擬環境的 Python 版本
- 建立完成後 `uv` 都會自動以當前資料夾的虛擬環境執行
- 要刪除虛擬環境就直接刪 `.venv` 資料夾就好
- `uv pip install <package>`：`uv pip` 提供與 `pip` 相容的介面管理套件
- 比原生的 `pip` 快上許多
- 但刪除套件時 `uv pip uninstall` 不會自行刪除依賴項
- `uv tool install <package>`：全域安裝，獨立於專案之外
- 通常是安裝全域 CLI：`black`、`ruff`、`httpie`、`pre-commit`、`poetry`
- 安裝的工具在任何資料夾都可使用
- 可以用 `uv tool upgrade` 或 `uv tool uninstall` 來升級或移除
- 在 VScode 裡面要選定 Python 的編譯器，這時候點選右下角，改用瀏覽的方式選取 `./.venv/Scripts/python.exe`，也就是當前虛擬環境裡的 Python 執行檔，就可以讓語法上色了。

### 管理專案

- `uv init`：初始化一個 uv 專案，包含 `.gitignore`, `.python-version`, `pyproject.toml` 等
- `uv add <package>`：專案內用這個命令來安裝套件
- 會紀錄依賴關係，並修改於 `pyproject.toml`
- 會更新或建立 `uv.lock` 來鎖定版本以重現（不需手動修改）
- 會安裝到專案的虛擬環境 `.venv`
- `uv pip install .`：從寫好的 `pyproject.toml` 安裝全部
- `uv tree`：可以看到套件的相依關係
- `uv remove <package>`：和 `uv add` 是反向操作
- 一樣會更新 `pyproject.toml`, `uv.lock`, `.venv`
- 會將指定套件、不再需要的相關依賴套件也一併刪除
- `uv lock --upgrade`：更新所有套件
- `uv lock --upgrade-package <package>` ：更新指定套件
- `uv run <套件提供的命令> ...`：指定 uv 環境跑檔案

### 手動修改專案、同步專案、跑別人的專案

#### uv 原生流程

1. （可選）先更改 `pyproject.toml` 的內容（刪除或新增套件）
3. `uv lock`：修改 `uv.lock` 檔案內容
4. `uv sync`：真正將修改後的 `uv.lock` 同步到虛擬環境

:::success
即使已經 `uv sync`，還是可以繼續用 `uv add <package>`，會自動執行上述三項動作。
:::

#### uv 提供的 pip 流程

1. `uv pip compile -o requirements.txt`：先編譯出鎖定檔（就是 `requirements.txt`）並將所有套件的版本寫入至鎖定檔
2. `uv pip sync`：用來找 `requirements.txt` 並安裝
### 啟動 / 關閉虛擬環境

- `.venv\Scripts\activate`：用這行指令啟動環境，才能用環境裡的套件
- `deactivate`：用這行指令關閉虛擬環境