在利用 agy 完成市圖網站爬蟲改版後, 接下來想要繼續用它來重構 serverless 函式執行平台, 主要目的是要加上 API Key 機制, 其次是美化前端介面.
本系列全部文章索引參考 :
我去年在鄉下家的 Mapleboard 伺服器上佈署了仿 GCF 基本功能的 serverless 函式執行平台 (後端使用 Flask), 後續透過 ChatGPT 精進功能後, 佈署到 render.com 雲端網站上, 目前主要是用來館裡市圖借書預約爬蟲的擷取結果, 參考 :
我將 serverless 寄存在 GitHub 以利 render.com 佈署之用 :
1. 前置處理 :
我先與 Gemini 討論 GitHub 倉庫是要繼續使用原倉庫 serverless, 還是新建一個 serverless2, 因為基於懷舊, 我想保留原來樸實無華的陽春版本面貌. Gemini 建議繼續在原有的 serverless 倉庫進行改版, 但透過 Git 的分支 (Branch) 或標籤 (Tag) 來管理, 而不需要大費周章開新倉 serverless2. 理由是基於專案連續性與降低維護成本, 開新倉會讓歷史提交紀錄斷代, 未來若發現第一版有個底層 Bug 要修, 得在兩個 repo 各改一次.
但要如何在原倉完美保留第一版的樸實模樣呢? Gemini 建議兩個方案 :
- 使用 Git Tag 凍結版本 :
這是在原倉的狀態上打上一個標籤 (例如 v1.0.0-basic), 然後直接在 main 分支上大刀闊斧地進行重構. 未來如果想重溫第一版, 任何人只需要執行 git checkout v1.0.0-basic 指令, 程式碼就會瞬間回到最純粹的樣子. - 開闢長青分支 (Long-lived Branch) :
這是用 git checkout 指令為原倉建立一個分支 (例如 v1-basic) 永遠停留在這裡不再異動, 的 main 分支則用來開發具有 API Key 認證機制的新版. 好處是在 GitHub 的網頁畫面上隨時點選下拉選單就能看到第一版專屬分支的程式碼.
Gemini 強烈建議採用 Git Tag 做法.
(1). 下載專案 :
首先到 Antigravity CLI 專案根目錄下 (此處為 D:\antigravity_cli\projects) 用 git clone 指令將 repo 複製到本機 :
git clone https://github.com/tony1966/serverless.git
PS D:\antigravity_cli\projects> git clone https://github.com/tony1966/serverless.git
Cloning into 'serverless'...
remote: Enumerating objects: 136, done.
remote: Counting objects: 100% (136/136), done.
remote: Compressing objects: 100% (131/131), done.
remote: Total 136 (delta 73), reused 0 (delta 0), pack-reused 0 (from 0)
Receiving objects: 100% (136/136), 52.96 KiB | 903.00 KiB/s, done.
Resolving deltas: 100% (73/73), done.
下載完成後會放在專案資料夾 serverless 下, 可用 tree 指令檢視專案結構 :
PS D:\antigravity_cli\projects> tree serverless /f
列出磁碟區 新增磁碟區 的資料夾 PATH
磁碟區序號為 000001FC 1258:16B8
D:\ANTIGRAVITY_CLI\PROJECTS\SERVERLESS
│ Procfile
│ requirements.txt
│ serverless.py
│
└─functions
add.py
add_function.py
add_table.py
clear_stats.py
delete_function.py
delete_record.py
drop_table.py
edit_function.py
execute_sql.py
export_table.py
hello.py
linebot_gemini.py
linebot_gpt.py
list_functions.py
list_tables.py
save_function.py
send_books_messages.py
send_ksml_books_messages.py
show_schema.py
show_stats.py
update_function.py
update_ksml_books.py
view_table.py
__init__.py
其中黃底色部分為自訂的應用函式, 不是系統本身的一部份.
用 git clone 從 GitHub 下載的專案, 其資料夾會自動納入版控, 不需要再下 git init 指令, 因為下載過程會把專案在 GitHub 上的所有 Commit 歷史, 分支, 以及最重要的 Git 核心控制檔 (就是隱藏的 .git 資料夾) 都下載下來, 已經具備完整的 Git 版控功能.
git clone 下載的專案預設會停在 main (或 master) 分支上, 可用 git status 檢視 :
PS D:\antigravity_cli\projects> cd serverless
PS D:\antigravity_cli\projects\serverless> git status
On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean
(2). 將原專案打上標籤 :
接下來用 git tag 指令將下載至本機中的專案打上標籤凍結歷史 :
git tag -a v1.0.0-basic -m "第一版：樸實無華的基礎 Serverless 平台"
PS D:\antigravity_cli\projects\serverless> git tag -a v1.0.0-basic -m "第一版：樸實無華的基礎 Serverless 平台"
然後將此 Tag 推送到 GitHub 上 :
git push origin v1.0.0-basic
PS D:\antigravity_cli\projects\serverless> git push origin v1.0.0-basic
Enumerating objects: 1, done.
Counting objects: 100% (1/1), done.
Writing objects: 100% (1/1), 230 bytes | 230.00 KiB/s, done.
Total 1 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
To https://github.com/tony1966/serverless.git
* [new tag] v1.0.0-basic -> v1.0.0-basic
如此一來, 無論以後程式碼怎麼改, 只要在任何地方輸入 git checkout v1.0.0-basic, 就能切回去, 隨時重溫第一版的程式碼了.
注意, git tag 本質上只是在 Git 的歷史紀錄中幫某個特定的 Commit (提交節點) 貼上一張唯讀的標籤紙而已, 這完全沒有更動到任何一行 程式碼, 專案架構或設定檔, 對於依賴原倉來重新佈署 serverless 的 render.com 來說, 整個專案的內容與打 Tag 前是一模一樣的, 不影響縣有兩個 render.com 上專案的佈署, 因為 render.com 的部署機制是認分支而不是認標籤. 上面所坐的動作只是把 main 分支目前的狀態打上標籤並推上去而已.
(3). 建立新分支 :
用下列指令從目前的主分枝 main 建立一個新分枝 :
git checkout -b feature/api-token-auth
checkout 是 Git 中用來切換或提取的指令, 作用是移動工作指針 (HEAD), 讓工作目錄切換到不同的分支或歷史節點, 此處用來切換到新分支. -b 是 branch (分支) 的縮寫, 代表建立新分支, 也就是用目前的進度為基底, 原地創造一個全新的分支, 並且在創造完後自動切換到新分支 (如果沒有加 -b 參數, Git 會去尋找一個已經存在的分支並切換過去).
最後面的參數 feature/api-token-auth 是以軟體工程中標準的斜線命名法來指定分支名稱, 其中 feature/ 表示新功能的前綴, 常見的前綴還有修正 Bug 的 bugfix/ 與重構的 refactor/. 斜線後面的 api-token-auth 是自訂的分支名稱 (可用字元為字母, 底線或連字號), 只要能清楚說明這個分支的目的即可.
PS D:\antigravity_cli\projects\serverless> git checkout -b feature/api-token-auth
Switched to a new branch 'feature/api-token-auth'
檢視目前狀態在哪個分支 :
PS D:\antigravity_cli\projects\serverless> git status
On branch feature/api-token-auth
nothing to commit, working tree clean
(4). 在新分支建立隔離資料夾 :
從上面 tree /f 結果可知, 原倉庫的 functions 資料夾下含有非系統的應用函式 (黃底色檔案), 這些 apps 可能會在 agy 閱讀程式碼時分散它的注意力, 干擾它對專案脈絡的理解. 但也不要直接將它們刪除, 因為當 API Key 認證機制完成後, 我們需要拿幾個函式來測試沒帶 Token 會不會被擋, 這時這些真實的用戶端應用就可派上用場了.
兩全其美的做法是在 functions 底下建一個臨時資料夾 (例如 apps_backup), 將它們移到一個此資料夾中, 與上層的系統操作函式隔離開來, 因為對 AI 來說, 結構的改變就代表了語意的改變, 當 agy 掃描專案目錄, 分析 serverless.py 的功能後, 又看到 functions 目錄下的 apps_backup 資料夾, 它會立刻理解, functions 底下的函式檔是系統管理功能, 而把 apps_backup 判定為不需同步修改的歷史檔案或備份. 如果不想讓 agy 看到這些自訂應用函式檔, 最徹底的方式是在 ,gitignore 檔中加入 functions/apps_backup/ 這一行.
PS D:\antigravity_cli\projects\serverless> mkdir functions\apps_backup
然後用 move 指令將自訂應用函式檔搬到 apps_backup 下 :
PS D:\antigravity_cli\projects\serverless> move functions\add.py functions\apps_backup\
PS D:\antigravity_cli\projects\serverless> move functions\hello.py functions\apps_backup\
PS D:\antigravity_cli\projects\serverless> move functions\linebot_gemini.py functions\apps_backup\
PS D:\antigravity_cli\projects\serverless> move functions\linebot_gpt.py functions\apps_backup\
PS D:\antigravity_cli\projects\serverless> move functions\send_books_messages.py functions\apps_backup\
PS D:\antigravity_cli\projects\serverless> move functions\send_ksml_books_messages.py functions\apps_backup\
PS D:\antigravity_cli\projects\serverless> move functions\update_ksml_books.py functions\apps_backup\
搬移後的檔案結構如下 :
PS D:\antigravity_cli\projects\serverless> tree functions /f
列出磁碟區 新增磁碟區 的資料夾 PATH
磁碟區序號為 00000244 1258:16B8
D:\ANTIGRAVITY_CLI\PROJECTS\SERVERLESS\FUNCTIONS
│ add_function.py
│ add_table.py
│ clear_stats.py
│ delete_function.py
│ delete_record.py
│ drop_table.py
│ edit_function.py
│ execute_sql.py
│ export_table.py
│ list_functions.py
│ list_tables.py
│ save_function.py
│ show_schema.py
│ show_stats.py
│ update_function.py
│ view_table.py
│ __init__.py
│
└─apps_backup
add.py
hello.py
linebot_gemini.py
linebot_gpt.py
send_books_messages.py
send_ksml_books_messages.py
update_ksml_books.py
(5). 提交 Git 紀錄 :
完成應用 app 檔案搬移後, 就完成重構的前置作業了, 用下列兩個指令進行提交, 把搬移成果正式記錄進 Git 的歷史紀錄裡 :
PS D:\antigravity_cli\projects\serverless> git add .
PS D:\antigravity_cli\projects\serverless> git commit -m "chore: 隔離自訂應用至 apps_backup，準備進行 API Token 重構"
[feature/api-token-auth c9afe88] chore: 隔離自訂應用至 apps_backup，準備進行 API Token 重構
7 files changed, 256 insertions(+), 256 deletions(-)
rename functions/{ => apps_backup}/add.py (97%)
rename functions/{ => apps_backup}/hello.py (98%)
rename functions/{ => apps_backup}/linebot_gemini.py (97%)
rename functions/{ => apps_backup}/linebot_gpt.py (97%)
rename functions/{ => apps_backup}/send_books_messages.py (100%)
rename functions/{ => apps_backup}/send_ksml_books_messages.py (97%)
rename functions/{ => apps_backup}/update_ksml_books.py (97%)
