Hikari 的工程筆記

前言剛開始接觸資料庫效能問題時，常常會聽到一句話： 「這個查詢很慢，可能要加 index。」 但 index 到底是什麼？為什麼加了它查詢就可能變快？ 這篇先不鑽太深的資料結構，而是用比較直覺的方式整理 index 的基本概念。 Index 可以想成書的目錄假設你手上有一本很厚的書，想找「例外處理」這個主題。 如果沒有目錄，你只能從第一頁開始慢慢翻。 但如果有目錄，你可以先查目錄，找到相關章節在哪一頁，再直接翻過去。 資料庫的 index 概念也很像。 沒有 index 時，資料庫可能需要掃描整張表，逐筆檢查資料是否符合條件。 有 index 時，資料庫可以透過索引結構更快找到符合條件的資料。 最常見的使用情境假設有一張 Users 表： 123456CREATE TABLE Users ( Id INT PRIMARY KEY, Email VARCHAR(255), Name VARCHAR(100), CreatedAt DATETIME); 如果系統常常用 Email 查使用者： 123SELECT *FROM UsersWHERE Email = & ...

前言很多人在學 Git 分支時，會看到各種流程圖：Git Flow、GitHub Flow、GitLab Flow。 這些流程都有它們的使用情境，但如果專案很小、團隊人數也不多，一開始就套很複雜的分支策略，反而會讓大家卡在流程上。 我覺得分支策略的重點不是名字，而是團隊能不能穩定交付。 最小可用的分支概念最簡單可以先分成兩種： 12main 穩定版本feature 開發中的功能分支 平常開發時，不直接在 main 上改。 而是開一個功能分支： 1git checkout -b feature/add-login-page 完成後送 PR，review 沒問題再合回 main。 這樣至少可以避免開發中的程式直接污染穩定分支。 分支名稱要看得懂分支名稱不用太華麗，但要能看出用途。 例如： 1234feature/add-search-pagefix/login-timeoutchore/update-dependenciesdocs/cloudflare-pages-guide 看到名稱時，至少能知道這個分支大概在做什麼。 比起： 1234testnewfix2hikari-b ...

前言在寫 API 的時候，很容易把成功流程寫得很完整，但錯誤流程只簡單回一句「失敗」。 例如： 1234{ "success": false, "message": "error"} 這種回應對使用者不友善，對前端不友善，對未來要查問題的自己也不友善。 這篇整理一下，我覺得 API 錯誤處理至少可以注意的幾件事。 錯誤訊息要能被理解錯誤訊息的第一個目的，是讓呼叫端知道發生了什麼事。 例如登入失敗時，如果只回： 123{ "message": "failed"} 前端很難判斷要顯示什麼，也不知道是帳號不存在、密碼錯誤，還是系統暫時異常。 可以改成比較明確的格式： 1234{ "code": "INVALID_CREDENTIALS", "message": "帳號或密碼錯誤"} message 給人看，code 給程式判斷。 這樣前端可 ...

前言API 一開始通常都很單純。 前端要什麼，後端就回什麼。 但當系統開始被更多人使用，API 一旦改動，就可能影響既有前端、App、第三方串接，甚至是已經發布出去的舊版本程式。 這時候就會遇到一個問題：API 要怎麼改，才不會把舊使用者弄壞？ 什麼情況會破壞相容性？不是所有 API 修改都需要新版本。 例如新增一個 response 欄位，多數情況下不會破壞舊呼叫端： 12345{ "id": 1, "name": "Hikari", "email": "[email protected]"} 但以下這些改動就比較危險： 移除既有欄位。 改變欄位型別。 改變欄位名稱。 改變錯誤格式。 改變必要參數。 改變原本的業務規則。 例如原本 id 是數字： 123{ "id": 1} 突然改成字串： 123{ "id": "U001"} 對後端來說可能只是 ...

前言在寫小工具或練習專案時，把設定值直接寫在程式裡通常不會有太大問題。 例如： 12var apiUrl = "https://api.example.com";var timeout = 30; 但當專案開始部署到不同環境，像是本機、測試機、正式機，這種寫法就很容易變成維護上的麻煩。 這篇整理一下，為什麼我現在會盡量避免把設定值寫死在程式碼裡。 寫死設定值的問題最常見的問題是：不同環境需要不同設定。 例如： 環境 API URL local http://localhost:5000 staging https://staging-api.example.com production https://api.example.com 如果這些設定都寫死在程式裡，每次切換環境都要改程式碼。 這會帶來幾個風險： 容易把測試環境設定部署到正式環境。 每次改設定都需要重新打包。 敏感資訊可能被 commit 到 Git。 其他開發者不容易知道哪些值應該依環境調整。 寫死設定看似方便，但後面常常會把成本還回來。 設定值應該和程式邏輯分開比較好的方 ...

前言剛開始接觸 Code Review 時，很容易把它想成「找別人錯誤」的流程。 但實際工作一段時間後，我覺得 Code Review 更像是團隊同步理解的過程。 它不只是為了找 bug，也是在確認這段程式碼是否容易維護、是否符合團隊習慣，以及未來的人能不能接得下去。 先理解需求再看程式碼Review 前，我會先看這次變更想解決什麼問題。 如果沒有先理解需求，很容易只針對語法或個人偏好留言。 比較好的順序是： 這個 PR 想解決什麼問題？ 使用者或系統行為會怎麼改變？ 有沒有影響既有流程？ 測試是否覆蓋到主要情境？ 先知道目的，再看實作，才比較能判斷這段程式碼是否合理。 不要只看能不能跑程式能跑只是基本。 Code Review 還可以多看幾件事： 命名是否清楚？ 是否有重複邏輯？ 錯誤處理是否完整？ 邊界情境是否有考慮？ 是否和既有架構一致？ 有沒有不必要的複雜度？ 好的 Review 不是挑剔，而是幫這段程式碼在未來少出一點問題。 留言要具體我覺得 Code Review 留言最怕太抽象。 例如： 1這樣不好 這種留言對作者幫助不大。 比較好的寫法是： 12這裡如果 us ...

前言剛開始寫程式時，看到紅字很容易緊張。 很多人的第一反應會是：複製錯誤訊息去搜尋，或是直接問人「這是什麼問題」。 搜尋和問人都沒有錯，但在那之前，我覺得可以先做一件事：把錯誤訊息完整讀完。 錯誤訊息通常不是敵人，它其實是在告訴你程式壞在哪裡。 先看錯誤類型錯誤訊息通常會先告訴你錯誤類型。 例如 C# 常見的： 1NullReferenceException 這代表你正在操作一個 null 物件。 或是： 1IndexOutOfRangeException 這通常代表你存取了陣列或集合不存在的位置。 先知道錯誤類型，就能先縮小問題範圍。 再看錯誤位置錯誤訊息通常也會附上檔案名稱和行數。 例如： 1at UserService.GetUserName(Int32 userId) in UserService.cs:line 42 這句話的意思是，錯誤發生在 UserService.cs 的第 42 行。 這時候不要只盯著最後一行，也要往上看呼叫堆疊。因為真正的問題有時候不是爆掉的那一行，而是前面傳進來的資料已經不對。 看懂「發生什麼」和「在哪裡發生」讀錯誤訊息時，可以先回答兩個問題 ...

前言剛開始使用 Git 的時候，我其實也常常把 commit message 寫得很隨意。 例如： 123git commit -m "update"git commit -m "fix bug"git commit -m "改一下" 當下看起來沒有問題，因為自己還記得剛剛改了什麼。 但只要過了一兩週，或是專案裡有其他人一起開發，再回頭看這些 commit，就會發現它們幾乎沒有提供任何有效資訊。 這篇就整理一下，我自己在寫 commit message 時會注意的幾個方向。 Commit Message 的用途commit message 不是寫給 Git 看的，而是寫給「未來需要理解這段變更的人」看的。 這個人可能是同事，也可能是幾個月後的自己。 好的 commit message 至少要能回答兩個問題： 這次改了什麼？ 為什麼要這樣改？ 如果 commit message 只寫 fix，那未來看到的人就只能進 diff 裡慢慢猜。 可以用動詞開頭我自己會習慣用一個清楚的動詞開頭，讓 commit 看起來像一個明確的操 ...

前言寫程式時，幾乎一定會遇到需要使用 try & catch 的情境。 它看起來只是把程式碼包起來，但實際上是在幫我們處理「程式執行時可能出現的例外狀況」。這篇就用幾個簡單範例，整理 try & catch 的用途、常見寫法，以及幾個容易混淆的小觀念。 try & catch 的作用是什麼？簡單來說，try & catch 通常有兩個主要使用契機： → 避免程式在執行時，因為非預期錯誤而直接中斷。 → 針對已預期可能發生的例外情境，設計對應的處理流程。 – 大多數情況下，我們使用 try & catch ，都是為了避免程式發生 崩潰（crash），導致後續功能無法繼續執行。 只要程式沒有直接 crash，通常就還有機會繼續運作，或至少能留下錯誤資訊，方便後續追查。至於功能是否完全正確，那就是另一個故事了 123456789// 程式發生例外錯誤的簡單範例static void Main(string[] args){ string a = null; a = a.ToString(); Console.W ...

前言這陣子剛開始經營 Blog，玩 Hexo 跟 Butterfly 主題玩得很開心，也一直在找各種主題美化的資料。 不過我找了很久，都沒有找到「依照深色 / 淺色模式，自動切換頂部與底部背景圖」的做法。最後就用自己的方式把它實作出來了。 這篇會記錄我的做法。原則上，我會盡量避開 Hexo 與 Butterfly 主題的原始檔，改用自訂設定與樣式來完成，之後維護起來也比較方便。 Hikari 也是剛接觸 Hexo 不久，所以這不一定是唯一或最完美的解法，但可以當作一個實作方向參考看看。 步驟流程第一步：在 .yml 檔新增參數首先，到 _config.butterfly.yml 裡定義一個新的圖片路徑參數。 123456# The banner image of home pageindex_img: /pic/index_img.png# 切換深淺模式時使用的第二張首頁圖。# index_img_w 是自訂名稱，可以依需求調整；後方則是圖片路徑。index_img_w: /pic/white.gif 這樣一來，之後要維護圖片就很單純，只要調整路徑即可。 第二步：新增 . ...