Posts on 伊果的沒人看筆記本

鴛鴦鍋就是要分成涮肉區和煮湯區才符合單一職責吧？

Igouist (Igouist) — Sat, 28 Feb 2026 21:00:00 +0800

這篇是我的 2026 年 2 月份 BlogBlog 同樂會投稿，本月主題是「只有我這樣嗎？」。如果你有自己的部落格，歡迎一起來參加！

如果你跟我一樣想看其他朋朋的文章看到爽，可以到：BlogBlog 同樂會：只有我這樣嗎？底下的「已經投稿的作者清單」，有各式各樣的優質文讓你三餐配飯、一次滿足。

參加了「只有我這樣嗎？」的投稿之後，發現原來真的不只我這樣！
感謝 Shuo-jen 的這篇〈火鍋界的「微積分大戰」〉
在追求鴛鴦鍋最佳實踐的路上，我們都不孤單，歡迎更多朋友加入我們！

看到這個月 BlogBlog 同樂會的主題「只有我這樣嗎？」的當下，文章主題就已經確定了。

畢竟曾經在現實生活問過一圈，完全沒有遇到過同樣做法的朋友，當時的想法就真的是「哇，不會只有我們這樣吧？」如此如此，正好寫文一篇，順便推廣推廣。

雖然很想直奔主題，但就像系統設計常說的「脫離問題脈絡、直接討論解決方案，就是耍流氓」，所以讓我們從一些背景脈絡開始聊聊吧。

首先，標題的鴛鴦鍋有一個重要的前提：吃到飽。

認識我的朋友都知道我是一個無肉不歡的人，凡是聚餐必定要大口吃肉、只要進食就一定要大口吃肉，反正就是要大口吃肉。因此我和吃到飽餐廳的關係，就像斷頭台的刀刃和路易十六的脖子，是一場命運般的奔赴：我不是正在吃到飽餐廳，就是正在前往吃到飽餐廳的路上。

而在數以百計的吃到飽餐廳種類中，火鍋又是金字塔的頂端，在煮沸的高湯涮上幾秒鐘，就有熱騰騰香噴噴的肉可以品嘗，從「肉量／每秒」為單位的進食效率來看，可以說是沒有比火鍋更方便的了。連續涮上幾片肉，裹上一些蔥蒜醬料，咬下的瞬間，肉汁和奶香味充盈鼻腔，恍惚間彷彿回到遠古時代的高原上跟野人祖先們一起撕咬獵物，這種感覺實在令人欲罷不能。

為了追求這份歡愉，我踏過了小蒙牛、新馬辣、向辣等戰場，用脂肪累積著戰士的勳章。但是，在這條偉大的火鍋征途上，仍然有一片巨大的陰影，那就是湯。

經常吃吃到飽火鍋的人都知道：只要涮的肉多了，煮到後面湯上面都有一層油，而且浮沫四溢、雜質四散，通常煮到這個程度，這鍋湯也就廢了。

原本該是火鍋主角之一的湯，就這樣淪為了龍套中的龍套，只為了把肉燙熟而服務。尤其像大學生聚餐這種眾菜拱肉的場合，更是連給旁邊火鍋料提鞋兒也不配，什麼湯頭帶來的濃厚、甘甜、溫暖和高普林，根本沒人在乎。散場的時候，也就只留下一灘陰暗扭曲的雜質鍋，跟離職前輩留下來的程式碼一樣，可以說是悲劇中的悲劇，實在令人唏噓。

但如果、如果我們既要又要－－既想大口吃肉，又想大口喝湯，該怎麼辦呢？

某天，我那聰明的女友靈機一動，想出了這套計畫（註：她非常強調要在文章中註明她是發想人。這很合理，畢竟是可以匹敵諾貝爾火鍋獎的殊榮）

在提供鴛鴦鍋的吃到飽火鍋店裡，服務生會請你們選擇兩個湯底——但這其實是一個陷阱。

我們要做的就是：兩邊都選擇同一個湯底。

補充：店員可能會露出疑惑的表情，不要管他，貴在堅持。

並且在最初的點餐中，集中火力在煮湯的底料：番茄、南瓜、玉米等，確保兩邊都各有一份（畢竟肉還是要有點湯味才好吃），份量因人而異。

接著，請選定一邊作為涮肉專區，另一邊則為煮湯專區。

所謂「同樣的條件、不同的經歷，就是不同的人生」我們將在火鍋實踐這一點。顧名思義，涮肉專區將專門用來涮肉，以確保參與者每分每秒都有美味的肉可以享用。

而煮湯專區的壓力就更大了，我們需要大量加入蛤蠣、扇貝等能讓湯頭鮮甜的海鮮，並且看情況運用白菜、香菇等工具來進行調整，偶而也要加入一兩片肉來增添風味。

只要遵守這個簡單的原則：「讓涮肉的歸涮肉、讓煮湯的歸煮湯」在一段時間的熬煮後，我們就能一邊攝取足夠的肉品，一邊享用由海鮮和蔬菜煮好的湯，並在這趟肉和湯的火鍋之旅中，找到兩者之間的平衡。

而在這趟旅程的結束、吃飽喝足的時候，回頭看看同一組湯頭所煮成的兩鍋湯，那又是另一番體悟了。

讓我們回顧這個方案在系統設計層面上的取捨：首先，全面涮肉之所以會毀壞湯底，是因為涮肉的副作用太大，而食材處理區域之間又太過耦合，以至於相互影響。這是典型的技術債，是因為模組拆分不當所造成的。

因此，我們會先想到的做法就是進行隔離。但要如何隔離呢？在民明書坊的《鴛鴦鍋設計模式》提到過：常見的方案是使用「辣」與「不辣」來進行劃分。但經過測試，這並不能解決我們的問題。

幸好，單一職責原則教過我們：「每個類別應該只對一個角色／業務場景負責」我們要找到的就是場景之間的區別；而吃肉吃到飽，跟喝火鍋湯喝到中風，明顯是不同的需求場景，所以我們應該將處理肉和處理湯的模組進行隔離。

經過我們火鍋架構師團隊的一番重構，現在湯頭已經比程式碼還清晰，這篇文章的字數也水得差不多了。那麼，以上就是同時懷著「只有我這樣嗎？」和「哈！只有我這樣吧！」心情所釋出的獨門吃到飽煮鍋秘方，祝各位吃鍋順利，大吉大利！

菜雞抓蟲：AutoMapper 出現奇怪的型別對應錯誤嗎？貼心的慣例式映射可能正在造訪你家

Igouist (Igouist) — Tue, 24 Feb 2026 21:00:00 +0800

部門朋朋前陣子忙著把一卡車陳年專案升級到 .Net 8，原本吃著火鍋唱著歌、升級升得好好的，眼看三下五除二就要升級完畢，但就在這一片祥和安寧之中，突然有個專案升級後 API 就原地死去，只留下 AutoMapper 的錯誤訊息，兇案調查也就此開始……

俗話說得好：不看錯誤訊息的偵探不是好偵探。

讓我們先看看以下片段（為保護當事欄位，已做混淆處理）：

---> AutoMapper.AutoMapperMappingException: Error mapping types.

Mapping types:
BooDataModel -> BooDto
NiceProject.Repositories.DataModel.BooDataModel -> NiceProject.Services.Dto.BooDto

Type Map configuration:
BooDataModel -> BooDto
NiceProject.Repositories.DataModel.BooDataModel -> NiceProject.Services.Dto.BooDto

Destination Member:
ProductOrder

---> AutoMapper.AutoMapperMappingException: Missing type map configuration or unsupported mapping.

Mapping types:
OrderedEnumerable`1 -> Int32
System.Linq.OrderedEnumerable`1[[Product...]] -> System.Int32

對第一現場進行勘驗，發現幾個值得注意的點：

來源類別並沒有 ProductOrder 這個欄位，但目標類別有
MapperConfiguration 並沒有明確要求 Ignore ProductOrder，但原本的版本運行得好好的，升級 .Net 後才出錯

現在我們已經收集了案發現場的線索，但我們還需要回答一個關鍵的問題：錯誤訊息中的 AutoMapper 在案發時究竟做了什麼？

AutoMapper 的貼心 Flattening

要繼續說明下去，就要先從 AutoMapper 的一些貼心小舉動開始說起。

AutoMapper 作為型別轉換工具，最吸引人的賣點就是「基於慣例的映射（Convention-based mapping）」這代表它預先處理了一些常見的情境，讓我們可以無腦使用。例如從 FooName 直接映射到 fooname（自動處理掉大小寫問題）、或是某些型別會自動幫忙轉型等等。

這些慣例在大多時候是很實用的，而且也非常省事。但在一些情況可能就會變成未爆彈，例如在之前的 AutoMapper 筆記介紹過的「2.65 變成 3」之謎：

public class Boo
{
    public double Val { get; set; }
}

public class Foo
{
    public int Val { get; set; }
}

public Foo Sut()
{
    var boo = new Boo
    {
        Val = 2.65
    };

    var config = new MapperConfiguration(cfg => cfg.CreateMap<Boo, Foo>());
    var mapper = config.CreateMapper();
    
    var foo = mapper.Map<Foo>(boo);
    return foo; // 3
}

這次要介紹的就是 AutoMapper 的貼心慣例之一：Flattening

When you configure a source/destination type pair in AutoMapper, the configurator attempts to match properties and methods on the source type to properties on the destination type. If for any property on the destination type a property, method, or a method prefixed with “Get” does not exist on the source type, AutoMapper splits the destination member name into individual words (by PascalCase conventions).

當您在 AutoMapper 中配置來源/目標類型對時，配置器會嘗試將來源類型上的屬性和方法與目標類型上的屬性進行匹配。如果目標類型的任何屬性在來源類型上不存在相應的屬性、方法或以 “Get” 為前綴的方法，AutoMapper 會將目標成員名稱拆分為單獨的單詞（根據 PascalCase 規範）。

（Flattening — AutoMapper documentation）

簡單來說，AutoMapper 在找不到目標的時候，會嘗試把屬性名稱拆成幾個單字，去抓看看有沒有符合的來源。例如 ItemId 就會拆成 Item 跟 Id，再去來源找看看有沒有這兩個東西。

用一組 LinqPad 腳本能更直觀理解這個動作：

public class Source
{
    public SourceItem Item { get; set; }
}

public class SourceItem
{
    public int Id { get; set; }
}

public class Target 
{
    public int ItemId { get; set; }
}

void Main()
{
    var source = new Source
    {
        Item = new SourceItem
        {
            Id = 256 // 準備了 source.Item.Id
        }
    };

    var config = new MapperConfiguration(cfg => cfg.CreateMap<Source, Target>());
    var mapper = config.CreateMapper();

    var target = mapper.Map<Target>(source);
    target.ItemId.Dump(); // target.ItemId = 256, 從 source.Item.Id 抓來的
}

現在我們已經知道了 AutoMapper 會幫忙試試看組裝欄位來兜出一個結果，跟我那個嘗試把夢到的東西跟樂透號碼關聯起來的鄰居一樣。但是在來源型別結構多層又複雜，我們又想賦值到扁平化後的型別的時候，Flattening 還是蠻有用的。

那麼，這個好棒棒慣例跟這次的案情又有什麼關係呢？讓我們看看一個轉型失敗的例子：

public class Source
{
    public SourceItem Item { get; set; }
}

public class SourceItem
{
    public string Id { get; set; }
}

public class Target 
{
    public int ItemId { get; set; }
}

void Main()
{
    var source = new Source
    {
        Item = new SourceItem
        {
            Id = "NaN" // Not a Number 噠！
        }
    };

    var config = new MapperConfiguration(cfg => cfg.CreateMap<Source, Target>());
    var mapper = config.CreateMapper();

    var target = mapper.Map<Target>(source);  // 爆炸！
    target.ItemId.Dump();
}

Error mapping types.

Mapping types:
Source -> Target
UserQuery+Source -> UserQuery+Target

Type Map configuration:
Source -> Target
UserQuery+Source -> UserQuery+Target

Destination Member:
ItemId

沒錯，錯誤訊息跟我們開頭看見的非常相似，都是型別映射錯誤！

走向破案

現在我們已經有了主要手法的假設了，但這個案子還有另一個疑點：升級前的映射沒有出錯，升級後就出錯了。

馬上進入粗暴推理階段：我們知道 AutoMapper 會嘗試去找名稱有關的東西來試試看，而開頭場景中轉型失敗的欄位名稱是 ProductOrder，也就是說 AutoMapper 會嘗試去抓 Product 的 Order。

正好，來源型別的確有一個 IEnumerable<Product> Product 的成員。但是 Order 又是哪裡來的呢？為什麼升級前找不到、升級後反而找到了呢？

噹噹！讓我們看看 .Net 7 Preview 的介紹：Order and OrderDescending

System.Linq now has the methods Order and OrderDescending, which are there to order an IEnumerable according to T.

System.Linq 現在具有方法 Order 與 OrderDescending ，可用於根據 T 對 IEnumerable 進行排序。

這樣就有了 Order 這片拼圖，我們的假設也就很明確了：因為升級之後多了 Order() 這個東東，成功滿足了 Flattening 的條件，原本找不到映射來源會保留預設值的 AutoMapper，在看見了 Order 之後覺得「這名字好像有關ㄟ，來試試看」，進而發生了 Error mapping types.

馬上用這組條件測試看看：

public class Source
{
    public IEnumerable<Product> Product { get; set; }
}

public class Product
{
    
}

public class Target 
{
    public int ProductOrder { get; set; }
}

void Main()
{
    var source = new Source
    {
        Product = new List<Product> {}
    };

    var config = new MapperConfiguration(cfg => cfg.CreateMap<Source, Target>());
    var mapper = config.CreateMapper();

    var target = mapper.Map<Target>(source); // Error mapping types!
    target.ProductOrder.Dump(); 
}

Error mapping types.

Mapping types:
Source -> Target
UserQuery+Source -> UserQuery+Target

Type Map configuration:
Source -> Target
UserQuery+Source -> UserQuery+Target

Destination Member:
ProductOrder

Missing type map configuration or unsupported mapping.

Mapping types:
OrderedEnumerable`2 -> Int32
System.Linq.OrderedEnumerable`2[[UserQuery+Product...]] -> System.Int32

Destination Member:
ProductOrder

重現成功，收工下班。

備註：隨著 AutoMapper 新版本開始收費，我們也正在緩慢地進行搬遷。
如果你也在搬家，這些文章推薦給你：

替換映射工具 - 使用 Mapster | mrkt的程式學習筆記

另一種映射工具 - Mapperly | mrkt的程式學習筆記

從紙筆到電子白板，我的 Heptabase 使用場景

Igouist (Igouist) — Sat, 31 Jan 2026 23:00:00 +0800

這篇是我的 2026 年 1 月份 BlogBlog 同樂會投稿，本月主題是「推坑」。如果你有自己的部落格，歡迎一起來參加！

如果你跟我一樣想看其他朋朋的推坑文看到爽，可以到：「推坑」──2026 年 1 月 BlogBlog 同樂會回顧，有各式各樣的推坑文讓你三餐配飯、一次滿足。

本月主題是「推坑」，原本想不太到要推坑什麼，但看到 PJ 留言「問就是推坑 Heptabase」後，心想：「對呀，我每天都在用 Heptabase，不如就推坑一篇吧！」

按照慣例，推坑開始之前還是要介紹一下什麼是 Heptabase。

這邊直接引用官方 Wiki 和教學影片，基本上看了影片就能馬上知道這軟體是做什麼用的：

Heptabase 是一個專門幫助你學習和研究複雜主題、對事物建立深度理解的視覺化筆記軟體。

雖然說要寫一篇來推坑，但關於 Heptabase 的介紹和教學已經一抓一大把了。

例如官方 Wiki 上就有足夠的使用案例和說明：

或是 Alan 分享的使用流程（當初就是因為這篇文章和裡面那部四小時的示範影片才入坑的）：

The Best Way to Acquire Knowledge from Readings | by 詹雨安 Alan Chan

當然還有更多介紹文，丟幾篇我個人喜歡的：

如果看見這篇文章的人，是想學習使用 Heptabase，那麼上面的資訊已經相當充足了。

那麼，所謂的「推坑文」到底需要什麼呢？果然還是需要推坑者使用的場景和心得吧。

綜上所述，接下來的篇幅就用來介紹我覺得好用的幾個地方了。以下全是個人經驗和主觀意見，充滿大量五星好評吹捧，想到什麼寫什麼。

如果看完發現沒什麼幫助，還請看在前面丟了一堆（別人的）資源的份上原諒我，阿彌陀佛。

從紙筆到電子白板

「喔，你是說你在腦中思考，然後記錄在紙上。」
󠀠『不是。這不是紀錄，這只是過程。你必須在紙上思考，這就是那張紙。』

在開始介紹使用場景之前，要先介紹一下我習慣的筆記方式。從小時候（？）還在學校念書做筆記開始，我就喜歡拿一張白紙，用簡單的文字和箭頭來整理腦子的想法，從第一個字詞開始，逐步地把東西倒出來，邊寫邊嘗試排列出一個方便好記的脈絡。

當時我發覺：如果只是在腦中想過，還是很容易忘；如果是單純閱讀課本或抄寫定義，那更不可能記得，只有像這種圖像式的關聯，才能稍微把記憶留得久一點，即使忘記了，也能藉由筆記上的圖樣更快地喚醒當初的印象。

▲ 跟同事討論分層架構時的筆記，這已經是少數字跡正常的紙筆紀錄了，還請包涵

過程之中也經過了幾次嘗試，有時候先把大框架畫出來、有時候先用第一張紙做條列，第二張紙才做整理、有時候就只是先寫上一個關鍵字，然後想到什麼寫什麼，但都還是遵循在紙上寫字畫箭頭的基本方向。現在回頭看，那也許就是我建構思考框架的過程。我喜歡將資料倒到一個平面上，然後像積木般地擺弄它們、畫上箭頭、用方框分群……試著從中找出關聯。

後來，我認識了 DIKW 模型（具體來說是下面這張圖）才明白：我其實是在學習從資料整理出知識的方法。而且，大多數人也是這樣形成新知識的，只是我的慣用工具是紙和筆。

▲ DIKW 模型：從資料到智慧的漸進關係，資料被整理出脈絡成為資訊，資訊被理解並內化成為知識，而將知識應用在判斷與行動上就成為智慧。有興趣的朋友可以參照這篇：知識是如何形成的？

隨著摸電腦的時數越來越多，漸漸地也開始放下紙跟筆，踏入了筆記軟體這個大坑。

然而沒多久就遇到了一個問題：整理太痛苦了。就像那句經典的「寫作之難，在於把網狀的思考，用樹狀的結構，轉換成線性的文字」，當時大多筆記軟體基本上就是一頁文字檔，和我原本的思考方式產生了很大的撕裂感，也導致製作筆記的摩擦力飆升。

很多時候，我仍然需要先使用外部工具（通常是一張紙）梳理完之後，再降維成一束文字塞到筆記軟體裡。我甚至發現，比起筆記軟體，Whimsical 或 Miro 這種數位白板用起來反而更順手。

後來又輾轉嘗試了多個筆記軟體，例如 Obsidian（我至今還是很喜歡那個視覺化的關聯圖跟豐富的擴充套件生態）、Notion（資料庫頁面的標籤可以下拉選單很方便，現在還是有用來管理我的書櫃）等等，也嘗試過在筆記內嵌 Drawio 的圖、用擴充套件來加入 Mermaid，但都沒能達到想像中的效果。

直到有一天，發現了一個主打白板的軟體：Heptabase。

這就是我尋找已久的筆記方式。

白板的真實本質是它是一張巨大的、無邊界的桌子。無論你是否自認為是視覺型思考者，每個人都需要一張桌子。桌子的大小決定你能同時看到多少資訊，進而影響你思考能延伸多遠。（The Best Way to Use AI for Learning - Yu An Chan）

▲ 搬家後的第一個白板：把物件導向跟依賴注入的筆記整理過去

我們可以在白板上自由地加上筆記、拉出線條，把筆記分群上色，實際上就這麼簡單。

但在快樂蜜月期（剛接觸筆記軟體都會有的一段時期，會瘋狂地加入筆記和試用各種功能，特徵是會看著自己的筆記呵呵笑）時，我還發現了更多白板帶來的優點：

第一項就是能用的空間變大了。原本受限於紙張大小的我，寫個字都很彆扭，不得已只能用抽象攏統的字代替。但現在一個節點是一則筆記，可以自由地完善這則筆記，我能用的空間和深度都大了許多，可以說是舒適無比。

第二個則是：在這個整合、梳理資料的過程中，我們很容易發現自己的疏漏。兩則筆記似乎應該要有關聯，但感覺線拉得很牽強？中間很可能少了一個關鍵觀念；把筆記分群之後感覺有一區特別稀疏？那就是補強的時候了。這種感覺很接近撰寫部落格文章時那種邊寫邊學的狀態，就是文章寫到一半才發現需要調查更多資訊，最終被迫在過程中學習到更多東西，這也算是一種輸出式學習了吧。

最後一個則是成就感。畢竟我是一個還算虛榮（？）的人，基本上就是會看著自己的作品沾沾自喜的類型（例如遊戲白金獎盃，或是自己覺得設計得很漂亮的程式架構）。白板本身就要求我們盤點自己的知識點、不斷整合資訊，整理出明確可見的關聯、在過程中擴張知識邊界。不斷重複以上步驟，在一波忘我的忙碌之後，發現白板已經隱隱約約有了一些知識的輪廓，對我這樣的人來說，沒有什麼比這個更令人愉悅了吧。

諸如此類，如果濃縮成一句心得的話，那就是：白板，真棒呀。（真是詞窮的表現）

補充：Heptabase 在九月上線了 Heptabase Gallery，裡面已經有許多朋朋分享的白板，可以上去逛逛其他人是怎麼使用白板，或是說，是怎麼思考、理解、梳理某個問題的。我一直對別人怎麼做這些事很有興趣，畫廊跟白板的 Publish 功能給了一個很棒的場景。

資料來源的好幫手：Readwise 與它的家族

在前面一頓對白板的無情吹捧之後，我們還是要面對現實：
如果我們要把知識點放到白板，我們必須要先有知識點（對，我知道有點廢話）

也就是說，我們需要先確認兩件事：

來源有哪些？我們去哪裡閱讀新的資訊？
我們要如何把這些資訊丟到我們的筆記軟體？

我目前閱讀的管道主要來自三個：RSS 訂閱、KOBO 電子書，以及社群媒體

RSS 用來訂閱我感興趣的網站
KOBO 是通勤路上的好夥伴
社群媒體用來打發碎片化時間

友善附註：RSS，是一種自古以來就存在（？）的訂閱方式。主要是將網站裡文章的標題和簡介等資訊整理成 XML 的文字格式（例如本站的 RSS 頁面），使訂閱服務只需要去各個網站抓取輕便的文字檔就能夠得知網站是否更新、現在有哪些文章等資訊，非常方便。

更重要的是，藉由自己選擇要訂閱的網站，就能讓我們自己決定資訊來源，在噪音多到爆炸的網路上可說是一片淨土。有興趣的朋友可以閱讀：

RSS：一份由你設計的報紙 | Tian-Yan’s Blog

你需要用 RSS，不要再拖了 | Wiwi.Blog

當我們提到「如何把這些內容丟到 Heptabase」，就必須提另一個常一起玩的好夥伴：Readwise

Readwise 是用來玩資料串串樂的，我們可以從 Kobo、Twitter、Medium 等軟體把閱讀時的劃線重點 Import 到 Readwise，再從 Readwise 把這些劃線重點 Export 到 Heptabase、Notion、Obsidian，基本上就跟《瘟疫公司》裡的鳥禽類作用一樣：從Ａ國家帶著病毒飛越大海散佈給Ｂ國家，帶來知識與希望。

題外話：我常覺得 Readwise 的 Twitter 同步做法很有趣，你需要把想收藏的推文用訊息發給 @readwise 這個帳號，它就會同步到你的 Readwise 上。每次按「透過聊天發送」都有一種「欸你先幫我把這東西拿回家」的錯覺

常被同時提到的還有 Readwise Reader，顧名思義是個閱讀工具，用來管理並閱讀 RSS 訂閱內容。並且在 Readwise Reader 劃的重點也會自動同步到 Readwise，進而同步到我們設定好的 Export 軟體，例如 Heptabase，直接做到一條龍。

我原本用來管理 RSS 訂閱的是 Feedly（還寫了一篇 Feedly —— 用 RSS 訂閱來主動篩選資訊吧），但在接觸 Readwise Reader 的強大整合就毅然決然跳槽了。

除了 RSS 訂閱內容作為出發點的這條路線以外，Readwise 也提供了瀏覽器擴充套件 Readwise Highlighter，可以直接在網頁上劃線，並將網頁內容同步到 Readwise Reader。如果閱讀到不錯的網頁，例如偶然發現的超讚部落格文章，就可以直接用 Highlighter 劃線並收藏。

我們從 Readwise Highlighter 和 Readwise Reader 收藏的劃線，最終會從 Readwise 同步到 Heptabase，並集中在 Heptabase 的 Highlight 頁面，後續就可以在我們的白板上取用，也能在每則 Highlight 底下繼續加上筆記、關聯其他筆記。

最重要的是：我們能在 Heptabase 用搜尋找到 Highlight，這個搜尋功能多次幫助了腦子只剩下一堆碎片的我成功找回當初看到的某篇文章，幫助很大，必須額外花一句話來稱讚。

▲ Highlight 頁面，可以看見從各個地方同步來的劃線筆記

聊完 Readwise 之後，另一個把資料丟進 Heptabase 的常用工具是官方的瀏覽器擴充套件 Heptabase Web Clipper，它會將網頁全文摘取到 Heptabase 中並建立一張卡片，還會標上來源連結。但由於我的外部資料主要集中在 Highlight 了，並且很難區分 Web Clipper 建立的卡片和我自己建立的卡片，對很喜歡在文章中加入一大堆外部連結的我來說有點困擾，因此使用的次數相對較少，只有在我打算留存全文、綁架人家的文章回家拆成卡片的時候才會使用。

現在我們已經簡短認識了 Readwise 家族，以及 Heptabase 自己推出的 Web，是跟上面的資訊來源（RSS、KOBO、社群）進行連連看的時候了。目前我的蒐集管道如下：

RSS 訂閱 → Readwise Reader（劃線）→ Readwise → Heptabase
文章閱讀 → Readwise Reader（劃線）→ Readwise → Heptabase
文章閱讀（如果想存全文） → Heptabase Web Clipper → Heptabase
KOBO → Readwise → Heptabase
Twitter → Readwise → Heptabase
Facebook → 分享連結到 Readwise Reader → Readwise → Heptabase
電子報 → 用 Readwise Reader 信箱訂閱 → Readwise → Heptabase

藉由這些路線，就可以把各處蒐集來的資訊集中到 Heptabase，成為後續筆記的養份。

延伸閱讀，順便丟一些 Readwise 介紹文章給有興趣的朋友：

Readwise Reader 付費訂閱三年評價，AI 快時代的「慢閱讀」

全方位閱讀軟體 Readwise Reader ── 文章匯入篇 - 好奇先生

Readwise + Heptabase 使用案例分享：讀文章、做筆記原來那麼簡單

關於閱讀與學習的工作流：Readwise Reader + Obsidian - 賴澤霖 - Medium

我所在意的筆記軟體功能：雙向鏈結、日誌、搜尋

前面聊完白板跟資料來源這兩個我最在意的重點，剩下的篇幅就用來聊聊一些我喜歡的功能吧。

首先一定要提的就是雙向鏈結，我最早是在 Roam Research 接觸到雙鏈這個概念的（現在似乎已經成為大多筆記的標配？），實際用了一段時間之後的確再也離不開了，因此第一段功能介紹就留給雙鏈。

雙向鏈結指的是「我在Ａ筆記提到Ｂ筆記，那麼我在Ｂ筆記也能看到Ａ筆記提到了Ｂ筆記」，其中

「Ａ筆記提到Ｂ筆記」是我們常見的正向鏈結
「Ｂ筆記也能看到Ａ筆記提到了Ｂ筆記」就是反向鏈結（Backlinks）

……用說的有點饒口，其實就是以前無名小站的「誰來我家」功能，只是對象換成了筆記，哪則筆記來我家。

利用反向鏈結，就可以從Ｂ筆記發現Ａ筆記的內容。尤其像我這種寫個文章都要插一堆超連結的人，可能撰寫Ａ筆記的時候，剛好覺得這和Ｂ筆記有關聯，就會順手標記上去。過了很久很久以後，當我瀏覽到Ｂ筆記，就能馬上掌握Ｂ和Ａ的關聯，這時候都會有一種賺到了的感覺。

如果以上的ＡＢ優酪乳大亂鬥看得有點亂，讓我們來看幾個簡單的例子：

以我在整理物件導向相關的筆記為例：我在單一職責原則、依賴反轉原則…等筆記都會提到跟介面的關係。那麼，我下次到介面的筆記時，就可以藉由反向連結，直接看到各個原則是怎麼應用介面的：

除了發現筆記間的關聯，並且能以某則筆記為主角看看其他筆記提到的內容以外，在日常工作上其實也有妙處。

我習慣在每天先到 Journal 頁面（類似每日筆記的地方）列好當天的任務，有進度的時候也會在 Journal 頁面關聯任務筆記，並放上相關的討論和紀錄（通常是隨手打個一兩句）

如此一來，當我有需要（？）的時候，就能在任務卡片的反向鏈結迅速確認每天的任務狀況和相關紀錄，還原專案的歷程及脈絡，意外地相當方便。

既然前面提到了 Journal，第二個就來聊聊我很需要的部份：日誌

我並不是喜歡在筆記軟體中頻繁切換畫面的人，那很容易打斷心流。因此，我更偏好大部份的工作都在少數幾個頁面中完成，像是白板能夠在畫布上完成知識點的拆分和梳理，就完全滿足這個需求。

但許多日常工作和臨時想法是無法當場花時間進行組織和整理的，我從 Roam Research 到 Obsidian 都已經習慣「開一個 Daily Note 來當作每日快速筆記」的做法。幸好，Heptabase 的每日筆記（Journal）非常好用，搭配側欄也不容易打斷心流，基本上成為了我日常工作的重心。

因此，我在使用 Heptabase 的時候，核心頁面就是這兩個：

當我正在研究一個主題、整理一組筆記，我的主要頁面是白板
當我每天執行工作、確認待辦項目、快速蒐集想法時，我的主要頁面是日誌

以今天（對，身為一個拖延症重度患者，這篇文章是壓線到最後一天寫的）的日誌頁面為例：

可以看見我習慣把日誌頁面分成三個部分：本日行程、待辦項目、每日紀錄。

每天我打開 Heptabase，就是先到日誌整理好當天行程、決定待辦項目、把相關的紀錄放到底下（像是某某專案決定怎麼實作、發現一個適合寫作的好點子、跟朋友聊到一個值得紀錄的概念，或只是想到什麼寫什麼）。每則紀錄都關聯到對應的筆記條目，後續就可以像前面雙向鏈結提到的，在各個筆記頁面用反向鏈結確認每天留下的紀錄。

同樣地，也可以使用關聯的方式，確保某天會需要的資訊自動出現在某天的日誌：

假設約好了下禮拜四要跟家人出門吃飯，就可以直接關聯下週四的日誌並打上「吃飯」，等到下週四的時候這則「吃飯」就會出現在日誌頁面底下的反向鏈結
假設某個專案預定在禮拜一完成Ａ任務、禮拜二完成Ｂ任務，我習慣將專案預計需要進行的步驟先全部列好，這時候就可以直接在專案筆記將Ａ任務的日期標為禮拜一，在禮拜一的日誌底下反向鏈結就會提到這個任務

備註：在上面的例子，如果是用待辦項目（Todo list）標記了某個日期的話，該日期的 Journal 右上角 todos 也會出現這則待辦（這真的是我最喜歡的更新之一，對我這種到處放待辦事項的人來說根本是德政）

搭配側邊攔直接開始相關的筆記頁面（例如整理專案資訊的筆記，又或者今天會用到的知識點筆記），可以做到在日誌畫面就處理完大部份的工作，說不定我停留在日誌頁面的時間還比白板長也不一定呢。

藉由白板跟雙向鏈結，就能盡可能保留筆記之間的關聯和脈絡，做出網狀般的知識庫。而搭配日誌、同步外部資料、擷取網頁，就能讓外部的資料有一個入口，提供知識庫源源不絕的燃料。當我打算列出一些我會在意的功能時，首先想到的就是這些，這可能也代表了這些功能對我的不可或缺。

當然，我還有許多在意的地方，例如搜尋。因為我記性不是很好，除了已經動手到白板的筆記以外，有些零散的筆記、隨手畫的線、從優質文章摘取下來的片段，平常都是散落在我的卡片庫裡的，頂多標了個標籤作為提醒。因此，我在使用筆記軟體時，其實是十分依賴搜尋功能的。Heptabase 的搜尋目前體感還蠻快的，而且可以同時搜尋到筆記內容和劃線重點，已滿足我的需求。

又或者看板，因為我的筆記軟體大多同時承載知識管理和專案管理的工作，對我來說，工作上的專案勢必會應用到先前累積的知識，兩者是無法分離的。而在 Heptabase 中，可以藉由標籤來將同性質的筆記列在一組標籤資料庫（Tag Database）裡，再加上一組專案進度的屬性，就能用看板（Kanban）的方式進行管理，這點也相當足夠。

諸如此類的部份就不展開細講了。~~主要是因為寫到這邊已經快晚上十點，感覺要來不及寫完了~~

小結

從大學寫筆記開始，一路用了 Evernote、Roam Research、Obsidian，最後半定居在 Hetpabase。最主要的因素還是前面提到的幾個場景（白板、雙鏈、日誌）都有符合我的需求。尤其是白板。既契合了我學習和思考的模式，又能保留更多的脈絡。

當我們看見一幅白板，甚至能大略知道這個人是怎麼理解這個主題的，又是怎麼拆解、怎麼組裝這些知識的（當然，這個「人」也包括六個月前的自己），白板保留了一部份思路，進而讓我們能窺見這個過程。

要打造一個脈絡化的知識網路，第二件事情是要確保所有知識和想法背後的思考脈絡都能被完整保存和追蹤。當你看到一個想法時，你必須能回憶起這個想法是怎麼產生的、又在哪些場景下被使用。

人類創造出的所有知識和想法，都是先有輸入，才有輸出。「追蹤思考脈絡」其實就是在幫助我們暸解什麼樣的輸入造成了什麼樣的輸出。也因此，我們必需打通生命週期中的「收集」、「思考」、「創作」這三個環節。（04 - The Knowledge Lifecycle）

甚至在看別人分享他們如何使用 Heptabase 整理筆記、自己也實際使用 Heptabase 整理筆記之後，會有種感覺：也許我們真的能藉由這種方式來學習如何掌握知識，最終讓自己變得更好。

A good thinking tool shouldn’t just hand users answers to their questions, but also guide and enable them to discover and articulate more complex questions.

一個好的思考工具不應該只是給用戶提供問題的答案，還應該引導並使他們能夠發現和表達更複雜的問題。（Linux’s stream）

決定 Heptabase 做為推坑主題之後，我一直在想：所謂的「推坑」到底是什麼呢？

尤其開始動手寫之前，我的想像一直被侷限在「推銷」，也就是「哇！這個東西有多麼多麼好」，或是是「你為什麼該用這個東西」。但是越寫越覺得，這好像不是我想要表達的方向。

看了幾篇推坑文，又回頭想想才發現：我是一個看到別人吃好吃的東西就會想吃、看到別人玩好玩的遊戲就會想玩的人。所以，能夠推坑我的東西，其實都有一個共通的特點：他們自己用得很開心。

只有對方分享自己的快樂，才會讓我想要嘗試。我甚至會想：也許最尊重對方的推坑方式，就是過好自己的生活也不一定。

所以，我最後決定用這樣的方式呈現：用我個人的使用場景來記錄這篇推坑。

如果你讀到這裡，然後你使用筆記的場景，跟我也有那麼一點類似，那麼我會推薦你：試試看 Heptabase 吧！

記一次把部落格圖片從 Imgur 搬到 Cloudflare R2 的過程

Igouist (Igouist) — Thu, 31 Jul 2025 23:00:00 +0800

在上個月的 Imgur 一直 temporarily over capacity 嗎？先檢查網路看看吧提到，因為 Imgur 不給上傳圖片了，現在寫個文章還得開 VPN 才能貼圖片。

拖著拖著七月也要過了，決定趁休假的時候來把圖床搬一搬。

比起實作上的拖延，搬家目標則早早決定好要嘗試這篇「Imgur 封鎖台灣 IP，我把圖床搬到 Cloudflare R2 - Code and Me」提到的 Cloudflare R2。

畢竟出口流量免費實在太香了，不愧是賽博菩薩。這就馬上前來皈依。

考慮到每位朋朋的部落格選型不同，先說明一下我家的狀況：

使用 Hugo 建置，直接丟在 Github Pages
圖片目前放在 Imgur

這代表有些較為暴力的操作可能只適用於我目前的狀況，例如直接在檔案裡搜尋 imgur 來抓圖等等（所以如果你是從關鍵字搜尋進來這篇文章的，請從右手邊的文章目錄直接前往你需要的小節）

這次圖床搬家主要進行了以下步驟：

章節目錄

如此如此，說搬就搬，這篇就紀錄一下這次的圖床搬家過程。

建立 Cloudflare R2 資源

既然都決定要搬家到 Cloudflare R2 了，首先當然是要建立一個 Cloudflare R2 資源。

建立 R2 的操作可以參考這篇「架設 Cloudflare R2 免費圖床，給 Hugo 靜態網站託管圖片 - Ivon 的部落格」的「新增 Cloudflare R2 bucket」小節，流程詳細還附圖，基本可以照著把 R2 儲存空間給建出來。

總之先到 Cloudflare 儀表板，把 R2 儲存體建出來，然後順手掛個自訂網域：

備註：如果想要自訂 R2 資源對外的網址，需要先讓 R2 和 Cloudflare 上存在的網域做綁定，也就是要在 Cloudflare 買網域或是其他地方買來掛在 Cloudflare 上（參考 Public buckets）

因為我（之前為了改 Bluesky 的帳號名稱）已經在 Cloudflare 購買過網域了，所以可以直接用自定義網域來把圖片網址改成我要的網址。

如果你也想要自訂圖片網址，但在 Cloudflare 還沒有任何網域，可以先多找幾篇網域購買和託管到 Cloudflare 的文章（例如 Cloudflare 網域購買教學）參考參考，再決定要不要投入 $$ 買一個自己喜歡的名字。

建立完畢之後，可以先進貯體隨便上傳一張圖片，確認一下 URL 有沒有連到圖片：

弄個 Powershell 腳本把部落格的圖片先抓下來

建好 R2 空間之後，就要開始著手搬遷啦～

我的部落格採用 Hugo + Github Pages，所以文章內容也就是一堆 Markdown 檔案而已。這種狀況下，最快的方式就是直接搜出文章中的圖片連結就行。

幸好 2025 年的懶人是有福的，直接請 GPT 幫我產一組 Powershell 腳本，把 .md 檔拖出來，掃到圖片就抓下來存著，迅速搞定這一階段：

# see: https://gist.github.com/mufidu/f7b795f844f1ee4dc78e55123d5a398b

# 1. 指定資料夾
$folder    = "C:\Blog\content"
$outputDir = "C:\Users\xxx\Pictures\Blog-Image-Backup"

# 2. 建立目標資料夾（若不存在）
if (-not (Test-Path $outputDir)) {
    New-Item -Path $outputDir -ItemType Directory | Out-Null
}

# 3. 逐一掃描 .md 檔案
Get-ChildItem -Path $folder -Filter *.md -Recurse | ForEach-Object {
    $mdFile  = $_.FullName
    $content = Get-Content -Path $mdFile

    foreach ($line in $content) {
        # 4. 正則擷取 Markdown 圖片 URL
        if ($line -match '!\[[^\]]*\]\((?<url>https?://[^\)]+)\)') {
            $url      = $Matches['url']
            # 5. 以 URL 最後一節當作檔名
            $fileName = Split-Path -Path $url -Leaf
            $destPath = Join-Path $outputDir $fileName

            try {
                # 6. 下載圖片
                Invoke-WebRequest -Uri $url -OutFile $destPath -UseBasicParsing
                Write-Host "已下載： $url → $destPath"
            }
            catch {
                Write-Warning "下載失敗： $url (`$_`)"
            }
        }
    }
}

插件：順便用 WebP 把圖片做一下壓縮

圖片下載完後，突然想起之前跑 PageSpeed Insights 時有被提示過圖檔太大的問題，決定趁這機會順便把圖壓成 WebP。

WebP 是 Google 推的圖片格式，從 developers.google 對 WebP 的介紹來看，WebP 無損壓縮後的檔案大小能比 PNG 小 26%，而有損壓縮在同樣壓縮品下也能比 JPEG 小 25-34%。

補充：有些情況下跑完 WebP 反而會讓檔案大小變大，例如 JPG 轉 WebP（參見 Image size is increased when converted from jpg to webp with quality value 100）

而在 WebP 常見問題文檔的「Can a WebP image grow larger than its source image?」這一小節有說明可能會導致檔案變大的場景，有遇到的朋友可以先確認看看。

因為我的部落格大多是 PNG 圖檔，文檔提到「Note that converting a JPEG source to lossy WebP, or a PNG source to lossless WebP are not prone to such file size surprises.」所以我仍然可以無腦轉 WebP，如果是跟我一樣都是 PNG 的朋友就別擔心了。

在開始動手之前，需要先確保環境中有 WebP 的工具。沒有的朋朋們請先到 Google for Developers 下載回來（為了方便後續使用，可以把 bin 的路徑丟進環境變數）

接著同樣產個小腳本來逐個把圖片壓成 WebP，這段除了好朋友 GPT 以外，還參考了這兩篇：

# 記得先下載 WebP 工具: https://developers.google.com/speed/webp/download

# 1. 設定來源與輸出資料夾
$inputFolder  = "C:\Users\xxx\Pictures\Blog-Image-Backup"
$outputFolder = Join-Path $inputFolder "WebP"

# 2. 建立輸出資料夾（若不存在）
if (-not (Test-Path $outputFolder)) {
    New-Item -Path $outputFolder -ItemType Directory | Out-Null
}

# 3. 定義可轉檔副檔名清單
$convertExts = @('.jpg', '.jpeg', '.png')

# 4. 遞迴取得所有檔案，並排除輸出資料夾本身
Get-ChildItem -Path $inputFolder -File -Recurse |
    Where-Object { $_.FullName -notlike "$outputFolder*"} |
    ForEach-Object {
        $src = $_.FullName
        $ext = $_.Extension.ToLower()

        if ($convertExts -contains $ext) {
            # 5a. 轉檔：jpg/jpeg/png → webp
            $dest = Join-Path $outputFolder ($_.BaseName + ".webp")

            # 使用 -q 指定壓縮品質（0-100, ex: -q 80）
            # 如果需要無損壓縮，可以使用 -lossless 參數
            # 但注意有損的 JPG 之類轉無損 WebP 反而會讓檔案變大哦
            & cwebp -lossless $src -o $dest > $null
            Write-Host "Converted: $src → $dest"
        }
        else {
            # 5b. 其餘格式（例如 gif）直接複製
            # 畢竟後續還是都要上傳到新的圖床，不能轉的就直接過去吧
            $dest = Join-Path $outputFolder $_.Name
            Copy-Item -Path $src -Destination $dest -Force
            Write-Host "Copied:    $src → $dest"
        }
    }

上傳圖片到 Cloudflare R2

現在我們有一卡車圖檔準備要大舉進攻 Cloudflare R2，按照上面的節奏。聰明的朋朋也許會想：
這傢伙又要叫 GPT 幫我們產腳本來上傳了吧？

但很可惜，我請 GPT 產腳本是因為我很懶，所以有更懶的方法存在時，我是連腳本都不考慮的。

這個步驟最懶的方法就是直接滑鼠點一點，畢竟 Cloudflare R2 在瀏覽器就可以拖檔案上傳了：

雖然瀏覽器上傳有每次一百個檔案的限制，但考慮到我部落格 ~~拖稿嚴重~~ 圖片不多，因此手動上傳也是分分鐘的事情，這個步驟就手動傳一傳收工。

補充：如果檔案太多，或是好想用下指令的方式上傳呢？請參考 R2 文檔的 Upload objects

因為前面的步驟只是下載檔案又上傳檔案，連檔名都沒更動，接著只要回去文章內文把原本有 i.imgur.com 的連結都替代成新的圖片網址就搞定囉～

補充：如果像我一樣，有些 JS 的操作會去呼叫圖片網址的話，可能會看到 CORS 的錯誤訊息，例如：Access to image at 'https://xxxx/xxxxxx.webp' from origin 'https://xxxxxx.github.io' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

這時候只要去 R2 儲存體的「設定」找到 CORS 原則，把站台加上去就可以了。

使用 VSCode 的 Markdown-image 延伸模組直接上傳圖片到 Cloudflare R2

到這邊其實部落格的圖床遷移已經完成了，但因為我習慣用 VSCode 撰寫文章，之前都用 vscode-imgur 這款延伸模組，實現貼上圖片自動上傳 Imgur 的舒適體驗。

但現在圖床搬家到 Cloudflare R2 了，當然也要調整一下 VSCode 的上傳圖片工具。果斷採用開頭這篇「Imgur 封鎖台灣 IP，我把圖床搬到 Cloudflare R2」提到的 Markdown-image

另外在設定的過程中還參考了以下兩篇：

首先我們得申請一組權杖，可以參考 Cloudflare 官方文檔的 Authentication 操作，或是從 R2 頁面的右側進入 API 權杖的頁面：

新增一組能夠「物件讀取和寫入」的權杖後，會來到金鑰畫面。注意這組金鑰跟識別碼只會出現一次，請務必記下來，等等設定延伸模組的時候會用到：

建立完之後，進到我們要上傳圖片的貯體，進到設定頁面，這邊的名稱跟 S3 API 資訊等等也會用到：

接著讓我們回到 VSCode，到設定裡面找到 Markdown Image 的相關設定，把上傳圖片的方式改為「S3」（不是 Cloudflare 哦！）

最後就是把剛剛拿到的資訊一個一個填進去設定裡啦～

這邊提供我填的內容給需要的朋朋參考：

S3: Endpoint => R2 設定頁面的 S3 API
- ps: 可以不用放最後面的儲存體名稱，反正等等 Bucket Name 要放
S3: Region => 直接填 auto 就好
S3: Bucket Name => 儲存體（貯體）名稱，抄 R2 設定頁面的名稱就好
- ps: 如果 Endpoint 有包含儲存體名稱了，這邊會開成資料夾
S3: Access Key ID => 發金鑰時拿到的存取金鑰識別碼
S3: Secret Access Key => 發金鑰時拿到的秘密存取金鑰
S3: Cdn => 我們自定義的 CDN 路徑 + {filepath}"

都搞定之後就可以開個 .md 檔、複製個圖片，試試看 Shift + Alt + V 有沒有自動上傳囉～

小結

從 Imgur 爆炸到搬完圖片也拖了快兩個月，但幸好有蠻多前人遺跡和好夥伴 GPT 的協助，還算搬得順利。秉持著一個「做都做了」的理念，乾脆把圖床搬家過程也拿出來水一篇，喜得部落格文章數 +1

搬完之後想說圖片也壓縮了、R2 也有快取之類的，是不是再來跑一次 PageSpeed Insights，分數意外地比之前高不少，也算是一個意外撿到的驚喜了

參考資料

C#: 使用 PDFSharp 在 PDF 加上浮水印和檔案密碼吧

Igouist (Igouist) — Mon, 07 Jul 2025 16:00:00 +0800

接續前一篇 C#: 使用 DinkToPdf 把 HTML 轉成 PDF，這篇要來用 PDFSharp 對 PDF 檔案進行一些小小的調整。基本上就是紀錄一下這次遇到的需求和一些坑，主要的內容會有：

替 PDF 加上浮水印
實作 FontResolver 以支援中文字，避免 ⎕⎕⎕
替 PDF 加上檔案密碼

首先當然是要先安裝 PDFSharp 套件：

接續上次的進度，我們把 PDF 檔案弄成了一組 byte[]：

// 在上一篇文章，我們使用 DinkToPdf 把 Html 轉成了 PDF 檔案的 byte[]
var pdfBytes = converter.Convert(doc);

// 或是打開已存在的 PDF 檔案（留著讓我以後複製貼上）
// var pdfBytes = File.ReadAllBytes(@"C:\temp\output.pdf");

// 使用 PdfSharp 由記憶體串流讀取轉換後的 PDF，開啟模式設定為 Modify（可以進行修改）
using var document = PdfReader.Open(new MemoryStream(pdfBytes), PdfDocumentOpenMode.Modify);

現在我們已經用 PDFSharp 開啟這個 PDF 檔案了，接著就讓我們從加上簡單的浮水印開始吧！

替 PDF 加上浮水印

加浮水印的時候要注意幾個小部份：

PDF 是逐頁構成的，所以要 foreach document.Pages 一頁一頁加上去
浮水印的原理是用繪圖工具把字畫上去，繪圖點的預設位置是座標 (0,0)，如果浮水印要壓成斜的話要記得先旋轉

以下採用直接對程式碼進行註解的說明方式，
朋朋們也可以對照參考官方的 Sample：PDFsharp Sample: Watermark

var watermarkContent = "waterwater";

// 記得用 EmbedCompleteFontFile 把字體嵌進去 PDF 避免客戶亂碼
//（ps: 大家常用的 Always 選項已經被淘汰了）
// 但要注意嵌入字體會讓 PDF 檔案變大
var font = new XFont(
    familyName: "Arial",
    emSize: 25,
    style: XFontStyleEx.Regular,
    pdfOptions: new XPdfFontOptions(
        PdfFontEncoding.Unicode, 
        PdfFontEmbedding.EmbedCompleteFontFile));

// 建立一個半透明的筆刷來繪製浮水印
// XColor.FromArgb(50, 0, 0, 0) 表示透明度 50（0~255），顏色為黑色 (0, 0, 0)
var brush = new XSolidBrush(XColor.FromArgb(25, 0, 0, 0));

// 注意：每一頁都是單獨的 Page，所以浮水印要一頁一頁加
foreach (PdfPage page in document.Pages)
{
    // 浮水印需要用繪圖工具，所以先從當前頁面開一個 XGraphics
    // 其中 XGraphicsPdfPageOptions 的 Append 和 Prepend 會影響浮水印在現有物件前方或後方
    // 可參考: https://github.com/Lakerfield/PdfSharp/blob/master/PDFsharp/code/PdfSharp/PdfSharp.Drawing/enums/XGraphicsPdfPageOptions.cs
    using var gfx = XGraphics.FromPdfPage(page, XGraphicsPdfPageOptions.Append);

    // 取得當前頁面的寬度與高度，以便計算頁面的中心點
    // 因為旋轉會以畫面中央為中心處理，因此要將繪圖點先移動到頁面的中央再進行旋轉
    // 確保後續加浮水印文字的角度正確
    // 可以想像成桌子上放一張 A4 紙，然後用手指戳著一個點，再轉看看那張紙，會比較有畫面
    var pageWidth = page.Width;
    var pageHeight = page.Height;
    gfx.TranslateTransform(pageWidth / 2, pageHeight / 2);
    gfx.RotateTransform(-45);

    // 旋轉完之後，將繪圖點移回原本的位置（0, 0），準備壓字上去
    gfx.TranslateTransform(-pageWidth / 2, -pageHeight / 2);

    // 使用 DrawString 方法在頁面中央繪製浮水印文字
    // 建立一個覆蓋整個頁面的 XRect，並以 Center 對齊格式顯示文字
    gfx.DrawString(watermarkContent, font, brush, new XRect(0, 0, pageWidth, pageHeight), XStringFormats.Center);
}

最後存檔測一下：

// 儲存 PDF 文件
var fileName = $"TestPdf_{DateTime.Now.ToString("yyyyMMdd_HHmmss")}.pdf";
var outputPath = @"C:\temp\" + fileName;
document.Save(outputPath);

實作 FontResolver 以支援中文字

上面我們替 PDF 加上了浮水印，但浮水印有包含中文字的朋友可能會注意到中文都變成「⎕⎕⎕」了

這是因為 PDFSharp 在 Core 的版本預設只支援部分英文字體（它想要跨平台，但它沒法知道你用的平台都有啥字體），要讓 PDFSharp 使用中文字體的話，就要自行實作 FontResolver 並掛到 GlobalFontSettings 上。

這部份可以參照官方文件 Font-Resolvin 的說明。
同樣地，這邊也留一份程式碼作為示範（不然我以後上哪複製？）

首先實作字型解析用的 CustomFontResolver，以標楷體為例：

// 自訂字型解析器實作
// 沒做這個的話，中文會變成 ⎕⎕⎕
// see: https://docs.pdfsharp.net/link/font-resolving.html
public class CustomFontResolver : IFontResolver
{
    private const string KaiFontKey = "KAIU";

    public byte[] GetFont(string faceName)
    {
        string fontPath = @"C:\Fonts\kaiu.ttf"; // 記得要改成字型檔案路徑
        if (File.Exists(fontPath))
        {
            return File.ReadAllBytes(fontPath);
        }
        throw new FileNotFoundException("找不到字型檔案：" + fontPath);
    }

    public FontResolverInfo ResolveTypeface(string familyName, bool isBold, bool isItalic)
    {
        if (familyName.Equals("標楷體", StringComparison.OrdinalIgnoreCase))
        {
            return new FontResolverInfo(KaiFontKey);
        }

        // 如果之後要支援其他字型，可以註冊在這邊
        // 都找不到的時候就回去串內建的 PlatformFontResolver
        return PlatformFontResolver.ResolveTypeface(familyName, isBold, isItalic);
    }
}

接著在做浮水印之前做一個 GlobalFontSettings 的註冊和防呆，並且調整一下我們 XFont 的字型：

var watermarkContent = "測試_中文字浮水印_浮水浮水";

// 注意: 如果使用的字型是中文字，因為 PDFSharp 在 Core 的版本預設只支援部分英文字體（它沒法知道你用的平台都有啥字體）
// 中文字體之類的會要求自訂字體解析，因此要自行實作 FontResolver 並掛到 GlobalFontSettings
// see: https://docs.pdfsharp.net/link/font-resolving.html
if (GlobalFontSettings.FontResolver is null)
{
    GlobalFontSettings.FontResolver = new CustomFontResolver();
}

// 警告：這邊的 familyName（"標楷體"）必須和 FontResolver 的字體名稱一致，可以用 Const string 做一個強制關聯
var font = new XFont(
    familyName: "標楷體", 
    emSize: 25,
    style: XFontStyleEx.Regular,
    pdfOptions: new XPdfFontOptions(PdfFontEncoding.Unicode, PdfFontEmbedding.EmbedCompleteFontFile));
    
// 略......

這樣中文字就可以正常顯示囉～

替 PDF 加上檔案密碼

除了浮水印以外，PDF 加上密碼也是很常見的需求，這篇也一併紀錄一下。

在 PDFSharp 加上密碼還蠻簡單的，只需要調整 SecuritySettings 就好：

// 3. 加密 PDF 文件
// see: https://stackoverflow.com/questions/12383409/password-protecting-a-pdf-file
document.SecuritySettings.UserPassword = "123";
document.SecuritySettings.OwnerPassword = "123";

UserPassword 指的是開啟檔案時要輸入的密碼
OwnerPassword 則是列印、複製等操作時需要的密碼

但一般來說會習慣設成同一組，讓使用者可以進行完整的操作。

小結 & 碎碎念

和上一篇 DinkToPdf 搭配，完成了這次「產製 PDF，並加上浮水印和密碼」的功能需求。

雖然需求本身並不難，能使用的工具也很多，但前期準備的時候還是踩了一些坑。主要是舊專案採用的 iText 已經改為收費授權，不能無腦照抄移植。接著就有了在上一篇也碎碎念過的這段：

原本想說用團隊成員碰過的 PDFSharp 三兩下收工，搜了一下也發現了 PdfSharpCore，那就來個 PdfSharpCore + HtmlRendererCore.PdfSharp 經典組合。結果裝下來發現這兩顆的依賴項目 SixLabors.ImageSharp 1.0.4 直接跳一堆弱點，嚇到不敢用。

幸好 PdfSharp 本體已經直接支援 .Net 8 了，最終決定使用本家 PdfSharp 進行開發，然後用 DinkToPdf 替代掉停止維護的 HtmlRenderer.PdfSharp，兜了個馬車，筆記一篇。

參考資料

.Net: 善用 IServiceCollection Extension 和自製 Builder，讓服務註冊更有約束吧

Igouist (Igouist) — Sun, 29 Jun 2025 15:00:00 +0800

在之前的依賴注入文章的「組合根請稍作分類」小節，我們介紹過使用 IServiceCollection 的擴充方法來對要註冊的服務進行分類和管理的做法：

public static class ServiceCollectionExtensions
{
    /// <summary>
    /// 註冊 Nice Service
    /// </summary>
	public static IServiceCollection AddNiceServices(this IServiceCollection services)
	{
		services.AddScoped<INiceService, NiceService>();
        // ...一些相關的註冊

		return services;
	}
}

// Program.cs
builder.Services.AddNiceServices();

一直以來我都採用這個方法來簡單地拆分我的服務註冊，在大多數的場合已經足夠使用（尤其是只關注目前的專案時）。

但前幾天在看某個套件的實作時，開發的朋朋跟我分享了一些延伸的做法，感覺合理又常見，屬於有注意到就會記得的小技巧，決定馬上來記錄一篇筆記。

場景是這樣的：當我們在開發套件的時候，常常會有主要套件跟擴充用的延伸套件。

例如說，我可能會有一個主要的 NiceTool 套件，跟擴展前者的 NiceTool.Memory 套件

這兩個套件都會需要對 IServiceCollection 註冊一些服務，並且延伸套件 NiceTool.Memory 需要確認 NiceTool 的服務都有進行註冊才能正常運作。

如果我們想要先確保主要套件 NiceTool 的服務都註冊了，再處理 NiceTool.Memory，同時又想保留擴充組合的彈性給以後的 NiceTool.SqlServer，甚至我們可能想在兩者各自的註冊加點工、傳遞點資訊，可以怎麼辦呢？

這時候就可以考慮包一個自家的 Builder，用這個 Builder 來把這些套件給串起來。

以上面的例子來說，我可以製作一個 INiceToolBuilder，並且把服務註冊時要用到的 IServiceCollection 包在裡面：

public interface INiceToolBuilder
{
	IServiceCollection Services { get; }
}

public class NiceToolBuilder
{
    public IServiceCollection Services { get; }

	public NiceToolBuilder(IServiceCollection services)
    {
        Services = services;
    }
}

接著，在作為註冊起點的主要套件 NiceTool 裡，我就可以提供一個產生 INiceToolBuilder 的擴充方法：

public static INiceToolBuilder AddNiceTools(this IServiceCollection services)
{
	services.AddScoped<INiceService, NiceService>();
	// ...一些相關的註冊

	var builder = new NiceToolBuilder(services);
	return builder;
}

接著，在延伸的 NiceTool.Memory，我就可以接續著使用 INiceToolBuilder 來對 IServiceCollection 進行服務註冊：

public static INiceToolBuilder AddNiceMemoryTools(this INiceToolBuilder builder)
{
	// 對 INiceToolBuilder 帶進來的 IServiceCollection 繼續進行服務註冊
	builder.Services.AddScoped<INiceMemoryService, NiceMemoryService>();
	// ...一些相關的註冊

	return builder;
}

如此一來，我們就可以明示使用者在註冊的時候，先把主要套件提供的服務註冊方法呼叫完並取得 INiceToolBuilder，再進行延伸套件的服務註冊。如果有什麼資訊需要帶著一起走，也可以直接包在裡面就好。

在 Program.cs 也可以用我們熟悉的串串樂舒暢地一路串完，並讓使用者自行組合：

builder.Services
	.AddNiceServices()
	.AddNiceMemoryTools();

是不是看起來乾淨舒服，又方便有約束力呢。

為什麼會說這是「有注意到就會記得的小技巧」呢？因為這個做法其實還蠻常見的，尤其是各種套件和工具。

例如大家應該都很熟悉的 AddHealthChecks()，回傳的就是 IHealthChecksBuilder，後續就能接著去呼叫另一顆套件的 AddSqlServer()

又或者是我們 IOptions 文章介紹過的 AddOptions()，回傳的是 OptionsBuilder；
隔壁的 AddLogging() 提供傳入 ILoggingBuilder 的委派作為參數等等……

如果只是一路 Add() Use() Add() Use()，可能就不會注意到這個設計上的小巧思。

像我個人以前比較少做套件，大多時候都在服務內處理，習慣 IServiceCollection 幹到底，就不曾留心在這部份過。這次有朋朋跟我分享了這個眉角，馬上跟之前註冊各種套件工具時的記憶連了起來。

延伸想了一下，同樣的概念也不是只有套件開發的時候會用到，那不如記錄下來，以後才方便抄(?)

如此如此，這般這般，又成功靠偷朋朋的小技巧水了一篇，功德圓滿，阿彌陀佛。

Imgur 一直 temporarily over capacity 嗎？先檢查網路看看吧

Igouist (Igouist) — Sat, 14 Jun 2025 13:30:00 +0800

直接先講結論，給正在查這條錯誤訊息而來到這邊的朋朋參考：

先看 imgur status 確定 Imgur 服務有沒有正常

優先判斷是不是網路問題：如果有其他網路，更換網路試試看

如果開著 VPN，關掉再試試看；反之如果沒開 VPN，找一組跳去外國試看看

到這邊還是不行的話，代表你遇到的狀況跟我不一樣，就，祝你好運

“Imgur is temporarily over capacity” 這組錯誤訊息除了服務異常，也有可能是 IP 或地區被阻擋。目前（2025/06/14）在 PTT 和巴哈也有台灣 IP 被擋（官方未證實）的討論。
因此有遇到並且找到這篇文的朋友，請先從網路問題開始檢查，最好能用 VPN 之類的跳到國外驗證試試，祝順利。

前陣子寫文章要上傳圖片的時候一直無法上傳，覺得奇怪就去 Imgur 看了一下，結果登入按了啥反應也沒有，忘記密碼也沒反應。

開 F12 只看到 “Imgur is temporarily over capacity. Please try again later."，例如忘記密碼的回應：

{
    "data": {
        "error": "Imgur is temporarily over capacity. Please try again later."
    },
    "success": false,
    "status": 500
}

奇怪的是用手機的 Imgur 可以正常登入，但換成筆電仍然是不能登入。但既然錯誤訊息都說它們已經 over capacity 了，這點輕微的靈異現象應該也都是合理的（吧）

本來想說「那就等等唄，誰系統沒壞過」，秉持一份工程師不為難工程師的善心，大不了就等系統恢復再用就好

但幾天過去了，感覺事情越來越不對勁……

身為工程師，第一步當然是要確認服務到底有沒有活著。

翻了一下 imgur status 全都是綠燈，寄信給客服也沒有下落，決定認命上網查看看

結果爬了幾篇討論，突然發現這個「Imgur is temporarily over capacity」好像不是單純的「temporarily over capacity」：

從上面幾篇可以看到：有些人把 VPN 關閉後就可以正常訪問了，或是如果標 localhost 也會遇到同樣的錯誤。

再翻了幾篇之後，感覺許多人吃這組錯誤訊息的狀況是：IP 之類的被 Imgur Ban 了（不是，你不讓我進去，找藉口跟我說沒位置了，然後送我 500？）

下個問題就來了：俺尋思俺也沒開著 VPN 啊，更何況我 ~~偷懶這麼久~~ 近期也沒使用 Imgur，手機 APP 又登得進去，應該不是針對我的帳號做阻擋了。那到底是啥被擋了？

這時突然看到巴哈這篇 Imgur壞了? 無法上傳? 2025最佳替代圖床提到：

全球最大圖床之一的 Imgur 是許多網友的最熟悉放圖工具之一，大約從 2025 年 5 月 16 日上午開始，Imgur 開始針對台灣地區的 ip 進行封鎖，使用國外 ip 可以，原因尚未對外公開說明，截至今日仍處於無法上傳的情況……

看到這句決定開一下 VPN 跳外國試試看，結果

登入成功。

這次的找路過程就記錄到這邊。順便把上面的流程做個小整理，提供給同樣遇到 Imgur 經典錯誤 "Imgur is temporarily over capacity. Please try again later." 的朋友參考：

先看 imgur status 確定 Imgur 服務有沒有正常
優先判斷是不是網路問題：如果有其他網路，更換網路試試看
如果開著 VPN，關掉再試試看；反之如果沒開 VPN，找一組跳去外國試看看
到這邊還是不行的話，代表你遇到的狀況跟我不一樣，就，祝你好運

剩下的問題就是後續該怎麼辦了。

雖然目前開著 VPN 還是可以正常上傳圖片、繼續寫作，然而這次狀況來得突然，也開始對能不能長久使用這個平台有點疑慮……

稍微逛了一圈，有些人推薦了 meee、postimages 之類的圖床，也有些人跟我一樣選擇先繞過去。

其中感覺最可行的是這篇：Imgur 封鎖台灣 IP，我把圖床搬到 Cloudflare R2 - Code and Me

流量免費、可長期運作，而且最適合我原本 VSCode 打開就一鍵無腦上傳圖片的習慣。

但想到要搬圖片搞環境就好懶，開 VPN 只需要按一個鍵…（我們拖延症重度患者就是這樣的）

最後決定先把自家的圖片都爬一份下來再說，等哪個連假心情好再來處理吧，阿彌陀佛。

Windows: 關閉 OneDrive 同步，並把我的文件移回預設路徑

Igouist (Igouist) — Sat, 14 Jun 2025 09:30:00 +0800

最近因緣際會必須重灌電腦，安裝過程中忘記把 OneDrive 取消掉，結果進 Windows 才發現我的文件夾跑去 C:\Users\xxx\OneDrive\文件，差點昏過去囧

先不論我一堆遊戲存檔都在 Documents 資料夾裡，預設的 5GB 根本吃不下（硬吃還會導致信箱不能收信），一些自己寫的小腳本都已經把 C:\Users\xxx\Documents 當作「我的文件」的預設路徑了，實在不想為了 OneDrive 調整…

因此決定留一篇筆記，把「我的文件」從 C:\Users\xxx\OneDrive\文件 搬回 C:\Users\xxx\Documents，給下次重灌的我（對，我下次還是會忘記的），順便也給網路上遇到同樣問題的朋朋跟他們的 AI Search 參考。

備註：如果你是遇到 OneDrive 名稱自動帶了空格跟中文（例如 “OneDrive - 超棒公司”，像是微軟社區的這個問題）導致一堆路徑沒加引號的腳本炸掉，但又不打算關閉 OneDrive 同步功能的話，只需要用改名的方式來迴避就可以了。請參考更改 OneDrive 預設資料夾名稱

一、關閉資料夾同步

點開 OneDrive -> 右上角的齒輪 -> 設定 -> 同步與備份 -> 把文件之類的同步關一關

二、取消連結此電腦

到 OneDrive 的帳戶畫面，用力按下「取消連結此電腦」，告訴它「你不要再管我了！』

三、將「我的文件」丟回預設路徑

在檔案總管，對「文件」右鍵 -> 內容 -> 位置 -> 還原為預設值

這樣就移回去囉！一二三，One Drive 掰👋

參考資料

C#: 使用 DinkToPdf 把 HTML 轉成 PDF 吧

Igouist (Igouist) — Mon, 05 May 2025 22:00:00 +0800

最近做的一項需求是要把 HTML 轉換成 PDF，過程中決定使用 DinkToPdf 來處理這一段。

考慮到現在拿到的一些文件模板都是 HTML 檔了，感覺以後會蠻常碰到這個場景，決定來筆記一篇，給未來的我複製貼上。

環境準備

首先，當然是要先到 Nuget 安裝這篇的主角：DinkToPdf

由於 DinkToPdf 只負責包裝給 C# 這段，實際上要產出 PDF 還得用到 wkhtmltopdf 這個工具，因此還需要先弄到 wkhtmltopdf 的檔案。

不過作者也知道大家不是很想另外跑去找，所以 wkhtmltopdf 的組件檔案可以直接從 DinkToPdf 的 Repo 拿。但要記得要按照作業系統下載對應的 wkhtmltopdf 檔案：

Windows => libwkhtmltox.dll
Linux => libwkhtmltox.so
macOS => libwkhtmltox.dylib

~~但全部都載也不會有人阻止你就是了。~~

最後把 libwkhtmltox 放到專案的根目錄底下，DinkToPdf 就呼叫得到囉！
（問就是魔法，不服的自己去啃 P/Invoke）

libwkhtmltox 準備好之後，因為我的示範環境是 .Net 8 的 API，所以還需要註冊 DinkToPdf 的 IConverter 到 DI 框架上。

這邊額外說明一下，IConverter 其實有兩個版本的實作：

BasicConverter：最直接的簡易版本，會直接去呼叫 libwkhtmltox
SynchronizedConverter：有搞執行緒安全的版本，會讓任務排隊依序處理

但通常我們就直接參考官方給的範例無腦註冊 SynchronizedConverter 就行了：

services.AddSingleton<IConverter>(_ => new SynchronizedConverter(new PdfTools()));

這邊要特別提醒一點：DinkToPdf 的 IConverter 一定要註冊成單例！

即使今天不是使用 DI 框架來注入的話，也一定要把呼叫的 Converter 包裝成單例，否則會導致多個 Converter 去操作 libwkhtmltox 而發生錯誤。

如果在使用 DinkToPdf 的時候，發現產生的 PDF 會有「一次正常、一次跑版、一次正常、一次跑版」之類的靈異現象，通常就是沒有把 Converter 包成單例所造成的組件呼叫錯誤。

如果懶得找檔案搞單例什麼的，也可以像我一樣，直接找人家包好的工具爽爽用：

這邊我選擇直接開 Nuget 安裝 HtmlToPdfConverter，它已經把 wkhtmltopdf 組件包含在套件裡了，還封裝了一層。我們只需要在 DI 註冊時加上：

services.AddHtmlToPdfConverter();

它就會自己呼叫 RuntimeInformation.IsOSPlatform 來載入對應的 libwkhtmltox 組件檔案了。（有興趣的朋友也可以參考 HtmlToPdfConverter Repo 的寫法）

不管是選擇自己放組件，還是直接挖人家包好的。總之材料準備好之後，就可以開工啦！

實作紀錄

首先，假設我們有某組 HTML 內容：

private string GetHtmlContent()
{
    // 為了簡單示範，直接寫死一組字串
    var html =
    """
    <!DOCTYPE html>
    <html lang="zh-Hant">
    <head>
        <meta charset="UTF-8">
        <title>測試 DinkToPdf</title>
        <style>
            body {
                font-family: '標楷體', sans-serif;
                padding: 20px;
            }
            h1 {
                color: #333;
            }
        </style>
    </head>
    <body>
        <h1>Hello world！</h1>
        <p>我來，我見，我 PDF。</p>
    </body>
    </html>
    """;

    // 我們也有可能是從檔案讀的嘛，留這段方便我複製貼上
    // var path = @"C:\temp\test.html";
    // var html = File.ReadAllText(path, Encoding.UTF8);

    return html;
}

接著就是 DinkToPdf 上場的時候，首先我們需要宣告一組 HtmlToPdfDocument，並設置一些文件相關的特性。

我們這種最簡單的例子，直接設定 A4 直向給他就可以了：

var doc = new HtmlToPdfDocument()
{
    GlobalSettings = new GlobalSettings()
    {
        PaperSize = PaperKind.A4,
        Orientation = Orientation.Portrait,
    }
};

補充：可調整的項目請參考 GlobalSettings.cs 的欄位，像是一些彩色／黑白啦、文件大小跟方向等等都可以從這裡調整。

有了基本的文件之後，就可以直接把我們前面的 HTML 整坨塞進去：

doc.Objects.Add(new ObjectSettings()
{
	HtmlContent = html,
	WebSettings = { DefaultEncoding = "utf-8" },
	HeaderSettings = { FontName = "標楷體" }
});

都 OK 之後就可以把 IConverter 叫出來轉檔案囉：

// 為了方便示範直接 new 一個 SynchronizedConverter
// 實際使用時請從 DI 之類的地方取得單例物件重複用
var converter = new SynchronizedConverter(new PdfTools());
var pdfBytes = converter.Convert(doc);

最後就可以根據狀況，看是要存成檔案，還是要把 bytes[] 傳遞到下一站：

// 把前面產生的 PDF 儲存成檔案
// 如果要繼續對 PDF 進行加工的話（例如後續用 PDFSharp 接手）
// 也可以考慮傳遞上面的 pdfBytes 就好
var outputPath = @"C:\temp\output.pdf";
File.WriteAllBytes(outputPath, pdfBytes);
Console.WriteLine($"已產生 PDF：{outputPath}");

這樣就搞定啦，馬上打開來看看：

後話

如果像我一樣拿到 HTML 的樣板，最後要產製 PDF 的話，DinkToPdf 算是個不錯的小工具，尤其程式撰寫的部份蠻簡單的，相關設定丟一丟就可以直接轉換檔案了。

比起程式碼部份，反而環境設定的坑還比較多，如果沒乖乖丟組件檔案，又或是註冊的時候沒有好好做成單例，就會發生各種怪怪的事情（果然還是留一篇筆記給未來的我抄比較安全）

原本有考慮 PdfSharp 最常搭配的 HtmlRenderer.PdfSharp，但它已經停止維護；而看起來像是移植版本的 HtmlRendererCore.PdfSharp 光用 Linqpad 裝看看就跳出一排東西，實在不敢直接用：

最後繞了半圈，還是把 libwkhtmltox.dll 丟一丟、DinkToPdf 叫一叫最簡單方便，畢竟早點下班才是正義，阿彌陀佛。

參考資料

《真三國無雙：起源》白金心得

Igouist (Igouist) — Sun, 27 Apr 2025 20:00:00 +0800

前陣子成功把《真三國無雙：起源》給白金了，按照慣例趁休假來把遊玩紀錄整理成一篇心得吧！

補充：這篇是我個人遊玩《真三國無雙：起源》的心得。
如果你是在找《真三國無雙：起源》的白金獎盃攻略，推薦你這篇：
《真・三國無雙起源》全成就指南 - Steam 社群

作為一名從２代玩到現在的老玩家，對這次的起源蠻滿意的。

雖然一開始玩的時候，對於不能像系列作一樣操作各式各樣的無雙武將這點感到很可惜，但隨著遊戲推進，覺得操作一名主角跟這些武將互動、參與戰役也挺有意思的。

同樣是操作路人甲（？）闖蕩三國，原本還有點擔心會不會變得像《臥龍》，但《無雙》還是保留了很多自家的特色，兩者對戰場的詮釋完全不同，尤其是一騎當千、馳聘戰場的部份很讓人滿意。

既然「無雙」都已經能作為一種遊戲類型的代稱了，聊無雙就一定會聊到戰鬥，這也是我對本作最滿意的點：有做出大軍團相撞跟亂軍衝殺的感覺。

戰場體驗和地圖設計

這點我對張國洋大大發的推很有共鳴，尤其是「戰役裡樂趣跟緊張感的平衡」這一項。這一代主線戰役裡幾乎都有明確的目標、各種苦戰的友軍、刺激緊張的橋段。在虎牢關等戰役裡更有超讚的演出（最後轉角大軍衝鋒搭配敵軍投石的震撼感真的很棒），沉浸感給得滿滿滿，身為無雙粉真的會感動到。

敵兵的數量給得很大方，爽快割草的特色有確實保留下來。但同時戰場又有各種事件和突發劇情（例如呂布追著你們跑之類的），玩家不得不在緊張感下衝鋒陷陣，殺敵突破的熱血感在各場戰役做得很不錯。

此外這代的另一個特色就是軍團集結，例如虎牢關最終階段眾將會集結在關前進行衝鋒；又或是官渡戰曹軍會在袁紹本陣前會合等等。兩方軍團集結相殺，玩家在其中衝鋒陷陣，這種戰場感真的很爽快，這才是在亂軍之中衝殺該有的樣子。

▲ 向袁紹本陣衝鋒前的兩軍佈陣，紅色那團就是我們要割的草

提到戰場事件，就必須和地圖設計做配合，這部份我認為也做得很好。例如十常侍戰在殺入宮中之後利用密道逐步開放地圖，而這些密道又會在後續的刺殺董卓戰用到；又或是關羽千里行的關卡無縫銜接汝南之戰；下邳戰指示玩家從右側偷襲水庫，同時安排呂布在地圖左側襲殺我方製造時間壓力等等，感覺得到有針對戰役事件特別去設計地圖，值得好評。

劇情心得

聊完戰鬥體驗跟地圖設計之後，下一個讓我意外的讚賞點其實是劇情。雖然光榮慣例的人人洗白還是少不了，但以無雙系列來說已經算很不錯了。

這代劇情我印象較深的點有兩段，第一個是劉備終於不只是成天喊著仁義仁義的鬍子據點兵長了，走劉備線會感覺到他的大志、小心思、迷惘，還有妥協跟不甘，比起前幾代立體很多。身為季漢粉，蠻喜歡這一代的詮釋，但因為篇幅只到赤壁結束，劉氏集團能發揮的空間還是有點可惜。

第二個則是逆天改命的設計，更準確地來說是曹魏線的逆天改命。很喜歡曹魏路線根據典韋跟郭嘉的存活決定赤壁之戰走向的設計。尤其是赤壁戰對「若奉孝在不使孤至此」的郭嘉傳說處理方式，並不是在陣前預知這種把其他軍師當白痴的做法，而是讓郭嘉抱病退休再跟著主角親上戰場而發現，對我來說算蠻加分的。

不過其實曹魏線原本的路線就很不錯了，尤其是郭嘉病死的雪下飲酒過場足夠唯美。赤壁戰後對華容道的改編也很棒，各種阻攔的伏兵、留下禦敵的友軍，混亂的局部戰場，救援各路將軍之後面對孫劉的最後防線等等。

其中最棒的兩個關鍵點絕對是曹魏線最終的關羽戰跟張飛戰。在遊戲開場的時候會跟張飛對打作為遊戲教學，而在曹操路線的最後一戰，張飛會在單挑時聊起當初對練的記憶，感覺真的很觸動；而華容道全部清場之後跟曹操一起逃到路口，面對的則是無限覺醒狀態的關羽，一邊對決、一邊提起遊戲開場兩人一起結伴對抗官軍的回憶，這段場景真的做得很不錯。

▲ 華容道底跟曹老闆一起對戰覺醒關羽，本作我最愛的橋段。

前面提到逆天改命，這代三條逆天改命（也就是ＩＦ劇情）只有曹魏的比較有感，畢竟直接影響了赤壁戰的走向。相比之下孫吳線只有最終劇情有影響，而劉備線更是幾乎感覺不到差別，算是我覺得蠻可惜的地方。

但救下孫堅的時候還是有點小感動，救典韋跟郭嘉的時候也是如此。也許三國題材的其中一個浪漫就是救下原本會死去的人，像是龐統、孫策，然後想像他們會如何改變歷史吧。

所以，逆天改命條件還是一個不差全都打了，呵。其中幾個還算讓人蠻有記憶點的啦，例如長坂必須在逃跑路上轉身隻身對抗曹操大軍、對戰超級難打的幻影張角去救孫堅之類的。

聊完曹操線跟劉備線，可能有些朋友以為接下來要聊聊孫吳線了，但抱歉，沒有。雖然吳國線是唯一一條成功跟白鸞和好，甚至在某種形式上一起共鬥的路線，但我本身就不是很喜歡孫吳，更何況這代的吳國劇情前後互相矛盾的奇怪地方實在太多了，真要寫的話可能就變吐槽了，就輕輕放下吧。

好感度系統

無雙起源還有另外一個特色：主角直接被稱作東漢魅魔。而這個評價基本上完全沒錯，這代的好感度系統實在……非常微妙。

出場的所有武將，注意，是所有武將，都非常親近主角。不管這角色原本戒心多重、身世多慘，心態多扭曲，對主角就是不一樣。在我們主角紫鸞的魅力之下，連類情敵關係的呂布都把主角當成一名對手，搞弱肉強食的董卓都願意讓主角飛翔，實在是東漢友善大使第一人。

雖然武將劇情跟對話都有點尬，但這部份有關聯到戰場作一些對話，感覺還算是有點誠意。原本以為個人劇情跟戰場對話應該會很有撕裂感，但在第三章以後、各陣營互相戰鬥、開始要你站隊的場合（例如曹劉對立的徐州之戰），敵對武將都會透露出認識你但不得不戰的態度。

例如選擇劉備陣營，夏侯兄弟會勸你快逃；而選擇曹操陣營的話，關張趙都會帶著敬意和你一戰。尤其是張飛的「什麼都別說了沒關係，讓我們打一架吧」也太帥了吧（這傢伙果然是起源第一女主角吧？）

▲ 第三章會讓玩家選擇路線，路線會影響可攻略對象，果然本作是一款 Galgame

仔細想想，一些人物塑造的確只能從個人劇情推進。但也因為有個人劇情，這次的張角、董卓、袁紹這些前期人物都塑造的很鮮明，而且不是前幾代那種用各種搞笑標籤來刷第一印象的做法，而是藉由劇情跟戰役過程告訴你張角如何改革失敗、董卓又是怎樣信奉弱肉強食（但是把我跟本陣一起當棄子還是很哭），覺得還算是個不錯的方向。

零碎的小地方

不知不覺到這段的字數已經過兩千了，最後來聊聊一些零零碎碎的小地方。

首先就是遊戲的大地圖，一開始其實沒有很看好這種人物超大地圖超小，還要跑到下個城池或戰場的 PRG 跑法，但玩著發現也不錯。尤其是城池和村莊裡 NPC 的諧音梗跟碎碎念，而且隨著各劇本也會有不同的內容。

例如我一開始有跟袁紹交好，而在官渡之戰袁紹死後，如果路過鄴城會有對話提到「一個個都在曹操曹操的，都忘了袁紹大人了嗎？」就不禁有點感慨，光榮還是很擅長處理這種小地方。

▲ 小地圖路過城鎮會觸發ＮＰＣ台詞，路邊小兵都可以臭我們仲家帝，沒在客氣

除了地圖台詞以外，還有一個功能我懷疑根本是衝著老玩家來的，那就是可以使用前幾代的ＢＧＭ。害得我又跑去重聽了前幾代的行軍、逃亡劇、成都之戰等等，真是經典。

▲ 可以播放前幾代的ＢＧＭ，對老人非常友善的功能

本作除了主線以外還有許多小戰鬥，例如退治山賊、守守城之類的。而我在打完所有主線之後，就去把小戰鬥都給補一補。其中最後一項地圖任務「夢幻激鬥」，非常推薦把這場戰鬥留到最後，不愧是最終任務，曹孫劉三家聯合對上董卓、張角、袁紹，打起來非常熱血。最後擊殺所有人之後跟呂布單挑並勝利，感覺就是一個完美的句點。

除了小戰鬥以外，要拿白金還需要補完所有武將的情誼。這代的武將情誼有些都做得很不錯，尤其是貂蟬，在分別許久之後回到村子重逢的部分也很棒，差點讓我一度相信貂蟬才是本作女主角，可惜前面還有朱和跟張飛（？）

我最後一位交朋友的武將是張角。畢竟是第一章的 Boss，只能在拿到劇情回溯之後再回頭解，乾脆就放到最後跑了，在看到「真是好久不見』反而有種從最後回到最初的感覺。

▲ 最後達成的繫絆是最初的對手，很喜歡這種前後呼應的調子

《真三國無雙：起源》要達成白金並不算太困難，雖然有些對手很像是隔壁魂系跑來的（對，就是你呂布，為了拿赤兔不知道死了幾次），後期仍然有找錢幣、刷武器這類要農的要素，但需要重複操作的時長並不多。

戰鬥的爽快感跟戰場感都很棒，即使只玩戰鬥都沒有問題的程度。劇情有蠻多記憶點，能感覺到這一代不惜砍角重新設計人物的決心，雖然還有略顯粗糙跟不知所云的部份，但還算是處理得不錯了吧。

這一代畢竟只作到赤壁，雖然一度擔心是不是一款半成品，但起源的確讓我玩得很開心，反而覺得後面還有很多戰役可以做、很多武將可以回歸，漸漸就開始期待下一款作品了，也許這就是無雙重啟後的答卷吧。

《河狸浮生記》體驗版遊玩心得

Igouist (Igouist) — Thu, 24 Apr 2025 23:40:00 +0800

在 Steam 城市營造和殖民模擬節購入了這款河狸浮生記，玩了一兩輪覺得挺不錯的，反正這款遊戲還沒有成就系統，也不用像前幾款一樣等白金再整理，決定來順手紀錄一下心得。

河狸浮生記的主軸是在人類滅亡後的世界裡率領河狸們建造都市，是款偏小品休閒的城市營造遊戲，我個人玩得還蠻開心的，除了河狸蠻可愛的以外，這遊戲的可玩性也符合我對小品城市營造的要求。

在指揮河狸們建立都市的過程中，我們主要會面臨三個課題：資源管理、災難處理、城市規劃。

資源管理和大多城市營造遊戲相同，就是在不同階段會有不同的主要資源目標，在生產既有資源的同時，逐步疊加生產新資源的需求。因此需要一步步提升城市蒐集、處理和儲藏資源的能力，同時維持所有資源的生產量和儲藏量，讓城市能夠持續運行。

而在這款遊戲，因為是河狸當主角，建築大多依賴木頭來製作，初期就需要積極開採木頭拓荒，同時規劃種植樹木來產生長期、持續的木頭收入，畢竟木頭自由就是持續擴張的本錢。

開伐一定木頭、開始有基本的建築之後，就開始面臨河狸的生存需求，尤其是食物和飲水。這時候就需要採集並種植漿果和胡蘿蔔等食物來源，並在河岸邊採水儲存，才能保證河狸們能夠長期存活。

在前期階段，擴張跟存活就是我們的主要目標了，吃飽穿暖就是我們河狸村的夢想。

在第一輪遊戲中，我就大量建造住房、擴展城市，導致河狸數量增長過快，幾天之內就把好幾座倉庫的存糧吃光。但食物大多需要等待種植和收成，過程還會因為遊戲的突發事件中斷食物收入，因此直接陷入一個周轉不靈的斷頭狀態，河狸數量直接從兩百多隻餓死到剩下十幾隻，差點就因為馬爾薩斯陷阱而直接滅村了。

▲ 身為一個種田派玩家，從世紀帝國種到河狸村也是當然的

既然提到了遊戲的「突發事件」，順便就來聊聊災難處理的部份。在遊戲裡，一定週期會發生特殊事件，這些事件都會對村莊造成一定壓力。

例如乾旱會讓所有水源好幾天不出水，而因為農田等種植作物會需要灌溉（附近有水）的土地才能正常生長，缺水的狀況下作物會枯萎死亡；同時遊戲的主要動力來源是水車，因此水流中斷、又沒有靠風力和人力發電補上缺口的情況下，工業設施也會陷入停擺，可以想像成缺糧又缺電的狀況。

另一種災害則是惡水潮，是讓所有水源一定時間內只產生惡水。

惡水就是汙染水，在遊戲中很明確能看見紅色水流，基本上會導致作物汙染死去、河狸中毒等等（設定上是已滅亡的人類搞出來的，謝嚕），但惡水也是產生炸藥的重要資源，只能說有好有壞。

前面提到的乾旱只要利用建造水庫、調整河床增加村莊河流的蓄水能力等手段就可以處理。但惡水潮因為是原本產生清水的地方變成產生污染的惡水，因此原本流經村莊的救命河流直接變成毒死所有作物的毒水。

這時候，河流蓄水能力越好，越具有能抵抗乾旱的特性（河床較深、河道蜿蜒等等），惡水反而就留得越久。因此惡水潮的處理上比起乾旱更加麻煩，幾乎一定要用調整河道走向和閘門的方式來引流，確保災害時期的水流能確實轉向，遠離我們的村莊，否則只能等著惡水退去之後摘除受汙染的作物，直接認賠。

就跟避免缺人所以收一堆人，而且還沒有淘汰機制的某些公司一樣，咳咳咳。

▲ 惡水潮讓水源變成受到汙染的紅色惡水，必須建立水壩阻擋並引流

以上災害雖然在前期發展階段時都會帶來痛苦和打擊，但確實提升的遊戲的可玩性，讓玩家會為了保護河狸、處理災害而調整村莊的設計，提高村莊的強韌程度。

到了中盤，確保擴張跟生存能力，也能稍微撐過災害時期之後，就會逐漸進入重構優化時期。

因為衣食無缺、有吃有住之後，差不多也有建造水壩、炸藥的餘裕了，這階段就可以開始嘗試改變水流方向、設計河流跟水的走向，像是下挖河床的深度，或是建造水庫來留住更多水資源，讓城市能安穩度過突發事件的缺水時期。

如果更有餘裕的話，也可以開始發展娛樂、裝飾品，一些進階的餐點，藉此提升河狸的心情指數了（不過我走一個鐵腕路線，放幾張醫療床給河狸躺已經很好，下班還有舞廳可以跳個舞就差不多了）

這階段我主要都在玩遊戲的動能系統，可以想像成拉電線遊戲。遊戲的工廠型建築需要動能，而動能需要產生跟運輸，像是利用水車和風車產生動能，再使用管道運輸動能提供給工廠。

前期容易在城市中心就近放個工廠處理木板，先求一個能動就好。但隨著城鎮擴張，這些散落的動能建築就會漸漸變成「技術債」，不方便繼續加蓋或串接其他建築來規劃新的生產路線，這時候就不得不重新設計、調整動能運輸的建築和路線，做出發電區、工廠區等等，來讓木板、紙張等進階資源的製作工廠漸漸規模化。

這段時間更多是在調整和修正初期的城市規劃，在村莊裡劃設儲藏區、住宅區、工業區、各種道路等等，想辦法藉由各種調整和重新設計來讓整個城市運作的效率往上提升。

並且因為遊戲中的部份建築是可以疊的，例如民房上面可以疊民房，倉庫上面可以疊倉庫，因此路線規劃（尤其是樓梯）就會相對重要。如果初期建設做得很平面、有個空地就丟棟建築，而沒有先做簡單的分區規劃的話，中期建設就會花更多時間在重新設計建築和動線。

▲ 遊戲的建築可以疊放，但我這個人實在沒什麼創意，所以河狸看起來都像住在貨櫃屋

更新：五月的更新追加了空中纜車和建築上面能疊放地形，立體建築能玩的地方又更多了，舒服

到這個階段，災害事件基本上都有應變方式了，村莊也優化跟擴張得差不多，遊戲也進入放置時期，漸漸會考慮開下一把來玩了。

聊完了一兩輪遊戲心得，接著就紀錄一些小缺點吧，首先就是前面提到的災害事件。目前的災害事件只有兩種：乾旱跟惡水潮，中盤把水流處理好之後，節奏就變得有點單調。

出事我就開關閘門、操作一下水流，沒事就歌舞昇平（這篇心得也是一邊看著河狸們游泳一邊寫的），漸漸變得只剩作業感了。還是希望之後能加入更多種類的災害跟發生頻率，不然跟我上班看到告警就按著 SOP 做事有什麼兩樣囧

另外一項是我個人感覺小品城市建造都會有的：遊戲中後期左右，新村莊都擴得差不多之後，就不再有大型目標了，基本上就是局部優化，像是調整水流、疊建築、搞電線這些細節處理。

如果沒有什麼特別要解決的問題，就會顯得無聊，遊戲和工作都是這樣。到了這階段不如新開一把。可能這就跟新創賭徒發現公司擴張停滯後就想開新公司一樣吧（？）

不過遊戲中提供的兩種河狸部落各有特色（以木頭為主的河狸，跟以鍛鐵為主的，呃，還是河狸）搭配地形還是有一定可玩性。但可惜我是個體驗俠，都摸過一輪就該玩下一款等更新囉，畢竟收藏庫還這麼多款在排，也不是每款遊戲都能像 Rimworld 能掛著當柬埔寨模擬器跟八點檔產生器嘛。

考慮到這遊戲還在搶先體驗版階段，還是期待以後的發展啦。至少不要像之前玩過的某幾款直接死掉就可以了（對，就是你《石爐》。明明自訂建築這個點很棒呀！）

只能說，河狸們，願您的國長治久安。我就坐等正式推出吧。

更新：河狸浮生記將在 2026/3 推出 1.0 版本，已經準備好來趟木頭龐克之旅了🪵

最後聊點題外話：玩這類城市營建遊戲的時候，常有種跟程式開發等既有概念串起來的感覺？

例如前面提到的城市規劃：初期沒有做分區，建築又亂疊，中期就要花更多時間規劃和重建……

又或者是「擴張、生存、彈性」的產品節奏：先蒐集資源、積極擴張、想辦法活下來，基本需求都穩定之後，就開始著手進行優化，提升整體效率和面對突發狀況時的容錯率等等……

感覺很多地方可以關聯起來，不過也有可能是我比較常想東想西就是了。

畢竟我玩 Shadow Tactics 系列也覺得「哦這跟解題和修 Bug 好像」，玩 4X（探索、擴張、開發、征服）也覺得「哦這跟學習程式技能好像」，也許它們都只是剛好符合我的某些思考框架而已吧？

大概這樣，原本只是想說寫點東西，結果比預期的還要多。難怪老前輩的簽名檔是「寫文紓壓」，可能真有幾分道理。那麼，我們下篇見～

JMeter: 使用 Constant Throughput Timer 設置固定吞吐量

Igouist (Igouist) — Sat, 01 Feb 2025 08:15:00 +0800

我們在之前 JMeter 的筆記時，介紹過直接對服務爆打一波的作法：簡單來說就是打好幾輪看看服務撐不撐得住，然後紀錄能吃的最大數量，可以說是非常暴力的做法。

但如果我們想要模擬某個固定數值的請求量（例如每分鐘 100 次請求）、又或是需要用固定速率打出去（例如每 5 秒得敲一下），就不能像上次一樣粗暴地全力出擊了。

這時候，我們就可以用 JMeter 提供的 Constant Throughput Timer（固定吞吐量計時器）來限制呼叫頻率，馬上來筆記一篇。

以下範例會使用到 JMeter 的 HTTP Request 等功能，還不太瞭解的朋友推薦先閱讀上一篇筆記：使用 JMeter 來對 API 壓力測試吧

先確認一下環境：我們有一組腳本，內容只是簡單地戳一下 API

現在我們希望可以模擬線上使用者在尖峰時段的使用頻率，並確認我們服務挺得過去，所以需要把這組腳本調整成：「每分鐘戳 20 次，持續五分鐘」

補充：有時候我們收到的需求會是「持續五分鐘，然後總量為 100」這種，意思是差不多的，反正先確認好 「每分鐘的數量 x 持續幾分鐘 = 總量」 這幾個關鍵數字再說嚕。

首先讓我們加入一組 Constant Throughput Timer：

並且找到 Constant Throughput Timer 裡面的 Target Throughput（每分鐘呼叫次數），我們這次的需求是每分鐘要戳他個 20 次，這邊就直接放 20.0：

圖片可以看到還有另一個選項「Calculate Throughput based on」，這個我們晚點再介紹，先維持在「this thread only」

接著回到 Thread Group，因為我們這次的場景是用時間來計算的，所以需要把底下的 Specify Thread Lifetime 打開，並根據要執行的時間來填上秒數。

因為我們的需求是跑 5 分鐘，所以先丟個 300 秒：

而且我們這次是用執行時間計算數量的，不希望 Loop Count 影響到我們，直接甩個 Infinite 給他（對，我們就是模擬有個使用者坐在那邊無聊一直按按鈕，而且他節奏感還很好）

執行之後就可以確認總量跟每分鐘的吞吐量有沒有符合我們的設置囉：

很好！現在我們已經會使用 Constant Throughput Timer 來控制壓力測試時的吞吐量了。

有興趣的朋友可以回去調整各個參數觀察看看，也可以改個 Thread Group 的 Thread 數量看看結果差異，例如當我把上面範例的 Thread 改成 2：

可以看見數量跟吞吐量都有影響（算總數寫報告的時候記得別算錯了 xD）

接著讓我們認識一下 Constant Throughput Timer 裡面的 Calculate Throughput based on

有時候我們只在乎每分鐘要打多少筆，不是很在乎每個 Threads 實際分配的量（或是不想算數學），這時候就可以調整 Constant Throughput Timer 的模式

像是把模式改成「All Active Threads」，就能直接訂最終數字（例如每分鐘就是要打到 2000 筆），剩下就讓 JMeter 自己去分配，可說是懶人好幫手

Constant Throughput Timer 的 Calculate Throughput based on 總共有五個選項：

模式	說明
This Thread Only	每個 Thread 各自獨立設定目標吞吐量例如設定 20/min、開 5 個 Thread → 實際總量 100/min
All Active Threads	目標吞吐量由所有 Thread Group 的所有 Thread 共同分攤例如設定 20/min、開 5 個 Thread → 每 Thread 各約 4/min，總量仍是 20/min
All Active Threads in Current Thread Group	同上，但只抓當前 Thread Group 的 Thread 來分攤
All Active Threads (Shared)	和 All Active Threads 一樣意思，但所有 Thread 共用同一個計時器，請求分配會更均勻
All Active Threadss in Current Thread Group (Shared)	基本上就是上面兩個加起來：當前 Thread Group 的所有 Thread 共用同一個計時器

可以再根據壓測的場景決定要選擇哪一個模式，供參考。

最後整理一下 Constant Throughput Timer 的適用場景，有以下狀況的時候就可以考慮使用：

模擬某個固定數值的請求量（例如每分鐘Ｘ次）
需要穩定地以固定速率發送請求（不能一開頭就重拳出擊）
老闆說：「我們這個測試不能更貼近真實使用者一點嗎？」

各位朋友可以再動手玩玩看。我們下次見～

參考資料

還有最實際的：

WakaTime: 隱藏敏感資訊、開啟離線暫存、卡在 Initialized 時的參考解法

Igouist (Igouist) — Sun, 12 Jan 2025 00:00:00 +0800

WakaTime 是一款紀錄 Coding 時間的好用工具，只要安裝 IDE 的擴充套件，就可以輕鬆地記錄各個語言、編輯器、專案所用的時間。我從 2020 年寫了篇 WakaTime 介紹文章開始，也一路用到現在 2025 了，已經習慣動不動上去看兩眼的生活。

但在相對封閉的一些環境進行開發時，我們可能需要先對 WakaTime 調整一些設定才能用得安心，這篇筆記就分享一下最近遇到的三個場景，供有興趣的朋友參考參考。

章節目錄

在 WakaTime 隱藏敏感資訊（檔案名稱、專案名稱…）

Wakatime 除了會記錄使用的程式語言和 IDE 等工具以外，也會紀錄專案、檔案路徑等等。但有時候我們可能並不希望記錄這些資訊（像是業主委託的專案名稱有點敏感啦、路徑可能有個人姓名之類的），這時就需要調整 Wakatime 的 Config，來把相關的資訊隱藏起來。

Wakatime 的設定會放在 .wakatime.cfg
（Windows 預設會在 C:\Users\{User}\ 或 C:\Users\{User}\.wakatime）

開啟之後就會看見自己的 API Key 等設定，像這樣：

[settings]
api_key = ***

能在 .wakatime.cfg 調整的設定值可以參考官方文檔：USAGE.md

因為這次我們的目標是隱藏資訊，所以會用到的主要是 Hide 四兄弟：

hide_file_names：隱藏檔案名稱
hide_branch_names：隱藏分支名稱
hide_project_names：隱藏專案名稱
hide_project_folder：隱藏專案資料夾

全打開的話會像這樣：

[settings]
api_key = ***
hide_file_names = true
hide_branch_names = true
hide_project_names = true
hide_project_folder = true

接下來讓我們簡單認識一下它們。

開啟 hide_file_names（隱藏檔案名稱）之後，檔案名稱就不會傳送上去。

在 WakaTime 看見的會是 HIDDEN：

補充：因為檔案名稱變成 HIDDEN 了，所以如果原本有用自訂規則來偵測副檔名之類的做法（像 .linq => C#）就會吃不到囉。如果有使用 Custom rules 的朋友請再注意一下。

開啟 hide_project_names（隱藏專案名稱）之後，則會幫你的專案取一個新名字。這個名字會在專案資料夾底下建一個 .wakatime-project 的檔案並存放在裡面。

在 WakaTime 看見的就會是這組專案名稱囉：

最後這組 hide_project_folder 則是會隱藏完整路徑。

原本的路徑像是這樣的話：/User/me/projects/bar/src/file.ts
就會變成這樣：src/file.ts

如果路徑上有個人資訊的時候，像是 C:\Users\{User}\...\file.ts 的話，就很適合把 hide_project_folder 打開。

除了上面四個 hide 兄弟以外，另一個隱藏資訊常用的設定是 hostname。

推薦在電腦名稱需要隱藏的時候使用，例如：

[settings]
hostname = nice_machine

在 WakaTime 就可以看見自訂的機器名稱囉：

開啟 WakaTime 離線暫存（Offline）

除了隱藏專案相關的敏感資訊以外，有時候我們也會到一些暫時無法聯網的地方工作。

這時候像 Git 這種可以離線工作、連線再上傳的工具就非常方便。

而 WakaTime 同樣也有 Offline 模式，開啟之後即使是離線的，也會把相關的紀錄暫存起來，等到有網路的時候再上傳。

要開啟的話，同樣要先到上面提到的 .wakatime.cfg，加上：

offline = true

這樣當我們沒有接上網路的時候，WakaTime 就會顯示離線模式：

離線模式時，會將資料暫存在 .wakatime/offline_heartbeats.bdb，等待重新連線後再上傳

這樣就可以安心繼續 Coding 囉～

如果想手動上傳的話，也可以找到 .wakatime/ 底下的 Wakatime CLI，直接呼叫上傳離線資料的指令

以我在 Windows 64 位元的工作機為例，應該會找到 wakatime-cli-windows-amd64.exe

接著就可以使用 --sync-offline-activity 來同步資料：

# 確認待上傳的離線資料筆數
.\wakatime-cli-windows-amd64.exe --offline-count

# 上傳離線資料
.\wakatime-cli-windows-amd64.exe --sync-offline-activity 9999

WakaTime 卡在初始化（initialized）？試試下載 WakaTime-CLI

這次還有遇到一個怪怪的狀況：WakaTime 的狀態一直卡在初始化（initialized）

折磨半天之後，終於找到了問題：我的開發環境連不到 Github，而 WakaTime 會嘗試上去 Github 更新 WakaTime CLI，於是就卡住了。

這時候可以嘗試手動下載 WakaTime CLI 來解決。首先到 github/wakaTime-cli - Release，根據作業系統下載對應的壓縮檔（我用另一台電腦上去拉的）

解壓縮之後會得到 wakatime-cli-{os}-{version}.exe，以我在 Windows 64 位元的工作機為例，就會是 wakatime-cli-windows-amd64.exe

把這個 exe 手動丟到 .wakatime 資料夾裡，就可以重開 IDE 觀察看看有沒有疏通囉～

備註：因為初始化的步驟不僅這項，也可能還有其他原因導致卡住
如果有用其他解法成功打通的朋友也歡迎分享～

參考資料

菜雞出門玩：2024 韓國釜山

Igouist (Igouist) — Fri, 22 Nov 2024 19:00:00 +0800

今年難得有機會出國逛逛（雖然是蹭女友公司的員工旅遊，謝謝隔壁老闆！），想說 2024 也要結束了，決定趁著放長假的時候來整理一下。

因為是第一次嘗試發旅遊文，打算順著路上景點丟丟照片、簡單寫一下心得就好。如果之後有繼續發同系列的文章再來慢慢微調吧。~~說不定就趁勢轉型成旅遊美食部落格了呢~~

這篇主要會分成三個部份：行前準備、景點紀錄、個人心得。那麼就開始囉！

▲ 海東龍宮寺的燈，放這張當封面只是因為我喜歡。

章節目錄

行前準備

這趟除了出門必須的整頓行李和旅平險以外，還另外買了有交通卡和換匯功能的 WOWPass、提供手機網路的 SKT eSIM，這兩個在 KKday 購買的話可以選擇直接在機場取貨。

但我們交通卡跟 eSIM 取貨的航廈選錯，導致我們要在桃園機場兩個航廈之間來回跑囧，如果有一樣蠢的朋友，提醒一下桃園機場有接駁電車可以往來第一航廈跟第二航廈…

此外要特別注意的應該是地圖 APP 了。

由於韓國的法規限制（主要是因為跟北韓的尷尬狀況），較精密的地理資訊只能放在國內的伺服器。這也導致 Google Map 在韓國……不是那麼好用。

因此要前往韓國之前，通常會在 Naver Map 和 Kakao Map 裡面選一個用

我們這趟用的是 Naver Map，主要是因為 APP 裡至少還有簡中能選。
~~我們這些英文不好的孩子是這樣的~~

延伸閱讀：為什麼 Google Maps 在韓國不行用？有什麼替代方案？ - ExitTaiwan

景點紀錄

接下來就是這幾天去的景點了。~~終於可以開始曬照片了~~

密陽豬肉湯飯

下飛機後第一餐是豬肉湯飯，湯送上來的時候還在滾，對怕燙的朋友不太友善

湯頭還不錯，但味道比想像的還清，主要靠旁邊的調味料（蝦米）自行調味

在韓國用餐真的是必備各式小菜，從這餐開始的每一餐都有小菜，是真的每一餐，完全想不起來有哪頓飯是沒有泡菜吃的，很切實地感受到他們對小菜的熱愛。

另外還得到了來自導遊的重要情報(?)：在韓國，菜單上東西越少的店就越好吃，其他那些菜單列一大堆的店都是來騙觀光客的。真實性有待商榷，但值得參考 XD

後來回台灣之後發現常看的 YT 在家做生魚片
也來過這家豬肉湯飯，有興趣的朋友也可以參考影片（約 0:59 處）：

富平罐頭市場

接著前往罐頭市場，據說是因為韓戰時期在這裡進行了大量軍用品（尤其是罐頭）的交易而得名。（富平市場(罐頭市場) - 韓國觀光公社）

我們抵達的時候已經有點晚了，基本上只有十字路上的攤販。挑了一攤酥炸豬排，味道意外地不錯，口感也紮實。

另外在導遊的鼓吹下還買了韓國香瓜。但實在沒什麼味道，就…脆脆的，我個人還是比較喜歡台灣的水果啦，甜的好。

延伸閱讀：韓國香瓜 참외 要這樣吃才道地 - 韓國x愛夢瑞絲

▲ 西瓜汁，要 12000 韓元（約 300 新台幣），讓我確實認識到在國外買東西一定要先問價格

青沙浦（膠囊列車、天空步道）

隔天是一些觀光行程，但可能我比較貪吃，對這部份的行程相對無感一點。總感覺天空步道只是凸出去海上的平台、膠囊列車就是看海曬太陽的小包廂。

但管他呢，辦公室關久了，看看海心情也很不錯。

▲ 膠囊列車中間的桌子感覺很適合放筆電，光照也充足，抬頭還能看海，很適合加班。

購物商場、沙灘

大家在瞎拼的時候我們這組在忙著買零食。好ㄘ。

有個印象蠻深的小地方是：韓國商場裡各店家的門口都會有個飲料架，讓遊客可以先把飲料放著再入店。在台灣似乎沒看過，但我個人是不太敢放（查了一下還真的有相關新聞）

另外，可能因為美妝盛行，在試戴帽子會提供衛生紙來墊額頭。雖然都是百貨商場，但發現這些小地方的差異也蠻有趣的。

買完之後的行程是沙灘散步，城市緊接著沙灘的感覺還蠻不錯，辦公大樓和大馬路旁邊就是沙灘和街頭藝人，也沒什麼衝突感。傍晚時活動的人數也比想像中多很多，到處都是跑步遛狗的人類。

▲ 我們前往時剛好是沙灘季前幾天，有沙雕，運氣不錯。

甘川洞

在山坡上的彩繪村。劇說是韓戰時期由難民組成的村莊，現在感覺是遊客眾多的拍照聖地。

有小王子的雕塑，也有韓服租借的服務，但排隊的人都超級多。另外還有非常多、非常多的咖啡廳及紀念品店。身為喜歡小廢物的朋友，買得還算開心。

延伸閱讀：甘川洞文化村 감천문화마을：告別悲情，重獲新生的釜山繽紛山城 - 艸頭黃這一家

▲ 無法排隊的老人，在咖啡廳悠閒地等待集合時間。

南浦洞

南浦洞給我的感覺……有點像西門町或新堀江？我們這趟主要是在 BIFF 廣場附近閒逛，這區域是由一堆攤販組成的觀光街，附近還有美妝店，逛起來特別有熟悉感。

可以參考街景圖會更有感：

吃了幾攤，比較特別的應該是糖餅，吃起來像是甜的燒餅裡面塞堅果，還算不錯。

另外還去吃了道地的炸醬麵，結果發現我更喜歡台式的韓國炸醬麵，雖然洋蔥跟醬是蠻順口的啦，但跟想像的不太一樣。反而糖醋肉吃起來挺不錯的，肉咬起來也是挺緊實緊實。

▲ 糖醋肉，還有形狀相當微妙的醬料。

李夏亭醬蟹

醬蟹是少數在出發前就決定好的目標，自由活動的當天馬上直衝李夏亭醬蟹。

點餐的時候充滿了既期待又怕受傷害的心情，在用餐之前還先吃了胃藥以防萬一。

吃的時候要先把飯挖到蟹殼裡，跟膏和醬攪著吃，接著把蟹肉擠到飯上面，搭配海苔一起吃。

只能說「恐怖但好吃」，一拿起來就有一股神祕的蟹味，難怪有人說會腥、也有人說這是鮮味。但是的確蠻好吃的，非常蟹，需要克服。

如果能夠吃生蝦之類的朋友可以嘗試看看，但如果對生食有所抗拒的還是先不要。我個人之後來韓國可能還會再吃吧，畢竟我喜歡吃螃蟹，而醬蟹真的很蟹。

延伸閱讀：釜山美食李河榮醬油螃蟹！來韓國必吃，蟹肉蟹黃伴飯真的凍未條

▲ 醬蟹被吃掉之前的最後合影

海東龍宮寺

自由活動的另一個景點選了海東龍宮寺，入寺要先走過十二生肖的雕塑、一個小隧道和石階，就能看見海岸邊的海東龍宮寺。

寺廟裡面有蠻多景色，建築的用色比想像中鮮豔一點，到處都能看見藍綠色。除了大雄寶殿本體以外，還有可以看見整個寺廟的岩灘（祭龍檀）、在地下室裡傳說有療效的泉水（當然現在不給喝了），以及景色很好的咖啡廳（想喝咖啡嗎？先看一下評價）

除了很有韻味的建築以外，寺內幾乎都能看見廣闊的大海。讓人覺得「在這種地方修煉會不會太舒服」(?)

▲ 大雄寶殿，藍綠色的裝飾蠻好看的，遊客人數也意外地多。

▲ 許願池，要把銅板丟到碗裡。但應該對台灣遊客不是問題，畢竟都在夜市套圈圈訓練過了

老奶奶伽倻小麥冷麵

自由活動日的最後一頓，決定探訪網路上找到、位於南浦洞巷子裡的伽倻小麥冷麵

上頭的醬汁拌勻調味，再用剪刀把麵剪斷，就可以開始享受Ｑ彈的麵。
吃的時候會附一壺像是茶的飲料，喝起來像是湯。不太確定是個啥，但蠻好喝的

▲ 冷麵本麵，哇金尬意，咻嚕嚕嚕

▲ 另外點的蒸餃，不錯吃，因為餡很飽滿，好像很上相，所以決定也放張照片上來

小結

這趟旅遊是五月多出發的，隔了半年才想說「既然 2024 都要結束了，那來記錄一篇這趟出國走過的景點吧」，所以大多時間都在看照片回憶當時的狀況。

當然也省略了一些沒待很久的快閃景點，例如可以看見對馬島的白淺灘、有烏龜故事的松島等等（還有跟團一定有的推銷購物環節也省略了）

除了到處吃吃喝喝以外，最大的體悟其實是英文還蠻重要的。身為一個多益 300 左右、程式碼命名還要先查單字的菜雞工程師，到了國外差點連咖啡都買不了 QQ

但長這麼老了難得出國一次，真的蠻新奇的，也吃了不少新東西（畢竟到處找食物吃就是我的人生志業），突然對以後的旅遊多了蠻多興趣，因此也就開了這篇。

希望來年還有機會再寫一篇吧。那麼，我們下次見～

VSCode: 使用 LiveShare 來即時線上協作吧

Igouist (Igouist) — Sun, 01 Sep 2024 15:00:00 +0800

在 VSCode 躺了一段時間的 LiveShare 終於派上了用場，這邊就簡單記錄一篇，方便以後推坑的時候用。

當時的情況是這樣的：在風和日麗的某個下午，我和女友去客美多（Komeda）喝超讚的蜂蜜冰咖啡，順便 ~~看著她加班~~ 悠閒地 Coding。

但麻煩的是，我們倆的座位是面對面的兩人座。所以當我們要邊看程式碼邊溝通時，得先把筆電轉 180 度，或是起身走到另一側，非常不方便

就在來回走了幾趟 ~~漸漸不耐煩~~ 之後，突然想起了香香的 LiveShare

LiveShare 可以讓我們在 VSCode 裡即時線上協作，一起編輯同一份程式碼。
並且也能看見對方游標的動作、在文件上留言互動等等

當我們正在 WFH，或是像這種懶得走過去(?)，但又想要和朋朋們來場 Pair 的時候，LiveShare 就可以派上用場了！

備註：Visual Studio 應該已經內建 LiveShare，
可以從「檔案 > 開始 Live Share 工作階段」來開啟

而 Jetbrains 的朋朋，
請左轉使用 Code with me，同樣也能線上開嚕

馬上來介紹一下安裝和基本的使用方式吧。

首先第一步當然是先安裝擴充套件：

安裝完畢之後，在左下角應該就能看到 Live Share 的圖示：

點擊之後就會開始分享囉，也會很貼心地幫你複製邀請連結：

如果想再複製一次邀請連結，或是想要停止分享，就再戳一次左下角的 Live Share 圖示就可以了：

受邀者加入就可以開始線上協作囉！

過程中可以看見對方游標所在的位置：

同時在右上角也會有一些功能可以使用，例如追隨對方的視角，還有直接把對方畫面拉過來的大聲公：

除此之外，如果不方便通話，也可以留言討論（但大多時候還是邊通話邊改比較方便啦）

基本上有這些功能就可以搞定大部份 Pair 的場景了，有興趣的朋朋也可以試玩看看，
線上協作，簡單方便，阿彌陀佛。

那麼，今天的分享就到這邊。又成功水了一篇，下篇文章見～

使用 AddTypeMap 調整型別映射，讓 Dapper 乖乖寫入 0001-01-01 到 datetime2

Igouist (Igouist) — Sun, 25 Aug 2024 15:20:00 +0800

這週忙著打黑悟空，簡單記一下前陣子同事遇到的一個場景：

由於曆法的關係，SQL Server 的 datetime 範圍只能從 1753-01-01 開始。
如果我們要寫入 0001-01-01 進去的話就會報錯

SqlDateTime overflow. Must be between 1/1/1753 12:00:00 AM and 12/31/9999 11:59:59 PM.

補充：關於曆法的部份，有興趣的朋友可以參考這篇：
淺談：消失的日期，以關聯式資料庫的日期資料類型為例 - 德瑞克：SQL Server 學習筆記

這時候通常去把資料表欄位改成香香的 datetime2 就可以搞定，爽爽寫入 0001-01-01。

但如果我們正在使用 Dapper，預設會把 C# 的 DateTime 映射到 SQL Server 的 datetime，所以還是會寫入失敗。

這時候我們就需要明確地請 Dapper 幫我們使用 datetime2 來進行處理。

如果傳遞的只是某個參數，使用 DbType 就行了：

var parameters = new DynamicParameters();
parameters.Add("@Birthday", birthday, DbType.DateTime2);

但如果傳遞的是某個 Model 裡的特定欄位呢？例如：

public class HistoricalEvent
{
    public Guid EventId { get; set; }       // 歷史事件的唯一識別碼
    public string Description { get; set; } // 歷史事件的描述
    public DateTime EventDate { get; set; } // 歷史事件發生的日期, 可能早於 1753 年！
}

這種時候就可以使用 AddTypeMap 來調整一下 Dapper 的映射型別。

首先確認 DB 的欄位已經修改為 datetime2，接著我們就可以使用 SqlMapper.AddTypeMap 來幫 Dapper 加上一些小小的型別轉換：

// 粗暴地添加 TypeMap，讓 Dapper 知道 DateTime 現在對應到 DB 的 datetime2 了
// 等等 Dapper 才會乖乖地把 0001/1/1 寫進去= =
SqlMapper.AddTypeMap(typeof(DateTime), System.Data.DbType.DateTime2);

// 示範用資料
var historicalEvent = new HistoricalEvent
{
    EventId = Guid.NewGuid(),
    Description = "公曆紀元開始",
    EventDate = DateTime.Parse("0001-01-01")
};

var sql = 
@"
    insert into HistoricalEvents (
        EventId, 
        Description, 
        EventDate)
    values(
        @EventId, 
        @Description, 
        @EventDate); 
";

using (var conn = this.Connection)
{
    var result = await conn.ExecuteAsync(sql, historicalEvent);
    result.Dump();
}

備註：因為我們改的是靜態方法裡的全域設定，所以確定要調整型別映射的話，可以把 AddTypeMap 移動到註冊的地方，例如 Program。

方便後續維護的時候好管理，也避免其他同事不知道你偷改，減少被扁的醫療費用。

此外，雖然微軟把拔也建議改用 dateTime2，但如果你會想先了解這兩者的不同（例如精度）再進行處理，可以參考以下的文章：

DateTime vs DateTime2 in Sql Server

Datetime VS Datetime2 | by RiCo 技術農場 | RiCosNote | Medium

大多數時候，我們不太需要寫入 0001-01-01，甚至 1753 年之前的日期
（像是日期尚未決定之類的場合，用 Null 表示會貼切）

但夜路走多了，總會遇到 0001-01-01。像是處理古老的遺留代碼、業務邏輯必須區分「還沒設定」和「沒有資料」的狀況，又或是像上面的例子，西元的開始真的就在那一天，這種時候就沒辦法了。

因此順手筆記下來，以後再回來抄，阿彌陀佛。

參考資料

.Net: 使用 FeatureManagement 套件來實作功能切換（Feature Toggle）吧

Igouist (Igouist) — Sun, 18 Aug 2024 13:00:00 +0800

在做上一篇 IOptions 的筆記時，剛好看到 FeatureManagement 這香東西。
馬上來收錄一篇。順便也簡單整理一下 Feature Flag (≒Feature Toggle) 的介紹。

章節目錄

認識一下 Feature Flag

本部落格秉持著「簡單、友善、我好菜」的精神，按照慣例先簡單介紹一下
已經知道的朋友就可以跳過這個小節，直接前往 #環境準備囉。

假設我們原本有 Old 邏輯：

Old();

天庭傳來諭令，要我們改成 New 邏輯。這簡單，我們就把 Old 砍掉，換成 New。非常自然，改完就佈版

New();

隔天，天庭又傳來諭令，New 需要調整一下，先不要了
現在我們又需要把 New 邏輯砍掉，讓 Old 邏輯回來。
簡單，但看來我們得再上一版

Old();
// New();

再隔天，大家可能猜到天庭又要幹嘛了，總之又上了一版

// Old();
New();

如此往復三萬八千次，工程師終於受不了了：「俺老孫每天在這切換 Old 跟 New，改完還得佈版，每天搞這些就飽了，我滴媽呀，不幹了」

就在老孫關燈走人的那一瞬間，突然靈光一現：等等，俺加個開關還不行嗎？

if (NewFunctionEnabled())
{
    New();
}
else
{
    Old();
}

現在只要把這個開關放到外面，別寫死在程式碼裡。丟去什麼 appsettings.json、Config、資料庫、ini、東海龍王廟，隨便

總之丟去個不用佈板就能直接修改的地方，不就完事了嗎？

現在程式碼就像盯著旗手的士兵們，旗手舉了藍色，他們就往左跑；旗手舉了紅色，他們就往右跑。老孫只要把設定給改了，就能一鍵切換邏輯，好不自在。

沒錯，老孫剛剛發現了 Feature Flag。

有了這個開關，除了開開關關(?)，現在也可以做到更多事情了。

例如新功能想先隨機讓一些使用者踩看看，馬上在這個 NewFunctionEnabled() 開關後面加點料，讓它隨機打開、隨機關起來；

想讓合作好的客戶搶先使用，馬上在這個 NewFunctionEnabled() 開關後面偷塞一張白名單：
你聽好了，看到這些人就幫我按藍色的按鈕，門就會打開

因為我們把開關抽出去了，代表判斷條件和執行邏輯之間的耦合被我們給降低了，
這樣開關的彈性就變高了，我們也就可以針對開關內部的邏輯動手動腳了

老孫把開關弄出來之後，用得挺爽。一時之間，花果山分部的工程師紛紛效仿老孫，
用這個香香的 Feature Flag 來從外部動態切換程式碼邏輯，好不爽快。
吱聲此起彼落，可謂是：

兩條邏輯改又改，改完還要等佈版
有了 Feature Flag，切個開關就下班

至於後來開關越埋越多，系統服務七十二變。工程師老孫被迫跟著唐經理去聽研討會，好好學習怎麼管理這些 Feature Flag。還弄了些儀表板、過期時間等等，那又是另一個故事了…

故事說到這裡，雖然例子粗暴一點，但朋朋們應該對 Feature Flag 在幹嘛有點了解了（吧？）

如果想要進一步認識 Feature Flag，這邊也準備了一些推薦閱讀。

例如 Feature Flag 還可以用在哪、分成哪些種類；
兩個 Flag 共用到同一段 Code 怎辦；
PM 朋朋們又是怎麼運用 Feature Flag 的……

都丟在下面這團，提供給有興趣的朋朋們：

補充：雖然 Feature Flag 這麼香，但如果開關沒有好好管理，
不小心開到不該開的程式碼邏輯會發生什麼事呢？

泡杯茶，看看實例吧：Knightmare: A DevOps Cautionary Tale – Doug Seven

補充：Feature Toggle 常常跟主幹開發（Trunk-based Development）一起出現？

蠻常聽到這個問題的，這邊也簡單筆記一下，沒有採用主幹開發的朋朋可以跳過這小段

（想認識 Trunk-based Development 的朋朋們，
　可以右轉去 TrunkBasedDevelopment.com，感謝協助中文化的大大們）

回到問題，我的理解是這樣：

即使我們採用了主幹開發，持續把變更交付到主幹分支上，把大家的 GAP 降到最低，
但一定還是會遇到需要做很久才做得完的功能

我們不想要拉一條 feature 分支，放著漸漸就跟主幹脫節，到時候合併又要大爆炸
而是想要把這些程式碼持續地整合到我們的程式庫，這樣就能及早發現問題和解除衝突
可是如果粗暴地合併進去，開發中的功能就會暴露出來…怎麼辦呢？

這種時候，如果有一個開關，來幫助我們關閉尚未完工的功能、打開即將交付的功能。我們就能整合現有的程式碼，也能提早知道合併會不會炸爛其他功能…

很方便對吧？ Feature Toggle 就跳出來啦。香。

環境準備：Microsoft.FeatureManagement

好，我們前面簡單介紹了一下 Feature Flag，接著就進入實作階段。

要實現 Feature Flag 的方法有很多，例如我之前都是用上一篇提到的 IOption 直接從 appsettings.json 把 true/false 讀出來用

而這篇我們要來使用香香的 FeatureManagement 來幫我們實現 Feature Flag 的操作。

首先，我們要先搞到 Microsoft.FeatureManagement.AspNetCore 這個套件：
NuGet Gallery | Microsoft.FeatureManagement.AspNetCore

接著讓我們把它給註冊到我們的 Program.cs：

// Program.cs

// 環境準備：Microsoft.FeatureManagement
// 加入 Feature Flag 功能，預設會抓 appsettings.json 中的 "FeatureManagement" 節點
builder.Services.AddFeatureManagement();

// 如果想要自訂 Feature Flag 在 appsettings.json 裡的位置，可以這樣寫
//builder.Services.AddFeatureManagement(builder.Configuration.GetSection("CustomFeatureManagement"));

然後為了後續的示範，先開好一組 Controller：

// Controllers/DemoController.cs

/// <summary>
/// 示範 Feature Flag 的使用
/// </summary>
[ApiController]
[Route("[controller]")]
public class DemoController : ControllerBase
{
    private readonly ILogger<DemoController> _logger;
    private readonly IFeatureManager _featureManager;

    public DemoController(
        ILogger<DemoController> logger, 
        IFeatureManager featureManager)
    {
        _logger = logger;
        _featureManager = featureManager;
    }
}

這樣環境就搞定了，讓我們開始第一組實作吧！

實作：使用 IsEnabledAsync 拿到 Feature Flag 的值

假設我們跟上面的老孫一樣：翻寫了一條新版邏輯。
如果開關被打開了，就走新版的路線；關著的話就維持舊版

要達成上面的條件，我們會需要直接取得某個 Flag 的開關狀態，
這時候就可以使用 IsEnabledAsync

先到 appsettings.json 加上我們的 Feature Flag，先叫做 NewLogicEnabled：

// appsettings.json

"FeatureManagement": {
  "NewLogicEnabled": true
}

為了後面方便使用，我習慣先建一組簡單的 Const 來管理這些 Feature Flag：

// Flags/FeatureFlags.cs

public class FeatureFlags
{
    // 這邊的名稱要和 appsettings.json 裡 FeatureManagement 底下的設定一樣
    public const string NewLogicEnabled = "NewLogicEnabled"; 
}

讓我們加上這次測試用的 API，並且使用 IsEnabledAsync 來抓取指定的 Flag 狀態：

// Controllers/DemoController.cs

// Feature Flag 可以讓我們從設定檔中讀取特定的開關
// 並且在程式中根據這些開關來決定是否啟用某些功能
[HttpGet("IsEnabledAsync")]
public async Task<string> IsFeatureEnabled()
{
    // Demo 1: 使用 IsEnabledAsync 拿到 Feature Flag 的值 
    var isEnabled = await _featureManager.IsEnabledAsync(FeatureFlags.NewLogicEnabled);
    
    return isEnabled 
        ? "香香的新版邏輯已啟用。"
        : "新版邏輯尚未啟用，繼續使用臭臭的舊版邏輯。";
}

現在讓我們直接把 appsettings.json 裡的 NewLogicEnabled 改成 false（只要存檔就好了，不需要重啟服務），並且再呼叫一次 API：

來張動圖看看成果：

搞定，收工下班。

實作：使用 FeatureGate 來啟用和停用 API

除了根據開關決定要執行哪條路線的邏輯以外，我們也常常根據開關決定某些功能是不是要開放

如果我們需要根據 Feature Flag 來決定是否啟用某支 API，就可以使用 FeatureGate

首先讓我們加上第二組 Flag，這次叫做 NiceApiEnabled：

// appsettings.json

"FeatureManagement": {
  "NewLogicEnabled": false,
  "NiceApiEnabled": true
}

// Flags/FeatureFlags.cs

public class FeatureFlags
{
    public const string NewLogicEnabled = "NewLogicEnabled"; 

      // 新增 NiceApiEnabled
    public const string NiceApiEnabled = "NiceApiEnabled";
}

接著就來替我們的 API 掛上 FeatureGate 試試：

// Controllers/DemoController.cs

[HttpGet("FeatureGate")]
[FeatureGate(FeatureFlags.NiceApiEnabled)] // 讓 FeatureGate 去檢查我們的 NiceApiEnabled
public string FeatureGate()
{
    // Demo 2: 使用 FeatureGate 來啟用和停用 API
    // 如果 NiceApiEnabled 是關閉的，這個方法不會被執行，會直接回傳 404
    return "這是一個很棒的 API，只有你看得到。";
}

NiceApiEnabled 是 true 的時候，可以正常呼叫到 API：

而當 NiceApiEnabled 是 false 的時候，這支 API 就不存在了…

實作：使用 FeatureFilter 自訂篩選條件、隨機抽取使用者

前面我們示範了怎麼看開關狀態，以及根據開關把 API 給 Ban 了。接著來點場景應用吧。

之前遇過需要隨機抽樣去分流的狀況（把 50% 使用者引導去翻寫好的新站台觀察狀況之類的）

像這種需要自己寫某些邏輯來決定開關是否開啟的場合，就可以使用 FeatureFilter 來實現

跟前兩個範例一樣，我們需要先去 appsettings.json 掛上我們的 Feature Flag。既然是要隨機抽取幸運兒體驗我們的新功能，就叫做 RandomTrial

但要注意，當我們要自訂 Flag 啟用的條件（也就是需要跑過某些邏輯才能決定是 true/false）的時候，就不能像前面兩個範例一樣簡單丟個 "RandomTrial":true 就搞定

而是要使用 EnabledFor，並在裡面標示出我們要呼叫的 FeatureFilter 名稱、需要傳遞的參數，這樣 FeatureManagement 才知道它得依序跑過這些 FeatureFilter

假設我們希望有 50% 的使用者會隨機抽中新功能。我們就可以先在 EnabledFor 裡掛一條叫做「Random」的 FeatureFilter，並且丟個 Percentage=50 的參數進去：

// appsettings.json

"FeatureManagement": {
  "NewLogicEnabled": false,
  "NiceApiEnabled": false,
  
  "RandomTrial": {
    "EnabledFor": [
      {
        "Name": "Random",
        "Parameters": {
          "Percentage": 50
        }
      }
    ]
  }
}

// Flags/FeatureFlags.cs

public class FeatureFlags
{
    public const string NewLogicEnabled = "NewLogicEnabled"; 
    public const string NiceApiEnabled = "NiceApiEnabled";

    // 新增 RandomTrial
    public const string RandomTrial = "RandomTrial";
}

接著讓我們實作對應的 FeatureFilter，這邊作法就可以粗暴一點：

從 context.Parameters 把前面設好的 Percentage 參數拉出來
現場骰下去看有沒有過門檻，沒過就掰掰

// Filters/RandomFilter.cs

/// <summary>
/// 隨機啟用 API 的 Filter
/// </summary>
/// <see ref="https://learn.microsoft.com/zh-tw/azure/azure-app-configuration/howto-feature-filters-aspnet-core"/>
[FilterAlias("Random")] // 設定 Filter 的別名，讓 appsettings.json 可以使用這個別名
public class RandomFilter : IFeatureFilter
{
    public Task<bool> EvaluateAsync(FeatureFilterEvaluationContext context)
    {
        var percentage = context.Parameters.GetValue<int>("Percentage");
        
        var seed = Guid.NewGuid().GetHashCode();
        var randomNumber = new Random(seed).Next(100);
        
        var isEnabled = randomNumber <= percentage;
        return Task.FromResult(isEnabled);
    }
}

接著我們要把這個 FeatureFilter 拿去註冊：

// Program.cs

builder.Services
    .AddFeatureManagement()
    .AddFeatureFilter<RandomFilter>() // 加入自訂的 Feature Filter. see: Filters/RandomFilter.cs
    ;

接著就像前面的兩個範例一樣，直接拿來用就好嚕

// Controllers/DemoController.cs

[HttpGet("FeatureFilter/Random/")]
public async Task<string> FeatureFilterRandom()
{
    // Demo 3: 實作：使用 IFeatureFilter 來隨機啟用 API - 直接查詢 Feature Flag
    var isEnabled = await _featureManager.IsEnabledAsync(FeatureFlags.RandomTrial);
    return isEnabled 
        ? "恭喜你！你抽中了香香新版邏輯的試用機會！"
        : "什麼事也沒發生，又是臭臭邏輯的一天。";
}  

[HttpGet("FeatureFilter/Random/FeatureGate")]
[FeatureGate(FeatureFlags.RandomTrial)]
public string FeatureFilterRandomWithFeatureGate()
{
    // Demo 3: 實作：使用 IFeatureFilter 來隨機啟用 API - 透過 FeatureGate 來啟用
    return "恭喜你！你抽中了很棒 API 的試用機會！";
}

來張動圖看看成果：

實作：使用 FeatureFilter 來根據白名單啟用 API

接下來試試另一組場景，假設我們打算先讓十位合作客戶試用新功能，
這時候也可以靠自製 FeatureFilter 來處理。

備註：這一節會需要用到依賴注入相關的功能，還不熟的朋友可以參見依賴注入的筆記

首先按照慣例，先加上我們的 Feature Flag
這次就叫做 Whitelist，並且只指定 FeatureFilter 的名稱就好，不需要參數：

// appsettings.json

"FeatureManagement": {
  "NewLogicEnabled": false,
  "NiceApiEnabled": false,
  "RandomTrial": {}, // 好長，省略
  
  "Whitelist": {
    "EnabledFor": [
      {
        "Name": "Whitelist"
      }
    ]
  }
}

// Flags/FeatureFlags.cs

public class FeatureFlags
{
    public const string NewLogicEnabled = "NewLogicEnabled"; 
    public const string NiceApiEnabled = "NiceApiEnabled";
    public const string RandomTrial = "RandomTrial";

    // 新增 Whitelist
    public const string Whitelist = "Whitelist";
}

接著，假裝一下我們在某張資料表裏面有白名單資料：

// Repositories/WhitelistRepository.cs

public interface IWhitelistRepository
{
    Task<IEnumerable<string>> GetWhitelistAsync();
}

public class WhitelistRepository : IWhitelistRepository
{
    public async Task<IEnumerable<string>> GetWhitelistAsync()
    {
        // 假裝從資料庫中取得白名單 :)
        return new List<string>
        {
            "Apple",
            "Banana",
            "Cat"
        };
        // 小提醒：如果真的連線到資料庫，然後名單的改動頻率很低，可以考慮加個快取
    }
}

而且這個 Repo 也有好好註冊到 Program.cs。
同時，因為後續的示範一定也需要從 Request 拿到使用者的身分
這邊也註冊了 IHttpContextAccessor 來取得 Request 內容：

// Program.cs
builder.Services.AddHttpContextAccessor();
builder.Services.AddSingleton<IWhitelistRepository, WhitelistRepository>();

延伸閱讀：存取 ASP.NET Core 中的 HttpContext 的「從自訂元件存取 HttpContext」小節

備註：如果 FeatureFilter 依賴對象的生命週期是 Scope 的，會需要調整一下 FeatureManagement 的註冊，請看這一小節最後的補充。

上游的假資料準備好了，接著就讓我們來實作白名單 FeatureFilter 吧：

// Filters/WhitelistFilter.cs

/// <summary>
/// 白名單啟用 API 的 Filter
/// </summary>
[FilterAlias("Whitelist")]
public class WhitelistFilter : IFeatureFilter
{
    private readonly IWhitelistRepository _whitelistRepository;
    private readonly IHttpContextAccessor _httpContextAccessor;

    public WhitelistFilter(
        IWhitelistRepository whitelistRepository, 
        IHttpContextAccessor httpContextAccessor)
    {
        _whitelistRepository = whitelistRepository;
        _httpContextAccessor = httpContextAccessor;
    }

    public async Task<bool> EvaluateAsync(FeatureFilterEvaluationContext context)
    {
        // 粗暴地從 Request 的 Header 取出使用者名稱
        // 實作時記得換成真正的使用者資訊來源，例如 JWT Token、拆好的 User 資訊、擲筊的結果，之類的
        var user = _httpContextAccessor.HttpContext?.Request.Headers["User"]; 
        if (string.IsNullOrWhiteSpace(user))
        {
            return false;
        }
        
        // 假裝從資料庫中取得白名單，檢查使用者是否在白名單中
        // 實作時記得換成真正的白名單來源 & 比對邏輯
        var whitelist = await _whitelistRepository.GetWhitelistAsync();
        return whitelist.Any(x => x.Equals(user, StringComparison.OrdinalIgnoreCase)); // 插個不分大小寫，避免我等等 Demo 手殘
    }
}

搞定，開開心心來註冊囉：

// Program.cs

builder.Services
    .AddFeatureManagement()
    .AddFeatureFilter<RandomFilter>()
    .AddFeatureFilter<WhitelistFilter>(); // 把白名單的 FeatureFilter 掛上去

接著捏支 API 來測測看：


// Controllers/DemoController.cs

[HttpGet("FeatureFilter/Whitelist/")]
public async Task<string> FeatureFilterWhitelist(
    [FromHeader(Name = "User")] string user)
{
    // Demo 4: 實作：使用 IFeatureFilter 來根據白名單啟用 API
    var isEnabled = await _featureManager.IsEnabledAsync(FeatureFlags.Whitelist);
    
    return isEnabled 
        ? $"{user} 先生/小姐，你好。歡迎使用本服務。您是我們第 9999 位 VIP 會員！"
        : $"{user} 先生/小姐，你好。很抱歉，本服務尚未開放給您使用。請加入我們的 VIP 會員，取得優先體驗資格！";
}

來張動圖看看成果：

搞定，收工。又是美好的一天，準時下班囉

補充：由於 FeatureManager 是 Singleton 的，而 AddFeatureFilter 會根據 FeatureManager 的生命週期來註冊 FeatureFilter，因此如果依賴對象的生命週期是 Scope，注入的時候就會發生錯誤。

這時候請改用 AddScopedFeatureManagement：
// Program.cs

// builder.Services.AddFeatureManagement();
builder.Services.AddScopedFeatureManagement();
參考：Unable to inject Scoped/Transient services into FeatureFilter · Issue #15 · microsoft/FeatureManagement-Dotnet

延伸閱讀：依賴注入的三種生命週期 Transient、Scoped、Singleton

小結

稍微玩了一下 FeatureManagement，並且拿了一些前陣子遇過的場景來實作看看

原本以為只是簡單的去組態抓開關，想不到 FeatureFilter 提供的自訂條件還蠻彈性的，挺香

FeatureGate 無腦噴 404 也挺爽的（警告：請跟呼叫端的朋朋喬好= = 不然很危險，生命危險）

如果有想要搞個 Feature Flag 的場合，推薦可以玩玩看。

那麼，今天的筆記就到這邊。我們下篇見～

參考資料

.Net: 使用 IOptions 取得 appsettings.json 的設定值吧

Igouist (Igouist) — Sat, 03 Aug 2024 08:30:00 +0800

因為手邊的 .Net Core API 專案越來越多，蠻常會需要讀 appsetting.json 的 Config，每次都要重找文章有點麻煩，這邊就來筆記一篇。

章節目錄

認識 Appsettings.json

首先簡單介紹一下 appsettings.json 是在幹嘛的：

我們開發的時候，常常會需要先設定好一些服務參數、組態設定之類的設定值，再用這些設定值用來控制我們程式的某些行為。例如：

「某功能的上限值是 10」
「某項開關在測試環境是 false」
「某服務信件的發送者要用 noreply9527」

另外常見的還有連線字串、寫 Log 時的 logging level 等等。

這些設定值會和程式碼拆開，放在設定檔集中管理，再讓程式碼從設定檔讀取相關的設定值來用就好，藉此來把設定值的管理和使用做個關注點分離。

有了設定檔，要調整修改也比較方便：要增加或是修改設定值，都只要先往設定檔衝就行。並且因為兩邊拆開了，我們也就可以簡單地替換這些設定值來應對不同狀況（例如正式環境和測試環境套用兩組不同的設定檔，或是在自己電腦測試的時候快速改個值之類的），彈性可說是 UPUP！

更重要的是，這樣我們就不需要把一大堆東西寫死在程式碼的各個地方，也就不會要改個值還要先搜尋整個專案再一個一個挖出來改了。~~我按 Shift Ctrl F 已經按到哭~~

把設定值抽出去丟到設定檔之後，我們就得到了：集中管理設定值、方便修改和替換、減少程式碼中又重複又寫死的臭東西等等好處。

在 .Net Core 的世界裡，這個設定檔就是 appsettings.json。
前面提到的像是日誌等級、功能旗標之類的這些設定值，就會放在 appsettings.json 裡面。

而當我們想要從 appsettings.json 把這些設定值給讀出來的時候，
就可以使用我們的 IOptions 啦！

使用 IOptions 來註冊 & 注入

提醒：這篇的示範會用到一些些 .Net 依賴注入（DI）相關的操作。沒接觸過的朋友可以考慮先閱讀菜雞新訓記：依賴注入

假設我們有個專案，叫做大漢防禦管理系統。專案內的 appsettings.json 有以下內容：

{
  "StrongholdInfo": {
    "Index": 49,
    "Name": "劍閣",
    "Enabled": true, 
    "General": [
      "姜維",
      "廖化",
      "張翼",
      "董厥"
    ]
  }
}

我們正好在開發一個新功能，需要抓到這段設定值。現在就來示範一下：

首先，讓我們建立一個類別，等等用來放設定值內容（通常後綴會用 Options）

/// <summary>
/// 關隘資訊
/// </summary>
public class StrongholdInfoOptions
{
    /// <summary>
    /// 關隘編號
    /// </summary>
    public int Index { get; set; }
    
    /// <summary>
    /// 關隘名稱
    /// </summary>
    public string Name { get; set; } = string.Empty;
    
    /// <summary>
    /// 關隘啟用狀態
    /// </summary>
    public bool Enabled { get; set; }
    
    /// <summary>
    /// 駐守人員
    /// </summary>
    public string[]? General { get; set; }
}

接著使用 Configure<T> 來註冊，並且用 Configuration.GetSection 來指定這段設定值在 appsettings.json 裡的位置：

// 原本就有的一些註冊...
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

// 使用 Configure 註冊 Option
builder.Services.Configure<StrongholdInfoOptions>(
    builder.Configuration.GetSection("StrongholdInfo"));

註冊好了之後，就可以使用 IOptions<T> 注入到我們要用的地方囉


[ApiController]
[Route("[controller]")]
public class DemoController : ControllerBase
{
    private readonly StrongholdInfoOptions _info;

    // 使用 IOptions<T> 注入，並用 .Value 取得內容
    public DemoController(
        IOptions<StrongholdInfoOptions> info)
    {
        _info = info.Value;
    }

    [HttpGet("IOption")]
    public object Get()
    {
        return _info;
    }
}

收工，搞定。就是這麼簡單。

補充：AddOptions & 對 IOptions 加入驗證

前面我們在註冊時，是使用 Configure：

// 使用 Configure 註冊 Option
builder.Services.Configure<StrongholdInfoOptions>(
    builder.Configuration.GetSection("StrongholdInfo"));

其實也可以使用 AddOptions：

// 使用 Configure 註冊 Option
builder.Services.Configure<StrongholdInfoOptions>(
    builder.Configuration.GetSection("StrongholdInfo"));
    

// 或是使用 AddOptions，這兩個做法最後都會呼叫 Configure<StrongholdInfoOptions>
// see: https://github.com/dotnet/extensions/issues/514
// ps: `BindConfiguration` 是比較新的語法，以前會使用 `Bind() + builder.Configuration.GetSection()`
builder.Services
    .AddOptions<StrongholdInfoOptions>()
    .BindConfiguration(StrongholdInfoOptions.SectionName);

這兩個語法最終會做同樣的事情，因為 Bind() 會去呼叫 Configure()

只是 AddOptions 比較晚出現，並且後來又加入了更多自定義，用起來比較靈活。

例如我們可以用 ValidateDataAnnotations 來啟用屬性驗證：
（可參考 Microsoft Learn 選項模式的「選項驗證」小節）

[Required]
[RegularExpression(@"^[\u4e00-\u9fa5]{1,10}$")] // 限定 1~10 個中文字
public string Name { get; set; }

builder.Services
    .AddOptions<SettingsOptions>()
    .Bind(Configuration.GetSection(SettingsOptions.ConfigurationSectionName))
    .ValidateDataAnnotations()  // 會在呼叫 .value 的時候進行驗證
 // .Validate(config => {})     // 也可以自訂驗證邏輯
 // .ValidateOnStart()          // 也可以要求在啟動時就驗證
    ;

// 假如加了 ValidateDataAnnotations 的話，取值驗證失敗會噴 OptionsValidationException
try
{
    SettingsOptions options = _config.Value;
}
catch (OptionsValidationException ex)
{
    foreach (string failure in ex.Failures) // 畢竟可能一堆東西沒通過驗證嘛
    {
        _logger.LogError("Validation error: {FailureMessage}", failure);
    }
}

如果需要自訂驗證器，可以搜尋 IValidateOptions，可以自己實作 Validate()，但我個人還沒遇到這麼複雜的狀況，這邊就不詳述。

Configure 直接又簡單，但 AddOptions 比較靈活。
我個人比較喜歡粗暴直接的做法，所以目前是都直接呼叫 Configure 而已。供各位參考

補充：IOptions、IOptionsMonitor、IOptionsSnapshot

提了 IOptions 就不能不提他的兩位哥哥：IOptionsMonitor、IOptionsSnapshot

[ApiController]
public class OptionsMonitorDemoController : ControllerBase
{
    // 我們有三種 IOptions 相關的介面來取得設定檔內容
    private readonly IOptions<StrongholdInfoOptions> _options;
    private readonly IOptionsMonitor<StrongholdInfoOptions> _optionsMonitor;
    private readonly IOptionsSnapshot<StrongholdInfoOptions> _optionsSnapshot;
}

這邊也迅速筆記一下。有興趣的朋友可以直接閱讀相關文章：

IOptions、IOptionsMonitor 以及 IOptionsSnapshot - wenhx - 博客园
ASP.NET Core 中的選項模式 | Microsoft Learn 的「選項介面」小節

IOptions

用起來最簡單方便，個人推👍

IOptions 會註冊為 Singleton，所以大家都會用同一組。也只有第一次建立的時候會抓設定檔的內容。後面就算跑去偷改檔案，也不會被影響（想更新？重啟站台吧）

如果設定檔不太常改動的話，直接用 IOptions 簡單做一做是最方便的，也省資源。

IOptionsMonitor

IOptionsMonitor 同樣也會註冊為 Singleton，但是它會去偷聽設定檔有沒有更新。
當設定檔有更新的時候 IOptionsMonitor 也會一起更新，所以能夠隨時取得目前版本的設定值

取值的方法名稱也很明確表達這點，大家都是 _options.Value，
但 IOptionsMonitor 的是 _options.CurrentValue

_options = _options.Value,
_optionsMonitor = _optionsMonitor.CurrentValue,

如果我們的功能非常依賴設定值，而且又希望隨時更新（像留言區 Cash 大補充的 Hot Reload）的時候，就可以考慮使用 IOptionsMonitor。

但要小心如果 API 正在處理 Request，然後又剛好正在修改設定檔的話，可能會有一些靈異現象（？）

弄這篇筆記的時候也動手試了一下 IOptionsMonitor，但有點小佔版面，就放在最後的附錄（讓我之後可以回來抄）了。

IOptionsSnapshot

IOptionsSnapshot 會註冊為 Scope，所以每個請求進來的時候，都會各自去拿一次目前的設定檔內容，並且就用這一份設定檔內容處理這一次請求

我個人感覺最中規中矩。吃得到設定檔的變動，但也不會像 IOptionsMonitor
搞到前一秒還是 true 下一秒就是 false🤔

如果有改動 Config 的需求，又能接受下一組 Request 進來才吃到的時候（或是希望不要發生靈異現象），就可以考慮使用 IOptionsSnapshot。

大概這樣。但我個人平常都還是 IOptions 優先，
如果真的有需要即時反應設定檔的變動時，再把另外兩個拿出來討論吧。

延伸閱讀

前面介紹了 .Net Core 裡 appsettings.json 和 IOptions 的基本操作，也順便補充了一些簡單介紹。其他相關的操作，就放在延伸閱讀這邊，有興趣的朋朋們可以看看。

如果想根據不同環境（Dev, Prd 之類的）切換不同 appsettings.json：
ASP.NET Core 依環境載入不同 appsetting.json 設定 - 黑暗執行緒

如果你正在搞功能旗標（Feature Flag/Feature Toggle）然後看到這篇的話，
也可以嘗試看看 FeatureManagement：
.Net: 使用 FeatureManagement 套件來實作 Feature Flag 功能切換吧

如果覺得到處都是 IOptions，想要降低對 IOptions 的依賴的話，可以綁到強型別裡：
[NETCore] ASP.NET Core 使用強型別取代 IOption 注入配置 ~ m@rcus 學習筆記

參考資料

附錄：試一下 IOptionsMonitor

簡單比較一下修改 appsettings.json 後，IOptions 和 IOptionsMonitor 的資料差異，方便我以後需要複製貼上，或是哪天需要甩給朋友時使用。

public OptionsMonitorDemoController(
    IOptions<StrongholdInfoOptions> options, 
    IOptionsMonitor<StrongholdInfoOptions> optionsMonitor)
{
    _options = options;
    _optionsMonitor = optionsMonitor;
}

[HttpGet("api/Demo/GetWithMonitor")]
public IEnumerable<object> GetWithMonitor()
{   
    var before = new
    {
        OptionsName = _options.Value.Name,
        OptionsMonitorName = _optionsMonitor.CurrentValue.Name,
    };
    
    // 在這裡下中斷點，打開 appsettings.json 手動改資料
    // 把 "Name": "劍閣" 改成 "Name": "羅馬"
    System.Threading.Thread.Sleep(1000);
    
    var after = new
    {
        OptionsName = _options.Value.Name,
        OptionsMonitorName = _optionsMonitor.CurrentValue.Name,
    };
    
    return new object[] { before, after };
    // [
    //   {
    //     "optionsName": "劍閣",
    //     "optionsMonitorName": "劍閣"
    //   },
    //   {
    //     "optionsName": "劍閣",
    //     "optionsMonitorName": "羅馬"
    //   }
    // ]
}

《九日》白金心得

Igouist (Igouist) — Thu, 01 Aug 2024 07:00:00 +0800

終於過了！九日沒有慣例的「完成所有成就」的盃，但是放結局獎盃又怕結局名字雷到路過的朋友，就截普通模式通關的盃吧。

按照慣例，留一篇筆記來聊聊心得和體驗，以下有雷。

補充：這篇是我個人遊玩《九日》的心得。
如果你是在找《九日》的白金獎盃攻略，推薦你這篇：【九日】才不是什麼全成就指南呢，哼！

首先，必須感謝當初募資的大大們有開出劇情模式，讓我解完其中一條結局（被易公痛扁）之後，可以馬上讀檔開劇情模式看另一條。（逃離研究中心的電影運鏡很棒啦，但我實在不想再走一次了囧）

看完兩個結局後，能理解為什麼蠻多人會說后羿射日結局才是真結局。原本覺得只是「不同的選擇」，但通關之後我也比較喜歡這個結局，易公第三階段和最後射日的演出令人印象深刻，也充滿故事結束的感覺。

這次的戰鬥和地圖探索體驗都很不錯，但果然首先要提的還是「道教龐克」的部份。

一開始有點水土不服，就是有點熟悉感又覺得怪怪的。但越玩越覺得「哇這很不錯」。像是嗑毒草的阿農、墳墓是虛擬實境裝置、煉丹的丹藥其實是基因改造，另外還有很潮的太陽語（說是古漢語發音和倉頡拼字來的？）等等。

蠻喜歡這種充滿各種腦洞的詮釋，感覺還有很多發展空間，不知道以後會不會有道教龐克宇宙？

另外一些破台時比較有印象的部分，首先就是臭菜（想了一下才發現是在嘴香菜）。還有李耳墓，通過三位大佬的測試、聽了李耳的寓言，然後才意會到門口就是被砍翻的那三位大佬，體驗良好。

哦對，還有茱麗葉。

然而最有記憶點的，果然還是第一次經過扶蝶他家門口的時候的 jump scare。

發現畫面開始無限 Loop 的時候，我就躲得離螢幕超超超遠。事後還上巴哈求助詢問後面還有沒有這種嚇人玩意，真的差點嚇到棄坑 = ="

但提到扶蝶就要稱讚一下，扶蝶戰的體驗和音樂真的很讚。

節奏雖然很快，但是從 1 隻、3 隻再到 7 隻分身，這種逐漸加快、越來越密集的感覺打起來非常舒服。應該是我打完九日過程中覺得戰鬥體驗最讚的 Boss，堪比易公

故事裡成員們陷入超級虛擬實境不想醒、搭配夢蝶的意境也很不錯。對戰中從後腦長出蝴蝶也很有 Feel，音樂更是相當有感（Smile at My Cursed Dream ~~Lady Ethereal’s Theme~~），就是背景和跑圖太陰間了點

除了扶蝶戰以外，也聊聊其他比較有印象的戰鬥

截全戰的印象九成都在背景音樂上，就是那首「苦難！哈！鑄英雄！」（有一段聽起來超像「人真好！郭富城！」的那首）。戰鬥過程就是中規中矩的你一刀我一刀。但截全的人氣好像蠻高的？常常看到相關的圖。

另一場印象比較深的是姬的戰鬥，尤其是占卜可以自己踩想要的，所以踩得準就可以自己選補血，一直補一直爽。飛劍可以格檔、黑洞可以打斷，實在非常貼心，所以說這種神秘又古老的角色就是棒。奄老還是乖乖顧倉庫去吧。

至於最終戰的易公，只能說齁勝。剛進場的時候覺得揮刀速度明明很慢，卻一直抓不到格檔的感覺。有種被教鞭教訓的感覺（這就是師傅嗎）

戰鬥過程中基本上就是鏘鏘鏘一直檔，檔完就抓空隙上符做輸出（不如說我八成輸出都是靠符），無量反擊用好才能進一步喝水跟補刀。打著打著有種夢回隻狼的 Feel

當然第三階段被完全看不懂的飛天劍打成智障又是另一個故事了。易公第三杯水強得跟鬼一樣，難怪他會覺得變怪物是種進化，我被打到都快信了

整輪打下來的戰鬥心得是：一定要格檔，一定要貼符。

很多輸出空間（像是扶蝶和易公）都只能靠貼符，越打到後期越覺得符才是主要輸出，刀反而是裝了玉石加減砍來治內傷的

戰鬥充滿格檔和互動，體驗非常良好。

故事部分也相當不錯，像山海 9000 支線到最後找到朋友和照片，還有風氏兄妹奢糜背後的原因（開打之前：人都死光了你們還開趴？　打完之後：太悲哀了QQ）、阿農一路走到帶領村人等等。

有一小段和軒軒下棋的對話我也蠻喜歡：

「咦！我是不是要贏了！」

『對，其實下到一半我就知道自己贏不了。
　恭喜你，接下來可以去找下一名對手了。』

「哈哈，才不要，我又不是為了贏，我只是想跟大哥下棋」

『不為輸贏嗎？　
　哈，看來我該學的東西還真不少。』

最後，偷偷許願，希望九日有機會像隻狼那樣出個單純和 Boss 對戰的模式（補：出啦！讚讚！）

像是扶蝶、易公都是那種會讓人想再打的 Boss。如果能手癢就上去擋兩把就好了呢～

大概醬子，白金封片。感謝九日。

《Fate/Samurai Remnant》白金心得

Igouist (Igouist) — Sun, 14 Apr 2024 05:20:00 +0800

要開玩 DLC 的時候跳了盃，按照慣例來發一下白金心得文～

補充：這篇是我個人遊玩《Fate/Samurai Remnant》的心得。
如果你是在找《Fate/Samurai Remnant》的白金獎盃攻略，推薦你這幾篇

【FSR】全成就攻略及部分收集地圖

智周萬物（雜記本條目100%全收集）

以下簡單列一下個人覺得的優點（當然有雷）

伊織和 Saber 這對主從很有特色。尤其是主角伊織的成長很有感，也有反應在遊戲性上，後期拿到空之架式的時候割草很爽快。在師徒決戰、伊織使出祕劍的時候，身為 Fate 玩家和動畫宅真的看得非常開心。

除此之外，二週目增加劇情、開始能漸漸窺見到主角內心異常的部份很棒。劍鬼意外地很有魅力，最後的對戰和收尾方式也相當舒服，應該是歷代精神狀況最令人「蛤？」的主角了吧，真不錯。

如果有一周目覺得劇情挖得不夠深入，或是主角的刻畫不夠的朋友，推薦把真結局打完。伊織現在已經成了我在 Fate 系列數一數二喜歡的主角了。

除了兩位主角之間的互動，其他主從之間的互動也還處理得還不錯，尤其是正雪和鄭成功。像是「我好好地遵守著您的命令！」這一段的張力很夠。

也有可能是因為我意外地蠻喜歡「切換視角到其他陣營的角色來認識他們」的處理方式吧。但當然也有一些橋段讓我，呃，不是很理解，例如三郎，到底在幹嘛？即使通關後已經幾個月的現在，這角色還是讓我充滿疑惑，而且操作起來也很難用。真的很難用。

既然都聊到三郎了，接著來補一下個人認為的缺點：

戰鬥時的破盾很煩，很拖時間。可以理解說身為人類打這些妖怪是很麻煩啦，可是我都打到後期了還在幫他們刮痧，真的很拖棚。

另外，有些角色的戲份少到令人意外。例如第十五騎，劇情鋪了這麼久，不會真的只是為了出來打個招呼而已吧？也許 DLC 會交代吧。也許。

最後，也是最令我崩潰的則是踩到超臭 Bug：
千辛萬苦蒐集完畢之後，居然沒跳白金！沒跳白金！沒跳白金！

害我浪費了一堆時間爬文、哀號。直到放棄之後，大約四個月之後才等來了官方修復。太傷害了。

如此如此，準備來開玩 DLC 慶安神前比武了。最後就貼個完成度紀念一下吧：

哦對，然後豬真的很可愛。滿分。

我買彩券是為了做一個善良的人

Igouist (Igouist) — Sat, 03 Feb 2024 12:02:00 +0800

我買彩券是為了做一個善良的人
只要還沒開獎，我就有可能會成為億萬富翁

有緊急需求？沒問題
東西又改壞了？沒關係
客戶跑來罵我們全家？當然可以

一個買了彩劵的人，生活充滿希望，行事滿懷善良，心胸寬大、舉止謙讓

畢竟我說不定晚上就發財了，沒必要跟你們計較這些小事。對吧

本文章絕無任何業配。投資一定有風險，購買樂透有賺有賠，申購前應撰寫破產聲明書

《臥龍：蒼天殞落》白金心得

Igouist (Igouist) — Wed, 05 Apr 2023 10:00:00 +0800

在東漢逛街快一個月，總算白金啦！

這次臥龍玩起來還算挺爽快的，從第一隻 Boss 張梁老師就好好教導玩家的基礎操作。而且意外地能從黃巾之亂一路做到官渡之戰，前期戰役打好打滿，算是蠻有誠意的。

白金之後就開始期待後續的三個 DLC 跟二代了。畢竟三國題材這麼多，實在不怕沒有後作嘛，但 DLC 還要等到六月，這篇就來稍微紀錄一下心得吧。

戰鬥＝化解

這次戰鬥主打的是「化解」系統，基本上就是在敵人攻擊的瞬間進行化解，很有中國武術的味兒，也讓我想起隻狼鼓勵玩家要提起勇氣上前拚刀的快感。

初次接觸的時候會覺得這系統做得很不錯，同時帶來了風險和回報：化解失敗就會被捅一刀，而化解成功就可以提升氣勢（可以當成能量條，做任何動作都會消耗），並且得到進攻機會。

除此之外，化解殺招的畫面也很帥，敵人釋放絕招然後主角行雲流水擋掉回擊，很有觀賞樂趣。

因此整個遊戲的主軸就是化解敵人的攻擊和殺招，你來我往地進攻，整個戰鬥就是化解的節奏，打起來挺爽快的。

到這裡我都還是覺得化解真香。但到中後期的時候就開始發現：整個戰鬥過程，就只有化解。

不像隻狼，應對敵人的攻擊時，如果是一般攻擊就需要招架，而對付「危」的殺招時需要跳或識破，再加上敵人多樣的變招，帶來了有趣的即時應對，強迫玩家當下要判斷並且反擊，並且失誤就會帶來死亡，實在是「猶豫就會敗北」

但在臥龍，不論敵人的任何動作，攻擊、殺招、弓箭、法術，基本上就是靠化解。戰鬥過程簡化到只剩下攻擊和化解兩個步驟，導致戰鬥很難有新的玩法。

尤其可以同時防禦和化解這一點，讓化解的風險變得更小了，只需要防禦按著應付敵人的殺招就好。節奏熟悉了之後，戰鬥基本上就是等著敵人開大，跟下落式的節奏遊戲差不多

只能說化解打得很爽快，卻也只需要化解，不夠痛快。

這也關係到 Boss 的設計。老實說，主線通關後比較有記憶點的，只有虎牢關呂布和十萬伏特張遼，以及欺負玩家視角很難切換的影分身張讓公公。

因為九成的 Boss 戰（其實小兵戰也是啦）都是抓時機化解，整場就是你帥一下，我化解你，你再帥一下，我再化解你。所以像袁紹這種原本很期待的知名 Boss 一次過的時候就覺得挺空虛的

結果都在觀賞 Boss 長得怎樣，哇會飛好帥、會放雷電好帥。

然後啪，化解！啪，化解！沒了。

既然都提到張讓公公的 Boss 戰了，就順便抱怨一下圍毆關卡。

這遊戲切換視角不知道為什麼很卡。偏偏仁王傳統的圍毆關卡還是有留下來，像是什麼「江東三虎臣」，三個人圍毆你還會放冷箭丟炸彈，還要喊話嗆你，我切個視角就忙得要死了，哪有時間，氣得半死。

更氣的是我打過了然後難度下修了。謝囉。

蒐集＝甚、甚是可恨

這次的蒐集成就比仁王少很多了（體感上），只有回復道具升滿、慣例的撿特定道具給 NPC 吃（仁王系列是糞球，這兒竟然是蟬殼），還有餵東西給路邊的野熊貓。

偏偏前兩個看道具都還能大概知道數量，但野熊貓這個完全不記得哪裡有遇到，因為蒐集內容不會顯示在任務上，完全搞不懂哪一關有餵、哪一關沒餵，找得挺痛苦。只好全破完之後再全部關卡找一次囧

這個成就的名稱叫做「甚是可愛」，巴哈有人說根本是「甚是可恨」，完全認同。

補充：三月底的時候改版，現在在關卡選單可以看到是否達成蒐集條件了，可是我已經解完了嗚嗚

劇情＝沒有劇情

劇情就仁王系列傳統了，大家都被妖怪附身，玩家每個都要打。

有心病的自己變妖怪；沒心病的被強迫變妖怪。不會變妖怪的？誰說人類就不能扁，信不信扁到變妖怪

現在看到任何 NPC，都是在想到底能不能扁他，到底什麼時候能扁他。

然後孫策的劇情就這樣，真是夠了。DLC 的「稱霸江東」這章節最好補完哦。

優化＝仁王傳統

最後聊聊優化。不得不說，遊戲初期的優化做得蠻爛的，這也是仁王傳統了

沒有關掉垂直同步的話會卡到幾乎不能玩，開場第一關的村莊就有大規模的燃燒場景，與其是新手教學，不如說是顯示卡檢定，看你電腦夠不夠玩這遊戲

但還是有看到逐漸更新的誠意啦，像是前面提到的蒐集素材搞不懂哪關達成了、視角切換很痛苦等等。發售一個月左右基本都有推出優化和更新，還算是不錯了

另外一個覺得需要優化的點，應該就是牙旗系統了。在搞什麼啊。

牙旗系統給像我這樣的探索地圖仔帶來了不錯的獎勵，我一周目的時候也插旗子插得很開心

只要在關卡裡找到旗子，插下去就會增加士氣，只要旗子插得越多、士氣值的下限就越高，而士氣值又能提升角色的戰鬥力，甚至比裝備什麼都來得直接有效

所以逛街插旗子代表你的角色戰力也越強，跟 Boss 的差異也越小，士氣值少 Boss 五級的話，被 Boss 揍的傷害應該有差到一倍。

因此一周目的時候，我基本上都是在逛關卡找旗子、欣賞地圖設計，然後跟 Boss 來一場平等的決戰。這時候的我不禁感嘆，的確是個好系統

但第二次進關卡旗子都要重插，結果都在跑酷。天哪，我不打了行嗎

小結

整體來說，優缺點還算明顯。一路化解打架的痛快感非常足夠、後續的優化也有聽到玩家的反應

我個人是挺期待後續的三個 DLC，而且三國版仁王這麼大的題材，不作個二代也說不過去。

考慮到之前仁王後續 DLC 的難度都加強不少，還是來二周目打個裝備好了囧。那麼，我們下次見～

使用 Midjourney AI 繪圖 & Canva 產生 Banner 初體驗

Igouist (Igouist) — Sun, 29 Jan 2023 10:01:00 +0800

我們在前一篇嘗試自行產生簡單的文字 Banner，我也用了好一陣子（畢竟三年前的新訓文章還是沒整理完嘛）。

直到前陣子逛臉書的時候，看到有人說「我都改用 AI 繪圖工具來產生部落格的配圖了，還沒有版權問題」當下驚為天人：對呀！這不是很不錯嗎！

如此如此，這般這般。立馬開始爬文來嘗試神秘的 AI 繪圖囉！

初嘗試 Midjourney

在網路搜了一下，發現有大神已經整理 Midjourney 入坑詳細步驟，特此感謝：

AI 繪圖教學，Midjourney 基本操作 · 嫁給 RD 的 UI Designer (akanelee.me)

這邊就稍微紀錄一下，總之先衝到 Midjourney，然後直接註他個冊、登他個入：

這時候會需要登入 Discord，然後同意一些授權之後，回來首頁選左邊的 Join the Beta，就會被邀請到 Midjourney 的 Discord 伺服器囉：

成功加入伺服器之後，可以看到左邊有一些 newbies 頻道，新來的朋朋們會在這邊產圖玩：

進入頻道後應該會看到很多人已經在玩了。讓我們到下面的對話框，輸入 /imagine 找到指令（因為太多人用了，可能輸入 / 就會跳出來了）：

接著就可以開始輸入咒文囉！

像我現在想要他產生一些很科幻的工程師雞，就可以輸入一些「Programming Chicken」啦之類的，咒文技術艱深，還請各位自行嘗試。~~我已經試到整個產圖紀錄都是雞~~

補充：前面提到的大神也有寫一篇關鍵字小技巧：

Midjourney 如何讓畫面精準呈現 · 嫁給 RD 的 UI Designer (akanelee.me)

以及另一位大神搭配 ChatGPT 產生咒文的紀錄，可以觀察關鍵字的格式和順序：

[ChatGPT 咒語庫] Midjourney 咒語產生器

[ChatGPT 咒語庫] Midjourney 咒語解析器

除此之外，也可以到 Midjourney 官網的 Showcase，裡面的作品會列出使用的咒文。或是直接在頻道裡面觀察別人詠唱也可以

或是到 Midjourney 提供的二次元繪圖版本 Nijijourney，註冊流程都一樣，但有支援中文頻道。像我這樣的英文渣去個中文頻道比較有機會看懂其他人詠唱咒文的邏輯啦，不然就認命 Google 翻譯了 xD

如果沒有什麼方向，可以先隨便下咒嘗試一下，但要注意免費試用有產圖的次數限制哦
我個人大概產出 40 張圖的時候就用光免費額度了 xD

（玩不夠的可以參見定價以及這篇巴哈的介紹，付費版還有比較慢但可以依直玩的 relax 模式，真香）。

咒文輸入完之後 Midjourney 會運算一下，過陣子機器人就會 Tag 你跟你說搞定啦：

可以看到下面有兩排按鈕：

Ｕ＝我要這張了，幫我弄大圖出來
Ｖ＝給我從這張圖繼續產新的一組圖出來

而數字則是對應從左到右從上到下的順序，也就是：
１２
３４

如果都沒有喜歡的，就勇敢按下🔁（這些我都不要，重來），或是乖乖回去調整咒文的關鍵字吧

如果按下Ｕ、選了圖之後就會開始幫你產生高清大圖：

有種外星文明的感覺，超級太空雞的外星文明。

到這邊我們已經會玩ＡＩ繪圖了，基本上就是動動手詠唱咒文而已。

但別忘記今天來的目的：我們是來做部落格文章 Banner 的啊！

嘗試調整圖片比例

~~總之我玩了半小時才想起來~~

既然我們是來製作文章封面的，而且根據先前的風格，至少要是矮矮寬寬的橫幅圖，還要讓我可以有地方寫文章標題

開始思考要怎麼做成部落格插圖之後，發現預設產的圖都不是我要的「矮矮寬寬的橫幅圖」，那麼就得先試試看是不是能夠調整圖片的比例囉！

官方有提供 /imagine 可以下的參數列表：Midjourney Parameter List

其中 aspect-ratios（–ar）就是我們要的調整圖片比例，但目前最新版的 v4 只支援預設的 1:1 以及 3:2, 2:3

更新：最新的 v5 已經可以支援自動比例囉！

有了 v5 之後，我只需要 --v 5 --ar 3:1 就可以得到我想要的橫幅圖啦！

不過以下還是 v4 版的血淚經驗，留著當紀念吧 xD

雖然可以用 --v 3 來指定比較舊的 v3 版本，這樣比例就能支援到更長的 7:4，但畢竟是舊版，連雞的形狀都高機率崩壞掉

甚至給我炸雞：

炸雞欸？真是科技齁，謝了 Midjourney。第 3 版真的不行啊，果然還是最新的版本香。

這邊已經宣告放棄，但是是放棄調整圖片比例，而不是放棄加上文字

決定先在咒文加一些 black background,no background,simple,icon 之類的關鍵字，讓圖和背景顏色變單調，我再自己把圖拉寬補文字

接著就是不斷的調整和重骰：

終於選定了一張圖，是時候回歸動手開工的時候啦！

使用 Canva 直接產出橫幅圖

~~我努力過了，我的小畫家技術爛到拉圖打字都做不好~~

身為一個具有工程師美德（怠惰）的菜雞，當然是要找一下有沒有好用的服務嘛對不對。

最後找到了這個 Canva。Canva 在免費使用時就有方便的拖拉編輯和足夠的範本數量，非常符合我目前簡單拉個圖的超初階需求

這就註冊登入到首頁，可以看到已經有一排快速開始的選項可以選擇，看了一下 600x200 的電子郵件標題最符合我要的形狀：

進來之後就可以看到空白畫面和一排範本，這次我們有備而來，完全不會用到範本：

總之先來上傳區，把剛剛ＡＩ的帥雞圖丟上來：

接著來調整背景顏色，上傳圖片之後 Canva 就會提供圖片內的一些顏色給你選，不過我試了一下，感覺上面選取顏色再指定圖片的顏色會比較好調整：

顏色盡量做到不太明顯就好了，畢竟ＡＩ也不會乖乖聽話用純黑背景Ｑ＿Ｑ

最後切換到文字頁面，加個標題、選個字型，完工

怎麼感覺比我原本用的ＦＢ封面產生器還方便了呀…

總之這下圖也產出來了，這篇也記錄完了。關門，收工

心得＆小記

這篇稍微紀錄了一下產製部落格文章 Banner 時碰了ＡＩ繪圖和線上製圖服務的過程

不得不說ＡＩ繪圖還真的蠻好玩的，唯一的問題就是 Midjourney 的免費額度一下就用光了囧

額度用光之後也嘗試把 programming chicken 這組關鍵字，丟去其他的ＡＩ繪圖服務看看，例如 DALL.E 和 Stable Diffusion，目前還是 Midjourney 產的圖最精細，Stable Diffusion 甚至一直丟給我人類的圖…

當然也有因為 Midjourney 跟一群人擠在 Discord 頻道產圖的體驗蠻特別的關係，看別人下咒生圖實在是蠻有趣的。我在製作工程師科技雞的時候，有位老兄一直在做帥氣烏鴉圖，差點就變成鳥類探索頻道

另外還發現 Midjourney 也出了二次元特化版 Nijijourney，甚至支援用中文組咒文（會自動翻譯成英文），不過額度用完了就沒試，後續有機會也想玩看看

最後找到的 Canva 作圖比當初的產生器還簡單，之後沒梗圖用的時候應該會優先用 Canva 吧。大概。

最後用一張 OpenAI 家的 DALL.E 產生出來的圖來做結吧，感謝各位

使用 .Net 的 System.Drawing 產生簡單的文字 Banner 初體驗

Igouist (Igouist) — Sun, 29 Jan 2023 10:00:00 +0800

原本我都是用產生 FB 封面的「康熙字典體產生器」來做簡單的文字 Banner，就拿來當作文章的封面照

用了好一陣子也沒啥問題。結果某天文章寫好，吃著火鍋唱著歌，產生器打開一看，服務竟然就沒了！

當下是一個震驚啊，一氣之下決定直接打開 Linqpad 寫一個。

註：現在搜尋康熙字典體產生器，還查得到介面截圖，還真的蠻簡單方便的 Q_Q

以前面的菜雞與物件導向系列 Banner 為例，我們大概需要：

產生一張圖
在圖上面放主標題和副標題
關鍵字可以上色

稍微搜尋一下發現 .Net 已經有 System.Drawing 這個工具可以幫我們完成這些簡單的圖片任務，事不宜遲馬上就來嘗試！

開工

首先第一步，當然是先畫出橫幅底圖，這邊就讓我們先建立圖片，並且用 Graph.Clear 先塗個黑色好辨識，長寬就參照先前產生器的長 315 寬 850：

void Main()
{
	int width = 850;
	int height = 315;

	using (var img = new Bitmap(width, height))
	{
		using (var graph = Graphics.FromImage(img))
		{
            // 先塗個黑色當底
			graph.Clear(Color.Black);
		}
        // Linqpad 的打印語法，可以直接顯示圖片
		img.Dump(); 
	}
}

接著讓我們開始加入主標題，這邊就用先前 Fluent Validation 文章的標題當作示範，直接用 Graph.DrawString 把文字寫到圖片中間。

註：這邊的字型是漢儀新蒂的黑板報體，可以替換成自己電腦裡有的字體

void Main()
{
	int width = 850;
	int height = 315;

    // 主標題相關設定：字型、大小、顏色
	var title = "使用 Fluent Validation \n來驗證參數吧";
	var fontName = "Hanyi Senty Chalk Original";
	var fontSize = 36;
	var fontColor = Color.White;

	using (var img = new Bitmap(width, height))
	{
		using (var graph = Graphics.FromImage(img))
		{
			graph.Clear(Color.Black);

            // 建立一下文字和筆刷
			var font = new Font(fontName, fontSize);
			var brush = new SolidBrush(fontColor);

            // 設定一下位置，Banner 的字當然要置中
			var rect = new Rectangle(0, 0, width, height);
			var format = new StringFormat()
			{
				Alignment = StringAlignment.Center,
				LineAlignment = StringAlignment.Center
			};

            // 直接把整個標題畫到圖上
			graph.DrawString(title, font, brush, rect, format);
		}
		img.Dump();
	}
}

我們順利地把標題顯示在圖的正中間，好像有那麼一點搞頭了。

接下來我們要加入關鍵字的顏色。原先的字典檔產生器可以用 % % 來把要標顏色的關鍵字框起來，例如：「使用 %Fluent Validation% 來驗證參數吧」這樣就知道「Fluent Validation」是關鍵字，需要上色。

因此這邊最快的做法就是用 % 來切割，再照著「一般顏色、%、關鍵字顏色、%、一般顏色」的順序輪流上色就好了。上色也只需要替換設定筆刷的 SolidBrush 就好，非常簡單：

void Main()
{
	int width = 850;
	int height = 315;

	var title = "使用%Fluent Validation%\n來驗證參數吧";
	var fontName = "Hanyi Senty Chalk Original";
	var fontSize = 36;
	var fontColor = Color.White;

    // 加入關鍵字要用的第二組文字顏色
	var fontSubColor = Color.Goldenrod; 

	using (var img = new Bitmap(width, height))
	{
		using (var graph = Graphics.FromImage(img))
		{
			graph.Clear(Color.Black);

			var font = new Font(fontName, fontSize);
			var brush = new SolidBrush(fontColor);

            // 加入了關鍵字用的第二組筆刷
			var subBrush = new SolidBrush(fontSubColor);

			var rect = new Rectangle(0, 0, width, height);
			var format = new StringFormat()
			{
				Alignment = StringAlignment.Center,
				LineAlignment = StringAlignment.Center
			};

            // 為了照一般色、關鍵字色、一般色的順序上色，需要先把標題做拆分
			var words = title.Split('%');
			for (var i = 0; i < words.Count(); i++)
			{
				// 有 %% 圈選起來的字詞，使用特殊色 ex: %API%
				var thisBrush = i % 2 == 0
					? brush
					: subBrush;

                // 改成分別將每一組字畫到圖上
				graph.DrawString(words[i], font, thisBrush, rect, format);
			}
		}
		img.Dump();
	}
}

好的完蛋。

因為前面的 Graph.DrawString 是無腦把整個 title 丟進去產生，因此文字的位置只需要在 StringFormat 指定個 Center 讓他置中就沒問題了。但

現在又要切關鍵字啥的，全部指定在中間當然就會疊在一起囧。這下子就只能自行計算長度了。

因為用 % 切完關鍵字之後會有很多段字，最直接的做法還是先嘗試抓到上一段字的結束位置，再繼續寫下一段字在後面，這時候我們就可以用上計算文字大小的 graph.MeasureString，馬上進行調整：

void Main()
{
	int width = 850;
	int height = 315;

	var title = "使用%Fluent Validation%\n來驗證參數吧";
	var fontName = "Hanyi Senty Chalk Original";
	var fontSize = 36;
	var fontColor = Color.White;
	var fontSubColor = Color.Goldenrod;

	using (var  img = new Bitmap(width, height))
	{
		using (var graph = Graphics.FromImage(img))
		{
			graph.Clear(Color.Black);

			var font = new Font(fontName, fontSize);
			var brush = new SolidBrush(fontColor);
			var subBrush = new SolidBrush(fontSubColor);

			var rect = new Rectangle(0, 0, width, height);
			var format = new StringFormat()
			{
                // 放棄直接指定置中的語法
				//Alignment = StringAlignment.Center,
				//LineAlignment = StringAlignment.Center
			};

			var words = title.Split('%');
			for (var i = 0; i < words.Count(); i++)
			{
				// 有 %% 圈選起來的字詞，使用特殊色 ex: %API%
				var thisBrush = i % 2 == 0
					? brush
					: subBrush;

				graph.DrawString(words[i], font, thisBrush, rect, format);

				// 嘗試計算每一段字的長度，然後重新調整位置
                // 讓下一段字可以接著繼續寫
				var wordWidthFloat = graph.MeasureString(words[i], font).Width;
				var wordWidth = Convert.ToInt16(wordWidthFloat);
				rect.Offset(wordWidth, 0);
			}
		}
		img.Dump();
	}
}

看起來使用 Graph.MeasureString 先抓到字段的長度再繼續寫下去是可行的。同時我們也知道了幾件事：

因為 StringAlignment.Center 的置中已經被拿掉了，現在我們除了要自行計算長度，還得要自己指定起始位置了，不然會跑回左上角。這時候就需要回來調整處理位置的 Rectangle。

幸好圖片的長寬都是我們先知道的，所以這部分直接用整個 Banner 的長度除以二先定位到正中間，然後再往左邊移整行字的長度的一半，這樣就可以讓這行字置中且左右對稱了！

除了起始位置以外，還可以看到 \n 切出去的第二行字的開始位置也會被第一行字的結束位置影響到，這代表我們換行顯示的時候需要重新調整位置。

至於第一行要顯示的高度，就要直接測一下了。

void Main()
{
	int width = 850;
	int height = 315;

	var title = "使用%Fluent Validation%\n來%驗證參數%吧";
	var fontName = "Hanyi Senty Chalk Original";
	var fontSize = 36;
	var fontColor = Color.White;
	var fontSubColor = Color.Goldenrod;

	using (var  img = new Bitmap(width, height))
	{
		using (var graph = Graphics.FromImage(img))
		{
			graph.Clear(Color.Black);

			var font = new Font(fontName, fontSize);
			var brush = new SolidBrush(fontColor);
			var subBrush = new SolidBrush(fontSubColor);

			var rect = new Rectangle(0, 0, width, height);
			var format = new StringFormat();

            // 先把每一行字都拆開，方便後續換行處理
			var contents = title.Split('\n');
			var lines = 0;

			foreach (var content in contents)
			{
                // 每一行的開頭重新定位起始位置
				var contentWidthFloat = graph.MeasureString(content, font).Width;
				var contentWidth = Convert.ToInt16(contentWidthFloat);

                // 先從整張圖的寬度抓到正中間，再往左移動這行字的一半，讓整行可以置中
				var setX = (width / 2) - (contentWidth / 2);
                // 先抓整張圖中間偏上的位置，然後換行的時候就往下移動一個字的高度
				var setY = height / 5 + lines * font.Height;

                // 中英文混著抓距離的話有時候點歪歪的= = 這邊加個值方便手動校正起始點
				var widthset = 20;

                // 重新定位要寫字上去的起始點
				rect.Location = new Point(setX + widthset, setY); 

				var words = content.Split('%');
				for (var i = 0; i < words.Count(); i++)
				{
					var thisBrush = i % 2 == 0
						? brush
						: subBrush;

					graph.DrawString(words[i], font, thisBrush, rect, format);

					var wordWidthFloat = graph.MeasureString(words[i], font).Width;
					var wordWidth = Convert.ToInt16(wordWidthFloat);
					rect.Offset(wordWidth, 0);
				}

				lines++;
			}

		}
		img.Dump();
	}
}

看起來主標題差不多有達到想要的效果了，順便多加了一組關鍵字測一下。~~程式碼的巢狀也越疊越多了哦~~

是時候來加個副標題了。副標題通常都比較簡單，像上面的範例只是用來標個系列文名稱

這邊直接抓主標題的程式碼稍微改一下，接在主標題後面操作就好

var subTitle = "菜雞新訓記‧七";
var subFontSize = 20;
// 中間處理主標題的部分省略...

// 副標題
if (subTitle != null &&
    string.IsNullOrEmpty(subTitle) is false)
{
    // 副標題的字型，只有大小先跟主標題不一樣，高度則往下抓一些避免蓋到主標
    var subFont = new Font(fontName, subFontSize);
    var subRect = new Rectangle(0, height - height / 4, width, height);

    var subFormat = new StringFormat()
    {
        Alignment = StringAlignment.Center,
        LineAlignment = StringAlignment.Near
    };

    graph.DrawString(subTitle, subFont, brush, subRect, subFormat);
}

這樣就搞定啦！

最後稍微整理一下程式碼，把主標和副標會用到的參數包個類別，方便後面需要調整的時候可以用：

public class BannerString
{
    public string FontName { get; set; } = "Hanyi Senty Chalk Original";
    public string Content { get; set; } = string.Empty;
    public int FontSize { get; set; } = 36;
    public Color MainColor { get; set; } = Color.White;
    public Color SubColor { get; set; } = Color.Goldenrod;
}

製作 Banner 的語法也先裝起來，改成傳遞上面包好類別的函式。

用來調整位置的偏移值也抽出來放著方便隨時調整：

private readonly int widthset = 20;

public void GenerateBanner(
    BannerString title,
    BannerString subTitle = null,
    int width = 850,
    int height = 315)
{
    using (var img = new Bitmap(width, height))
    {
        using (var graph = Graphics.FromImage(img))
        {
            // 上面的程式碼本體
        }
    }
}

這樣後續回來使用這個腳本就可以直接改外面的參數就好啦！

void Main()
{   
   var title = new BannerString
   {
       Content = "使用%Fluent Validation%\n來%驗證參數%吧",
       FontSize = 40
   };
   
   var subTitle = new BannerString
   {
       Content = "菜雞新訓記‧七",
       FontSize = 20
   };
   
   GenerateBanner(title, subTitle);
}

存完收工！

小結

雖然這個工具的場景挺侷限的，但寫小腳本的過程也還算有趣，~~雖然調位置的時候已經有點沒耐心，快要打開小畫家了~~

有鑒於三年前新訓的筆記到今天都還沒寫完，之後應該還是會派上用場 xD

但後來因緣際會看到另一種 Banner 製作方式令我躍躍欲試，結果忙半天又走回去用 Canva 直接產圖，又是別的故事了…

Polyglot Notebooks －－在 VSCode 簡單迅速地撰寫 C# 腳本吧

Igouist (Igouist) — Sat, 28 Jan 2023 18:00:00 +0800

2026-03 補充：

Polyglot Notebooks 已經宣佈被棄用了：DEPRECATION ANNOUNCEMENT: Polyglot Notebooks & .NET Interactive - Github，由 .Net 10 提供的單檔執行功能取代。

單檔執行功能可以直接用 dotnet run app.cs 這種方式直接跑 .cs 檔，引入套件的語法也差不多。以順手撰寫腳本的角度來說比 Polyglot Notebooks 更加方便，有興趣的朋友也可以看看：體驗 .NET 10 的超酷新功能：dotnet run app.cs | The Will Will Web

像我這樣的菜鳥工程師，在 Coding 的時候時常會需要簡單試一些想法。像是「我這邊下了這串 Linq 出來的資料，到底是不是我想要的內容啊 = =？」

或是在進行開發任務時：「這個步驟能不能這樣做啊？先拆個簡單的 Method 試試看好了」之類的

以往遇到這種時候，我都會打開香香的 Linqpad 直接無情開寫，快速地作個小小的概念驗證。

畢竟 Linqpad 可以迅速地開始撰寫簡單的 C# 腳本，並且有良好的語法提示、Nuget 支援和方便的資料庫連線，省去我還要開一個 Console 專案自己弄這些東西，更可以存著之後備查，所以一直以來我都愛不釋手。

但在因緣際會下（其實就是閒逛論壇的時候），發現了微軟把拔出的 Polyglot Notebooks 這款 VSCode 擴充套件。當下驚為天人！Linqpad 在我心中的地位就這麼動搖了

Polyglot Notebooks 可以讓我們直接在 VSCode 上面撰寫簡單的 C#、F#、JavaScirpt 等腳本、迅速驗證想法。甚至可以對程式碼分段、加入 Markdown 文檔，讓我們能更有邏輯、有步驟地撰寫我們的腳本、處理我們的資料。

它的特色是這麼對我的胃口，看來我以後鐵定是會用到的。現在就來簡單記錄 Polyglot Notebooks 的使用方式吧！

章節目錄

安裝及建立檔案

首先我們需要先在 VSCode 找到「Polyglot Notebooks」這個擴充套件並安裝：

安裝完畢之後，我們可以有兩種開啟方法：

新增 ipynb 檔案再切換到 .NET Interactive 引擎
使用 Polyglot Notebooks 的指令或快捷鍵，直接建立 dib 或 ipynb 檔案

補充：ipynb 檔案是用於撰寫 IPython Notebook 的檔案，也就是 Jupyter Notebook 在使用的檔案。而微軟把拔藉由 .NET Interactive 引擎讓 Jupyter Notebook 可以支援 C#, F#, SQL 等語言，讓 Notebook 可以支援多語言的撰寫，因此我們建立 ipynb 檔案也是可以撰寫 C# 的，感謝微軟把拔

由於我之前已經有在使用 Jupyter Notebook 撰寫 Python，因此這邊就以新增一個 ipynb 檔案進行示範：

建立了 ipynb 檔案之後，讓我們切換到 .NET Interactive 引擎：

現在我們已經可以看到讓我們 Coding 的儲存格了，這樣就完成準備工作啦！

補充：也可以使用 Ctrl+Shift+Alt+N 快捷鍵，或是 Ctrl+Shift+P 叫出 VSCode 的指令窗來下 Polyglot Notebook: Create new blank notebook 來直接建立檔案

這時候 VSCode 會詢問你要建立 .dib 或是 .ipynb，其中 .dib 進去就直接是 .NET Interactive 引擎，但目前還在實驗階段，並且 ipynb 還是以較常見的格式，因此我都還是選擇慣用的 .ipynb

開始撰寫腳本

首先當然要從 Hello world 開始啦，讓我們直接在儲存格裡面開寫：

撰寫，然後按下全部執行或是左邊的單格執行：

切換腳本語言、加入更多儲存格

儲存格的右下角可以讓我們切換語言：

例如說我們可以來個 JavaScript：

當然我們並不是只有這一個小小的儲存格能用（否則我前面就不敢說可以切步驟了嘛）

可以按下左上角的「＋程式碼」來新增程式碼儲存格，或是把滑鼠移到儲存格最底部，會出現執行之後幫你往下新增一格的按鈕：

現在我們可以同時放上兩個語言啦：

我們也可以針對某一格來執行，或是用滑鼠選擇指定的儲存格，就可以選擇執行指定的儲存格以上或以下的部份，如果有修改某一格，然後要從修改的部分重跑一次的時候還挺方便的：

此外還有複製貼上儲存格、合併儲存格等等操作，可以在上圖右邊紅框的「…」找到，這邊就不再贅述。

插入 Markdown 儲存格

眼尖的朋友應該發現了，上面新增儲存格的地方除了「＋程式碼」以外，還有「＋Markdown」的選項

畢竟 Polyglot Notebooks 這東西還是一本「筆記本」，只能貼 Code 不能寫筆記還算什麼筆記本呢，對吧？

因此我們可以在程式碼區塊之間適當地加入 Markdown 區塊，來提供需要的資訊，或是紀錄需要的筆記。讓我們撰寫的過程可以更有條理，之後回來閱讀也可以更快掌握內容。

除了在最底下新增儲存格的做法以外，我們也可以對指定的區塊上下來插入新儲存格：

現在讓我們加入 Markdown 內容：

執行之後就會變成文檔的一部分囉！

如果 Markdown 有用到標題之類的，實測也可以進行摺疊：

如此一來這份 Notebook 也可以當作一份文件來保存下去了，豈不美哉！

印出參數內容 & 簡單的 Linq 操作範例

現在來一點實境題：假設我現在想要試試看怎麼「取出列表裡面，依據特定欄位分組後，每一組的第一筆資料」

首先我們先做個測試用的 Class，並且捏一點測試用的假資料

接著直接呼叫參數來印出內容確認一下：

現在我想要每一個 code 的第一筆，也就是 True 的那一筆。現在我覺得「也許 GroupBy 之後 Select 第一筆就搞定了吧？」

這時候我就可以在下面新增一個儲存格來做測試：

搞定！現在我有信心使用這段 Code 了。還可以順便存成一個「分組取第一筆.ipynb」來讓以後的我可以抄，又是美好的一天。

安裝 Nuget 套件 & 簡單的呼叫 API 範例

2024.4.20 更新：後來時常連公司自家的 Nuget 抓內部套件，決定回來補一下指定 Nuget 的範例

平常開發的時候，我們還會運用各種套件來完成目標。

在 Polyglot Notebooks 裡可以使用 #r "nuget:{套件名稱}" 來安裝 Nuget 套件

此外，如果有需要指定 Nuget 套件來源，也可以使用 #i 來處理

#!c#
#i "nuget:https://api.nuget.org/v3/index.json"
#r "nuget:Newtonsoft.Json"
// 需要指定版本的話，可以在後面加上版本號。
// 例如：#r "nuget:Newtonsoft.Json, 12.0.3"

using Newtonsoft.Json;

var obj = new { Name = "James", Age = 30 };
var json = JsonConvert.SerializeObject(obj);
json // {"Name":"James","Age":30}

什麼是 Magic Commands

在前面安裝套件的時候，我們使用了 # 開頭的語法，這些語法被稱作「Magic Commands」

可以參考：Magic Commands 魔法命令 - dotnet/interactive

以下使用程式碼區塊（Cell）紀錄一些比較常用的 Magic Commands：

#!lsmagic
// 使用 #!lsmagic 來列出所有支援的 Magic Commands
// 或是參考 https://github.com/dotnet/interactive/blob/main/docs/magic-commands.md

#!csharp
// 使用 #!csharp 來指定語言為 C#
// 支援的語言有：#!csharp (#!c#, #!C#), #!fsharp (#!f#, #!F#)
// #!powershell (#!pwsh), #!javascript (#!js), #!html, #!markdown

#!time
// 使用 #!time 來計算 Cell 的執行時間

Console.WriteLine("Hello World!"); // Wall time: 32.5128ms

// 也能使用 #!mermaid 來讓 Mermaid.js 繪製流程圖

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

使用 #!set 來跨語言傳遞變數

2024.4.20 更新：用了一段時間之後，發現這東西的其中一個香點就在跨語言。趕緊回來補一下這段

當我們需要在兩個不同的程式語言之間傳遞變數，就可以使用 #!set

可參考：Variable sharing 變量共享

ps. #!share 誕生的比較早，但後來推出了更香的 #!set，所以這邊就只記 set 嚕 XD

#!c#

var fruitPrices = new Dictionary<string, int>
{
    {"apple", 10},
    {"banana", 20},
    {"cherry", 30}
};

// 同一個語言不需要特別傳遞也抓得到，所以這邊 Csharp 傳給 Csharp 不用做什麼處理
#!c#

var fruitPricesInCs = JsonConvert.SerializeObject(fruitPrices);
Console.WriteLine(fruitPricesInCs); 
// {"apple":10,"banana":20,"cherry":30}

// 現在讓我們到 JavaScript，這時候如果想從 Csharp 把變數拿過來，就需要用到 #!set
#!javascript
#!set --name fruitPricesInJs --value @csharp:fruitPrices

console.log(fruitPricesInJs); 
// {"apple":10,"banana":20,"cherry":30}

小結

這篇記錄了 Polyglot Notebooks 的基本用法，並且介紹了一些我覺得很香的地方：輕便快速的驗證風格、能像 Python 的 Jupyter NoteBook 逐步對資料進行處理，又有 C# 的 Linq 能用，用這東西寫個爬蟲之類的小腳本，邊跑隨改實在是舒適的體驗。

但同時因為這個工具還是 Preview 階段，被其他 IDE 養慣的我，已經習慣貼上語法之後讓 IDE 提示我 using 相關的命名空間進來了，因此像是 HttpClient 這種需要 using 的在這邊就很容易忘記，導致沒有跳自動完成提示的時候寫起來有點綁手綁腳（…說完感覺比較像是我的問題= = 我就菜）

總之身為一個當年用過 Jupyter Notebooks 的使用者，還是很看好這個工具後續的發展。輕便又能按步驟執行、又跨語言、又能插 Markdown 來做文檔，怎麼想都香！

~~太香了太香了，是不是該拿來刷題了啊？~~

2023.02.28 補充：
前面提到沒有自動完成提示的問題，在搭配 Github Copilot 之後，已經不是問題了！

例如說需要 using 的時候，Github Copilot 會幫忙補：

安裝 Nuget 套件的時候，也會幫忙補上：

甚至－－

原來 Polyglot Notebooks 搭配 Github Copilot 才是完全體啊！

~~果然還是該拿來刷…~~

參考資料

《仁王》＆《仁王２》白金心得

Igouist (Igouist) — Thu, 26 Jan 2023 09:20:00 +0800

終於趁著這次連假白金啦囧

在法環的白金文有提到過，我真的很懶得刷一些要農、重複蒐集東西的成就。偏偏仁王和仁王２後期都在做這兩件事情，結果兩款的主線過完之後就進入無限拖延狀態

尤其像仁王２的主線通關成就早在 2021/9/18 就拿到了，ＢＯＳＳ也都挑戰完一輪，但想到後面有一堆跟仁王１一樣要蒐集的東西，就一路拖到現在 2023/1/24 才農出白金

仁王系列給我的感覺很特別，它在前期的時候是個完完全全的魂系遊戲：容易死亡、要熟悉ＢＯＳＳ招式、要思考打法、重複挑戰和修正等等

但差不多一周目過完之後，中後期就會開始往暗黑那種刷裝、配裝的方向走。所以最佳方針就是一路打上高難度、農出可以搭配的裝、然後大功告成輾壓眾生。到這個階段已經沒有什麼魂系遊戲的味道了，樂趣變成是嘗試各種裝備的搭配和打法，完全變成另一款遊戲

二代在戰鬥和農裝都有比一代更友善一點，但感覺起來就是同一條套路。尤其我有一半時間都在用忍術隱身術之類的跑酷來蒐集東西和衝進度拿更強的裝備，所以記憶點都在蠻前面艱難打ＢＯＳＳ的一周目。只能說青菜蘿蔔各有所好，如果同時喜歡魂系和配裝的朋友可能就會挺滿意的

地圖設計方面還算不錯，水面下顛倒的平等院之類的有驚艷到我。不過一二代實在太多地方會摔死了！太多了！嚴島動不動地板就有洞讓你掉到水裡，然後我一個西洋水手（一代）／超強半妖（二代）就這樣溺死，搞啥？我失足溺死的次數說不定比被ＢＯＳＳ打成肉醬的次數還多

總之還是成功把這兩片都封印進去了，阿彌陀佛。~~所以我說那個血源上ＰＣ呢~~

《軟實力：軟體開發人員的生存手冊》心得

Igouist (Igouist) — Sun, 27 Nov 2022 00:00:00 +0800

這是一本你從未見過的軟體開發書。
－－《軟實力：軟體開發人員的生存手冊》

這本書其實已經借來兩年了（隔壁 Sian 心得文已經發了多久，就代表我借了多久），不過因為有一個指節那麼厚，我又是這麼的懶，因此就放在書櫃中睡了兩年，直到最近才終於捧起來看。

直接先說感想：驚為天人。這本書的內容就像是一篇接著一篇的部落格文章，但每篇之間又是環環相扣的，彷彿某種連載短篇一樣，會讓人一直看下去。

對於這本書的內容，我推薦有興趣的朋友、或是喜歡閱讀部落格的朋友可以自己去試閱看看（今年剛好也出了第二版）；這邊就來聊聊我覺得這本書比較特別的部份吧！

神奇的內容廣度

首先一定要從這本書神奇的內容廣度開始說起，從常見的職涯建議、自我行銷，到健身、理財都有。完全對得起「生存手冊」的名稱。

為了讓各位可以感受一下這個衝擊，這邊就條列出本書的章節目錄，並且附個一兩項裡面提到的內容：

職涯
- 如何把職涯當作企業經營？如何成為自由工作者？
自我行銷
- 如何打造個人品牌？為什麼幫助別人如此重要？
學習
- 什麼是十步學習法？指導別人有什麼好處？
生產力
- 什麼是番茄工作法？為什麼培養習慣這麼重要？
理財
- 什麼是選擇權？如何投資房地產？
健身
- 為什麼工程師需要健身？怎麼計算卡路里？
心靈
- 什麼是自我形象？我們該如何樹立理想的形象？

從目錄就可以看出來，這本書能夠給軟體工程師們為了生存所接觸到各個領域的簡介、讓讀者能快速對這些領域都有基本的概念。藉由這些基本概念，就可以根據這些方向來做進一步的了解。

例如我們在生產力的章節看到「番茄工作法」，也許就可以延伸閱讀介紹番茄工作法的書籍；而培養習慣和自我形象的章節，也能延伸到《原子習慣》。諸如此類，這本書可以說是非常好的指引。

先前看到 PARA 這套筆記分類法的時候，在 Area（領域）這個階段曾經困惑過：雖然說是要把寫好的筆記分類到長時間關注的各個領域主題，但我應該關心哪些領域才好呢？

當時只能切出幾個很模糊的大領域，然後筆記還是一股腦塞進去。面對像我這種迷惘的孩子，這本《軟實力》完美地給出了建議：身為一個軟體工程師，我推薦你關注這些領域！

看完的時候不經覺得，如果我在規劃筆記系統的時候就已經讀過這本書就好了！

貼心的小挑戰

書中有許多需要親身實踐的建議，在這些章節結束時都會給讀者一些小挑戰，讓讀者能從小地方開始動手做起。

例如說對自己生產力感到焦慮的我，就覺得書中對罪惡感的詮釋很有感觸：「你就是不知道自己做了多少事情，才會總覺得自己應該做更多事情」

而針對這個焦慮，作者提出了番茄鐘的解法，也邀請讀者親身力行。

我目前也正在嘗試使用番茄鐘來追蹤我的工作狀況。儘管結果還是有些令人慚愧，但至少是有統計資料佐證的慚愧，感覺還不錯。

因此針對書中的提議，的確是可以嘗試看看。如果能像開頭提到的朋朋 Sian 堅持每個小節的建議都嘗試看看，相信是絕對會有所收穫的。

生產力、自我推銷、健身－－是為了讓我們成為更好的人

最後來聊聊為什麼作者會在一本寫給軟體工程師的書本中，放入像是健身、理財這些主題：「為了讓我們成為更好的人」

也因為作者的這個目標，在閱讀的過程中會時常有種和作者對話的感覺，隨著作者的腳步去閱覽各個能讓我們「變得更好」的主題。

例如書中在講述為什麼我們害怕失敗、並鼓勵不要害怕像個傻瓜時，就像是作者直接給我建議一樣。

在理財健身這類我較不熟悉的領域，就像是作者在介紹基礎知識給我這個小白；而在閱讀習慣的養成、十步學習法等等章節，又能讓我和先前閱讀的原子習慣、超速學習等知識點連結起來。

因此這本書比起各種講述特定主題的書籍而言，更像是一本指南、一張粗略的地圖，指出在我們的專業以外，可以深入研究的區域，讓我們能夠有個方向來探索。

如果你也是像我一樣曾煩惱過副技能都該點些什麼，又或只是有點好奇、想找點各領域的入門磚來讀讀，相信這本書能夠讓你獲益。

最後放上我在這本書裡很喜歡的一句話，和大家共勉之

如果你不征服自己，你就會被自己征服。
－－拿破崙·希爾

使用 JMeter 來對 API 壓力測試吧

Igouist (Igouist) — Mon, 10 Oct 2022 18:50:00 +0800

前陣子協助某支 API 的壓力測試，趁機請 QA 朋朋指導指導一下，因此接觸了這款簡單好用的壓測工具 JMeter，趁現在記憶還在的時候記錄起來。

~~往後其他同事只要說 API 弄好了可以串了，就先幫他打個一萬次壓壓驚，真是貼心~~

JMeter 是款充滿暴力的壓力測試工具，只要告訴他：你要揍哪支 API？要揍幾拳？揍他個幾輪？它就會忠實地對你指定的 API 爆打一頓。

章節目錄

下載與開啟 JMeter

JMeter 會需要 Java，如果還沒有 Java 的朋友可以先安裝一下：下載 Windows 適用的 Java

首先讓我們到 JMeter 官網的 Download 頁面來下載，這邊我選擇 zip：

下載並解壓縮後，可以在 /bin 找到 jmeter.bat：

點開之後就會開啟 JMeter 的介面囉！

更改語言

雖然 JMeter 的中文翻譯有些殘缺，但對英文弱弱的我來說，介面有太多英文會讓心理壓力變得太大，果然還是得先更改語言：

接著就會看到介面的大部分都變成中文囉：

批次呼叫指定的 API

雖然 JMeter 支援了一堆測試功能，例如 TCP 之類的，但身為一個 CRUD 工程師，我們當然要用呼叫 API 來當作範例囉！

在先前的 API 筆記，我們已經建立過簡單的「查詢卡片」API：

GET https://localhost:44304/card

這次就用 Local 的這支 API 作為範例來操作 JMeter 吧。

建立 Thread Group

讓我們回到 JMeter，可以看到預設已經有一組測試計畫了：

而我們將會在測試計畫中加入幾個元素，利用這些元素的組合來達到我們測試 API 的目標。

首先我們會需要一個執行緒群組（Thread Group），用來告訴 JMeter 我們打算如何規劃這些 Thread 的行動。可以當作我們正在寫一個迴圈，現在才正要訂迴圈的內容而已。

讓我們在預設的測試計畫上按右鍵，新增一個執行緒群組：

接著應該就會看到我們的測試計畫下多了一個群組，並且進入了該群組的設定畫面：

這邊要特別注意的是右側的「執行緒屬性」，我們白話一點來說明：

執行緒數量：要打幾次
啟動延遲：幾秒內要打出去
迴圈次數：要打幾輪

例如說，我們想要模擬一百個使用者，在一秒內湧進網站，然後這狀況持續三輪，那就是：

執行緒數量 = 100
啟動延遲 = 1
迴圈次數 = 3

這時候也就決定了這次測試的總數（執行緒數量 * 迴圈次數）

此外，迴圈次數下的「Same user on each iteration」會讓每次迴圈時都用同一批使用者，如果想要每次都模擬全新的使用者，例如把前面的例子改成三百名使用者，分三批湧進網站，這時候就可以取消勾選。

而定時器則是讓我們設定在執行前先延遲多久、執行多久後自動停止，這邊例子不會用到，就不開啟了。

我們也可以設定 Throughput 來調整打出去的頻率，有興趣的朋友請參考 JMeter: 使用 Constant Throughput Timer 設置固定吞吐量

現在我們已經把執行緒群組建好了，讓我們指派任務給這個群組吧！

建立 Http Request

在執行緒群組上右鍵 > 新增，可以看到一排能指派給這群組的任務，其中「取樣」就是指我們這次的目標。這邊讓我們選擇「取樣 > HTTP 要求」：

接著可以看到 HTTP Request 的設定畫面，如同前面所說的，我們這次的目標是 GET https://localhost:44304/card，因此將 API 的資訊填到對應的欄位中：

在 API 的路由等資訊填好後，下方可以設定呼叫時要帶的參數，例如 Body 或上傳檔案等等。

補充：設定 Http Request Header

很多時候我們要測試的 API 會要求在 Header 帶著 Token 才能使用，這邊也記錄一下掛 Header 的做法。

對執行緒群組右鍵 > 新增，選擇「設定元素」，裡面就會有一票設定值可以選，這邊選擇「HTTP 標頭管理員」：

例如我們要指定 Post 的 Body 為 Json，就可以掛一個 content-type = application/json：

這樣就會加到 Header 上囉：

不過我們這次的範例只是一支簡單的查詢卡片，這邊就不用加上啦。讓我們進行下一步吧！

建立 Listener

當我們的小弟們去解決了目標之後，就必須要回來報告給我們知道。這邊讓我們一樣在執行緒群組上右鍵新增，並且選擇「接聽（Listener）」，先嘗試建立一個「檢視結果樹」：

除了檢視結果樹以外也可以新增別的試試看，方便打完 API 之後確認，這邊再加上一個「Summary Report」，現在群組應該會長得像這樣：

等等打完之後再來確認這兩頁的內容。現在讓我們戳戳看 API 吧！

開始執行測試

在最上面找到大家都很熟悉的綠色三角，戳下去就會執行這次的測試計畫，也就是照著剛剛的計畫烙一群小弟去揍 API

它旁邊還有發現不對勁時使用的 STOP，更旁邊的神奇掃把是用來在結束之後滅證用的清除結果：

總之，用力給他按下綠色三角！

這邊就先意思意思揍個一拳，執行之後就可以來看看我們的檢視結果樹：

可以看到結果樹中會顯示剛剛執行的結果，假設你打了兩百次這邊就會有兩百筆；右側則是這次 API 回傳的結果，通常都是看有沒有好好回 200 OK 就是了 xD

此外也可以切換上面的頁籤，看這次 API 回傳的內容：

接著切換到剛剛新增過的 Summary Report，可以看 API 回來的時間等資訊：

這樣就完成一次測試啦！

為了慶祝完成來打個一萬次 API 先（？）

小結

這次筆記了 JMeter 這套壓力測試工具的簡單使用方式，在大多數對 API 做測試的場合中，只需要新增幾個 JMeter 提供的元件就可以完成任務，可以說是相當方便。

同時 JMeter 也提供了更多進階場景時用到的工具，來幫助我們在 Request 發送前後進行處理：例如在這次工作上用到的場景來說，就需要從設定元素中新增 CSV Data Set Config 來從 CSV 讀出需要的資訊，利用 ${參數名稱} 的語法來把參數加到我們的 HTTP 請求：

又或是新增前置處理器，如 JSR223 PreProcesser 來撰寫 JavaScript 腳本，先對參數進行處理等等：

當然除了從 CSV 設定參數以外，JMeter 也提供了簡單的邏輯控制，像是從一數到十這種是完全沒問題的：

有這些工具可以進行組合，可以說是相當方便。但大多時候我們只會需要用到基本的 Http Request。有興趣嘗試的朋友可以參考 Yuanchieh’s Blog 的這篇：壓測工具：JMeter 使用教學 + 自定義變數使用，以及官方文件 Apache JMeter - User’s Manual 來試試，這邊就不再贅述。

雖然 JMeter 還是有一點小問題，例如那個只有一半的翻譯，還有跑在 Linux 的表現會比 Windows 好之類的現象

但這無損它是個功能完善又簡單使用的壓力測試工具。需要的時候還是可以打開 JMeter，簡單掛個執行緒群組就揍起來，同事 API 寫好就直接把它打爛，不亦樂乎。

~~雖然我的後端前輩最後跑去用更新更潮的 K6 了，嘖。我筆記都寫完了欸，讓我看看是有多潮……~~

那麼今天的筆記就到這邊，我們下次見！

參考資料與延伸閱讀

Sony WH-1000XM5 使用一週心得

Igouist (Igouist) — Sat, 01 Oct 2022 20:00:00 +0800

在某個風和日麗的午後，同事讓我試戴他的 XM5，當我戴上去聽了兩秒音樂，就明白我已經犯了錯，而且無法回頭。

過了幾天，這副耳機就出現在我家門口，到今天已經過了一週，就讓我來紀錄一下小小心得吧。

音質升級、降噪有感

我的上一副耳罩耳機是陪了我好多年、用到脫皮的 Avantree Audition Pro，因此整個升級感還蠻明顯的。

其中最有感的就是音質和降噪兩個部份。身為一個木耳仔，音質的升級也只能說出「哦哦！這個…比較厲害！」的心得，這邊就不獻醜了，總之我是聽得一個開心。

至於降噪的部份就真的是無線耳機第一梯隊，我所在的辦公室相當開放，同事間也經常討論，並且在入手耳機時還正逢隔壁施工。但當降噪開下去，真的有種隔離感，瞬間就只剩下音樂陪伴，令人相當滿意，貝多芬試了也會微笑。

通透的表現也很不錯，左側有實體按鍵能切換降噪／通透，使用上相當直覺。但因為習慣問題，說話時還是會把耳機摘下來，這時候會自動暫停音樂，還算貼心。

此外，APP 也有提供等化器調整，切換風格的感覺蠻明顯的，不過像我這種門外漢也就是調個心情愉快就放著了。到目前 APP 沒開過幾次，比較像是個徽章蒐集器：「恭喜你又多聽了一天！」

舒適、好戴、都是汗

聊完我覺得有感升級的部份，現在聊聊另一個同樣有感的部份：熱。

第一天拿到的時候興高采烈聽了一兩小時的歌，實在是相當舒適，耳朵和眼鏡都沒有什麼壓迫感，頭頂拉開之後也不夾頭，完全可以佩戴上好一陣子沒問題。

但一拿下來發現耳罩上整圈的汗，才發現事情不大對勁，耳朵彷彿洗了三溫暖。

剎那間我就明白，這東西是不能在我家這種冷氣很爛的環境下使用的，非得要到冷得要死的辦公室，那保暖起來才剛剛好。

除了熱以外，攜帶性也讓人不大習慣，畢竟這代無法摺疊，而耳機本體和收納包都挺大一個的，側背包根本放不下，要帶著走，乾脆直接戴在頭上。

小結

一句話總結：音質和降噪讓我這木耳很滿意，但又熱又大，想入手的朋朋呀，使用場景得好好考慮。

題外話，上一次介紹這些小東西是前年買外接螢幕的事兒了。那為什麼突然想寫這篇呢，原因非常簡單：

看到進版圖了嗎？這是我家的豬，我覺得超可愛，如果你沒看過，現在讓你看看。

在 Chrome 使用翻譯套件 ImTranslator 的嵌入式翻譯來逐行中英對照吧

Igouist (Igouist) — Sun, 18 Sep 2022 10:55:00 +0800

嗨各位朋朋，又到了替文章數灌水的好用工具時間！

今天要介紹的是 ImTranslator，它是一款 Chrome 的翻譯套件。由於有嵌入式翻譯（Inline Translator），意外地在辦公室的詢問度還蠻高的，這就來寫一篇介紹來推廣給和我一樣英文苦手的朋朋們！

首先讓我們到 Chrome 線上應用程式商店的 ImTranslator 頁面將套件安裝到瀏覽器中：

安裝完之後預設會是翻譯成世界語，因此我們要先到擴充功能選項調整一下語言：

可以看到左邊有四種翻譯模式，我們先把翻譯語言都調整一下：

這邊也可以更改翻譯來源，我個人是都用預設的 Google 翻譯。此外像是嵌入式翻譯結果的文字顏色也可以在這邊修改。

接著我們來看看這四種翻譯模式吧：

首先是我個人最常用的嵌入式翻譯（Inline Translator），只要將翻譯目標的句子反白起來，按下 Alt + C，就會在翻譯目標的句子後方插入翻譯結果：

如果想清除翻譯結果可以按下 Alt + X：

接著是彈出視窗（Pop-up Bubble），顧名思義就是彈出式視窗。不過由於我不喜歡彈一塊視窗出來擋畫面，平常都是關閉的，只有嵌入式翻譯會讓版面跑版的時候才從右鍵選單使用：

接著是窗口翻譯（ImTranslator），就是彈出視窗的獨立視窗版，好處是可以用滑鼠拖移：

最後是網頁翻譯（Webpage Translation），不過這功能就和 Chrome 右鍵的「翻譯成繁體（中文）」意思一樣，就不再贅述，我也沒用過。

看過一輪上面的翻譯模式後，應該可以發現這套件最香的還是嵌入式翻譯，可以中英對照對我這種不擅長英文又怕被機器翻譯幹掉術語的人來說真是一大救贖，善哉善哉。

~~我相信真的有人用中英對照來練習英文閱讀啦，但我是真的看不懂= =a~~

這邊就推薦給各位和我一樣的朋朋，省卻複製貼上到 Google 翻譯的時間吧！

參考資料（推坑來源）

ImTranslator 我選擇的 Firefox 即時翻譯套件，好看順手多功能 (playpcesor.com)

使用 Azure Functions + Line Notify 來定時提醒公車到站時間

Igouist (Igouist) — Mon, 12 Sep 2022 23:51:00 +0800

在上週的使用 Powershell + 工作排程器 + Line Notify 來定時提醒公車到站時間，我們利用工作排程器來定時觸發腳本，藉此用 Line 提醒我下班的公車還有多久才來。

做完之後靈機一動，對呀！最近上班挺常接觸到 Azure Functions 這個方便東東，不如就把這個小提醒給架設到 Azure Functions 上吧！

這樣就省卻了特定主機要開著掛工作排程器的困擾，又可以用香香的 Azure 工具來控制監聽的開關，豈不美哉。

如此如此這般這般，讓我們開始建立 Azure Functions 服務吧！

章節目錄

建立 Azure Functions 資源

Azure Functions 是 Azure 推出的一款無伺服器（Serverless）服務，簡單來說就是伺服器之類的麻煩事就交給 Azure 去處理，我們只要專心寫功能就好。對我這種愛寫小腳本的偷懶工程師來說，可以說是香到爆的服務。

小提醒：Azure Functions 是一款收費服務，使用前請務必確認定價。

在這篇文章撰寫當下，Azure Functions 有提供每月免費執行一百萬次的授權，對我們每天一次的公車通知來說綽綽有餘了（我們應該不會搭這麼多趟吧…？）

首先讓我們到 Azure 建立一個函數應用程式（如果用英文，請找 Azure Functions）：

接著進到建立 Functions 的頁面，讓我們先選好資源群組，並取個好名字

因為「MyFunctions」之類的都被取走了，這邊就直接取「林北ㄟ Functions」：

執行階段堆疊請選擇自己開發用的語言，我這邊使用 .Net 6 進行開發，作業系統則按照建議的選擇。

這邊要稍微注意方案的選擇！如同前面提到的定價，也可以參照 Microsoft Docs 的預估 Azure Functions 中的取用方案成本說明，裡面會有使用量、進階等方案的說明。

這次我們要做的只是簡單的提醒通知，所以就選費用最低的使用量計價就好囉～

按下確認後就會開始部屬：

部屬完成就可以前往我們建立的資源囉，可以在這裡確認記憶體、執行次數等資訊：

從左側的「函式」可以確認我們現在有哪些 Functions，當然目前還是空的：

接著就讓我們來撰寫第一個 Function 吧！

使用 Azure Functions 開發公車到站提醒服務

因為這篇的功能完全是使用 Powershell + 工作排程器 + Line Notify 來定時提醒公車到站時間的完美復刻版，因此我們要做的事情還是一樣：

每天下班前十分鐘（定時執行）
告訴我（通知功能）
下一班到達的公車時間（查詢資訊）

只是這次的功能使用 .Net 6 撰寫，並且使用 Visual Studio 為範例來記錄，定時功能則從臭臭又綁電腦的工作排程器改用香香 Azure Functions 的定時觸發功能。

建立 Azure Funtcions 專案

首先讓我們新增專案，內建已經有 Azure Functions 的範例可以使用：

取個好名字，這邊沿用剛剛開資源的命名：

接著就要選擇版本，這邊要注意 Azure Function 目前還有分出隔離版（Isolated）：

簡單來說，原本的 Azure Functions 和主機環境太耦合了，如果用到同一個套件不同版本就有可能翻車。因此推出了隔離式的 Azure Functions 讓我們可以乾乾淨淨地用。

想更了解隔離式版本的差異，可以參見：

由於 .NET on Azure Functions Roadmap 的示意圖：

明確指出將來的主軸會是隔離式（Isolated），因此我們這邊專案也選擇 .Net 6 已隔離的版本。~~這樣我往後抄起來比較方便~~

小提示：查詢 Azure Functions 相關資料時也要注意版本的差異！在 .Net 開發隔離式的 SDK 並不一樣，連最基本標示 Function 的語法，原本是 [FunctionName()]，隔離式也改成了更簡潔的 [Function()]，因此查資料或開發時要特別注意版本差異，避免被 IDE 畫了紅線卻搞不懂為什麼。

接著我們就可以選擇 Function 的觸發條件，因為我們要定時提醒，因此這邊選擇 Timer Trigger 就可以了：

同樣常用的還有當成 API 打的 Http Trigger，以及和我們上一次介紹過的 ServiceBus 一起使用的 Service Bus Queue/Topic Trigger 等等。

關於提供的觸發方式和程式碼範例，可以參照 Microsoft Docs 的 Azure Functions 中的觸發程序和繫結

最後因為我們選擇了 Timer Trigger，這邊提供我們直接設定時間。使用的是 NCrontab 格式，可以參考 NCRONTAB expressions 的說明，Visuat Studio 上也有簡短地介紹：

按照需求，我們希望下班前，也就是每天的 17:45 左右能提醒公車預估到站的時間。

NCrontab 和常見的 Crontab 差在多了第一個欄位來控制秒，因此這邊果斷直接使用 Cronitor 查一下，再往前加上一欄當作秒數即可。

補充：另一個香香工具 DevToys 也能迅速組裝和確認 Cron 語法呦！

每天的 17:45 在 Crontab 表示為「45 17 * * *」：

我們希望在 0 秒的時候觸發，因此轉 NCrontab 時需要在秒的位置指定 0，也就是「0 45 17 * * *」

但在填到 Azure Functions 要注意，在伺服器的時間會是 UTC+0。為了在台灣，也就是 UTC+8 的 17:45 觸發，因此將時間更改為「0 45 9 * * *」，否則 Line 就會在半夜通知你起來搭公車

這樣其他資訊的頁面就填寫完了，可以按下建立囉！

建立後會看到 Visual Studio 已經使用我們剛剛的設置建立了一個 Function 及 Timer Trigger，時間也填好了（如果後續還要調整時間，就修改 TimerTrigger 的值就好）：

public class Function1
{
    private readonly ILogger _logger;

    public Function1(
        ILoggerFactory loggerFactory)
    {
        _logger = loggerFactory.CreateLogger<Function1>();
    }

    [Function("Function1")]
    public void Run([TimerTrigger("0 45 9 * * *")] MyInfo myTimer)
    {
        _logger.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");
        _logger.LogInformation($"Next timer schedule at: {myTimer.ScheduleStatus.Next}");
    }
}

為了後續管理方便，我們先改個名。這邊就叫做 BusReminderFunctions 吧：

public class BusReminderFunctions
{
    private readonly ILogger _logger;

    public BusReminderFunctions(
        ILoggerFactory loggerFactory)
    {
        _logger = loggerFactory.CreateLogger<BusReminderFunctions>();
    }

    [Function("BusReminder-TimerTrigger")]
    public void RunTimerTrigger([TimerTrigger("0 45 9 * * *")] MyInfo myTimer)
    {
        _logger.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");
        _logger.LogInformation($"Next timer schedule at: {myTimer.ScheduleStatus.Next}");
    }
}

並且為了測試方便，我們再增加一個 HttpTrigger，這時候會需要先去 Nuget 安裝相關的套件

搜尋 Microsoft.Azure.Functions.Worker.Extensions 就會看到各種 Trigger，這邊就安裝一下 Http 需要的套件吧：

現在讓我們回到 Functions，增加一個 HttpTrigger，調整一下非同步，並建立一個私有方法 TrackBusAsync，讓 HttpTrigger 和 TimerTrigger 都去呼叫這個方法，這樣我們就可以定時觸發也可以手動觸發它，後續測試起來也比較方便：

[Function("BusReminder-TimerTrigger")]
public async Task RunTimerTrigger([TimerTrigger("0 45 9 * * *")] MyInfo myTimer)
{
    await TrackBusAsync();
}

[Function("BusReminder")]
public async Task<HttpResponseData> HttpTrigger(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req,
    FunctionContext executionContext)
{
    await TrackBusAsync();

    var response = req.CreateResponse(HttpStatusCode.OK);
    await response.WriteAsJsonAsync<object>(new { result = true });

    return response;
}

private async Task TrackBusAsync()
{
    throw new NotImplementedException();
}

補充：HttpTrigger 的參數有三個部份，可以拆分成：

授權層級：Anonymous, Admin 之類的，可參照授權層級

方法：Get, Post 之類的，沒指定就會是不限方法

路由：用來定義 API 路由，預設會拿 FunctionName，在這例子就是 BusReminder

都有指定的樣子會像這樣：
[HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = null)]

這樣事前準備就差不多了，讓我們開始撰寫邏輯部分吧！

呼叫 MOTC Api 查詢公車到站預估時間

首先我們需要取得公車到站預估時間，這部分跟上一期一樣就直接從公共運輸動態服務 MOTC Transport API 的「市區公車之預估到站資料」（EstimatedTimeOfArrival/City/{City}/{RouteName}）這支 API 取得就行了。

2024.11.25 更新：發現 MOTC 的 API 已經下架了，現在公車資訊已經被整合到運輸資料服務 TDX (Transport Data eXchange)，有要動手串公車資訊的朋友可能得觀察新版 API 再進行調整了 QQ

註：為了避免被查水表，以下就用台北的 307 號公車為例，並假設目標站點是「台北車站（忠孝）」

嘗試把縣市和公車路線名稱代入後，可以取得公車行經的站牌資訊，其中就有我們最想要的估計到站時間（秒）：

在這個步驟我們還會需要調整 $top 參數的筆數，順便取得我們要監聽公車到站的站牌 ID（StopId）以及行進方向（Direction）在這個例子中「台北車站（忠孝）」的站牌 ID 會是 15250

確保了資料來源之後，讓我們回到專案裡。

這次為了之後方便擴展，決定將公車名稱、站牌 ID 等查詢資訊放到組態裡。

註：接下來會使用到依賴注入以及讀取 Config 的 IOptions；對這兩項不太熟悉的朋友可以先看過去，並且在後續 BusReminderFunctions 的建構式裡把公車資訊寫死就好，並不會影響功能。

一般的 .Net 6 API 專案我們會把組態設定放到 appsettings.json 中，而在開發 Azure Functions 的時候，則會需要用到 host.json 和 local.settings.json：

其中 host.json 用來設定站台相關的組態，例如在先前調整 ServiceBus Trigger 的時候，我們就是在 host.json 修改重新傳遞訊息到 Azure Functions 的時間。

而 local.settings.json 則是讓我們在本機開發時使用，對應到線上的組態設定：

可以看到 Azure 上的組態有「應用程式設定」和「連接字串」兩個區塊，而在本機開發時會對應到「Values」以及「ConnectionStrings」：

有個大概的認識之後，現在讓我們填入一些值吧。

現在我希望能從組態中，使用 IOptions 取得查詢公車估計時間相關的設定，因此我先建立了一個 Class BusTrackerOption：

/// <summary>
/// 公車到站監聽設定
/// </summary>
public class BusTrackerOption
{
    /// <summary>
    /// 公車路線名稱
    /// </summary>
    public string RouteName { get; set; }

    /// <summary>
    /// 要預估到站的站牌 ID
    /// </summary>
    public int StopId { get; set; }

    /// <summary>
    /// 公車路線行進方向
    /// </summary>
    public int Direction { get; set; } = 0;
}

並且到 local.settings.json 加上組態。這邊要特別提到的是：原本我們在 appsettings.json 加上組態，會用這種階層式的寫法：

{
    "BusTracker": {
      "RouteName": "307",
      "StopId" : 15250,
      "Direction": 0 
    }
}

但我們前面已經看到了，在 Azure 上的組態實際上是一個單層的列表。因此我們會使用 __ 當作分隔符號來將設定攤平，並放到 local.settings.json 的 Values 裡（如果是連線字串就放到 ConnectionStrings 裡），也就是像這樣：

{
  "Values": {
    // ...這裡會有其他組態設定

    // 加上 BusTracker 的 參數，用 __ 來表示階層
    "BusTracker__RouteName": 307,
    "BusTracker__StopId": 15250,
    "BusTracker__Direction": 0
  }
}

接著讓我們到 Program.cs 來將 json 的設定值繫結到 BusTrackerOption，Section 名稱要記得和 json 中的階層名稱對上

// 注意 Azure Functions 的 settings.json 的階層要用 __ 來區隔
services.AddOptions();
services.Configure<BusTrackerOption>(hostContext.Configuration.GetSection("BusTracker"));

註：如果像我一樣開 .Net 6，只看到 HostBuilder 的朋友，可以自行加入 ConfigureServices((hostContext, services) => {}) 的部份來註冊，如下：

接著就可以回到我們的 BusReminderFunctions 來把 IOptions<BusTrackerOption> 注入進來：

public class BusReminderFunctions
{
    private readonly ILogger _logger;
    private readonly BusTrackerOption _busTrackerOption;

    public BusReminderFunctions(
        ILoggerFactory loggerFactory,
        IOptions<BusTrackerOption> busTrackerOption)
    {
        _logger = loggerFactory.CreateLogger<BusReminderFunctions>();
        _busTrackerOption = busTrackerOption.Value;
    }

    // ...略
}

對依賴注入還不太熟悉的朋友，可以在這邊的建構式裡宣告出 BusTrackerOption 並賦值即可。但還是推薦閱讀依賴注入的筆記來了解一下呦

現在公車路線等組態都準備得差不多了，只剩下回傳時候要用來接收資料的 Model 還沒開。這時候就直接偷懶，拿 MOTC Transport API 的 Swagger 打回來的 Json，直接到 Json2Cshrp 之類的轉換網站直接產生 C# Class 就好了：

記得轉換結果的 Class Root 要改個名稱，這邊就直接取名叫做 BusEstimateInfo 吧：

現在我們有傳過去的參數，也有接回來的 Model 了，讓我們來開一個私有方法，從 MOTC API 取回資料吧：

/// <summary>
/// 查詢公車估計到站時間
/// </summary>
/// <param name="routeName">路線名稱</param>
/// <param name="stopId">站牌 ID</param>
/// <param name="direction">去返程</param>
private async Task<BusEstimateInfo> FetchBusEstimateTime(
    string routeName,
    int stopId,
    int direction = 0)
{
    var api = $"https://ptx.transportdata.tw/MOTC/v2/Bus/EstimatedTimeOfArrival/City/Taipei/{routeName}";

    // 將站牌 ID 及路線方向 加入到查詢參數中
    var filter = $"stopId eq '{stopId}'";
    if (direction != 0)
    {
        filter += $" and direction eq {direction}";
    }

    var query = new Dictionary<string, string>()
    {
        ["$filter"] = filter,
        ["$top"] = 1.ToString(),
        ["$format"] = "JSON"
    };

    // 使用套件 Microsoft.AspNetCore.WebUtilities 提供的 QueryHelpers 
    // 直接組出帶 QueryString 的 Url
    var url = QueryHelpers.AddQueryString(api, query);

    // 建立 request；注意直接呼叫 API 會要求驗證
    // 必須將 Header 掛成瀏覽器才能吃到每日 50 次的呼叫額度
    var request = new HttpRequestMessage
    {
        Method = HttpMethod.Get,
        RequestUri = new Uri(url)
    };
    request.Headers.Add("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64)");

    using var client = new HttpClient();

    var response = await client.SendAsync(request);
    if (response.IsSuccessStatusCode is false)
    {
        throw new Exception(response.StatusCode.ToString());
    }

    var body = await response.Content.ReadAsStringAsync();
    var result = JsonSerializer.Deserialize<IEnumerable<BusEstimateInfo>>(body)?.FirstOrDefault();
    return result ?? throw new Exception("呼叫 API 失敗，無法取得估計到站資訊");
}

這支呼叫 API 的 Method 步驟相當簡單：組出參數，呼叫 API，取回資料。

這邊有偷懶不想組字串，直接使用 Microsoft.AspNetCore.WebUtilities 的 QueryHelpers.AddQueryString 來把 GET 的 QueryString 參數組到 Url 裡，不想多安裝一個套件的朋友也可以自己手動組。

註：MOTC 的文件有提到非會員一天有 50 次的免費 Swagger 呼叫次數，實測如果是從程式呼叫時會需要吃驗證，要掛 Header 假裝成瀏覽器才能取得資料，不確定是不是還有其他限制。如果是要給自己開發的工具或產品使用的話，還是可以考慮了解一下 MOTC 的會員制度。

註：這邊的 HttpClient 也可以直接改用注入 HttpClientFactory 的方式來製作。可以參照 Yowko’s Notes 的這篇：在 .NET Core 與 .NET Framework 上使用 HttpClientFactory

現在取得公車資料的 FetchBusEstimateTime 已經建好了，讓我們調整一下外面的 Trigger 和共通的私有方法，來把 BusTrackerOption 的資訊帶到參數裡吧：

public BusReminderFunctions(
    IOptions<BusTrackerOption> busTrackerOption,
    ILoggerFactory loggerFactory)
{
    _busTrackerOption = busTrackerOption.Value;
    _logger = loggerFactory.CreateLogger<BusReminderFunctions>();
}

[Function("BusReminder-TimerTrigger")]
public async Task RunTimerTrigger([TimerTrigger("0 45 9 * * *")] MyInfo myTimer)
{
    var routeName = this._busTrackerOption.RouteName;
    var stopId = this._busTrackerOption.StopId;
    var direction = this._busTrackerOption.Direction;

    await TrackBusAsync(routeName, stopId, direction);
}

[Function("BusReminder")]
public async Task<HttpResponseData> HttpTrigger(
    [HttpTrigger(AuthorizationLevel.Anonymous, "get", "post")] HttpRequestData req,
    FunctionContext executionContext)
{
    var routeName = this._busTrackerOption.RouteName;
    var stopId = this._busTrackerOption.StopId;
    var direction = this._busTrackerOption.Direction;

    await TrackBusAsync(routeName, stopId, direction);

    var response = req.CreateResponse(HttpStatusCode.OK);
    await response.WriteAsJsonAsync<object>(new { result = true });

    return response;
}

private async Task TrackBusAsync(
    string routeName,
    int stopId,
    int direction = 0)
{
    var busEstimateInfo = await FetchBusEstimateTime(routeName, stopId, direction);

    throw new NotImplementedException();
}

就像前面提到的，我們在這邊讓 TimerTrigger 和 HttpTrigger 取出 BusTrackerOption 的公車相關參數，例如公車路線名稱後，再傳遞到共用的 TrackBusAsync，現在第一部份的查詢公車資訊已經完工，就讓我們先添加上去。

註：這邊之所以要讓查詢參數交由外面決定，就是以後如果我想把 HttpTrigger 改成可以從外部呼叫 API 時可以指定公車路線之類的參數，又或者是將來要註冊多組公車路線到資料庫之類的改動時，可以不用再動「查詢公車到站資訊」之類的邏輯。~~畢竟懶惰的訣竅在於提早準備~~

發送 Line Notify

2024.10 更新: Line Notify 將於 2025 年 3 月停止服務（LINE Notify 結束服務公告），有看到這篇的朋朋請選擇一組新的通知服務來串吧 QQ

現在搞定取得公車資訊的段落了，接著就讓我們來撰寫發送 Line Notify 的部份吧。

這邊為了過程完整一點，就重播一下上次衝刺去申請 Line Notify Token 的過程吧：

當下一個直衝 Line Notify 高速申請權杖：

好的回想完畢，現在讓我們把拿到的 Line Notify Token 也丟到 local.settings.json 的 Values 裡方便管理：

{
  "Values": {
    // ...這裡會有其他組態設定

    // 加上 LineNotify 的 Token，用 __ 來表示階層
    "LineNotify__Token": "YOUR LINE NOTIFY TOKEN"
  }
}

一樣建立一個 Class，方便後續用 IOption 從組態中取得值：

public class LineNotifyOptions
{
    public string Token { get; set; }
}

接著到 Program.cs 來將 json 的設定值繫結到 LineNotifyOptions，Section 名稱要記得和 json 中的名稱對上：

services.Configure<LineNotifyOption>(hostContext.Configuration.GetSection("LineNotify"));

接著就可以回到我們的 BusReminderFunctions 來把 IOptions<LineNotifyOptions> 注入進來：

這樣從 Config 取得 Token 的準備就完成了，現在讓我們來撰寫傳送訊息的方法本體吧

發送 Line Notify 實際上就是傳送一個 Post 請求到 /api/notify，並將 Token 放到 Header 的 Authorization、訊息丟到 Body 就行了，因此我們可以直接把這方法包裝成接收到訊息就傳遞給 API：

/// <summary>
/// 發送 Line Notify 通知
/// </summary>
/// <param name="message">The message.</param>
/// <exception cref="System.Exception">發送失敗</exception>
private async Task SendLineNotify(string message)
{
    if (string.IsNullOrEmpty(_lineNotifyOptions.Token))
    {
        throw new Exception("取得 Line Notify Token 失敗");
    }

    const string lineNotifyApi = "https://notify-api.line.me/api/notify";
    var requestBody = new Dictionary<string, string>
    {
        ["message"] = message
    };

    var request = new HttpRequestMessage
    {
        Method = HttpMethod.Post,
        RequestUri = new Uri(lineNotifyApi),
        Content = new FormUrlEncodedContent(requestBody)
    };
    request.Headers.Add("Authorization", $"Bearer {_lineNotifyOptions.Token}");

    using var client = new HttpClient();
    var response = await client.SendAsync(request);

    if (response.IsSuccessStatusCode is false)
    {
        throw new Exception("Line Notify 發送失敗");
    }
}

現在我們也已經有了傳送訊息的方法，是時候把它們倆串起來了！

組合查詢公車資訊與發送到站通知

先把鏡頭回到我們讓 Trigger 們共用的 TrackBusAsync 方法：

private async Task TrackBusAsync(
    string routeName,
    int stopId,
    int direction = 0)
{
    var busEstimateInfo = await FetchBusEstimateTime(routeName, stopId, direction);

    throw new NotImplementedException();
}

可以看到我們已經嘗試取得公車資訊，現在我們要組裝訊息，然後傳遞到剛剛撰寫的 Line Notify 通知方法裡。

而我想要的訊息是這樣的：「您追蹤的公車 307 將在 10 分鐘後（18:00）抵達台北車站（忠孝）」

因此我會需要計算出剩餘的分數，以及抵達時間，再從前面拿到的公車資訊來組成訊息並傳遞到方法中：

private async Task TrackBusAsync(
    string routeName,
    int stopId,
    int direction = 0)
{
    var busEstimateInfo = await FetchBusEstimateTime(routeName, stopId, direction);

    // 將預估幾秒後抵達 轉換成 預估幾分鐘後抵達
    var estimateMin = new TimeSpan(0, 0, busEstimateInfo.EstimateTime).Minutes;
    
    // 取得台北時區的目前時間，並和預估秒數計算出預估抵達時間
    var timeZone = TimeZoneInfo.FindSystemTimeZoneById("Taipei Standard Time");
    var convertedTime = TimeZoneInfo.ConvertTime(DateTime.UtcNow, timeZone);
    var estimateTime = convertedTime.AddSeconds(busEstimateInfo.EstimateTime).ToString("HH:mm");

    var message = $"您追蹤的公車 {busEstimateInfo.RouteName.Zh_tw} 將在 {estimateMin} 分鐘後（{estimateTime}）抵達 {busEstimateInfo.StopName.Zh_tw}";
    await SendLineNotify(message);
}

這邊要特別注意取得時間的部份，因為在伺服器的時間會是 UTC+0，因此我們這邊使用 TimeZoneInfo.ConvertTime 轉換成台北時區的時間。

註：像這種丟到雲端平台的服務，會時常遇到時區時間的轉換。單純的時間轉換可以參照之前筆記的 C#: 時區轉換、民國西元、國曆農曆、中文月份週期

或是可以嘗試更優雅的 DateTimeOffset，請參考還在用 DateTime 嗎？試試 DateTimeOffset 吧 - demo小鋪

現在我們已經將前面撰寫的兩個小方法組裝起來，是時候來測試看看了！

本機測試 Functions

總之，啟動鍵先用力給它按下去：

接著就會看到小黑窗跑起來，告訴你已經啟動了哪些 Functions：

可以看到我們的 Http Trigger 以及 Timer Trigger

因為我們的 Http Trigger 有支援 GET，所以這邊直接複製 Api 網址丟到瀏覽器打看看就可以試囉：

這時候小黑窗也會記錄到這次呼叫：

看起來運行良好，該放上 Azure 上啦！

補充：在 Azure 上要看小黑窗的話，可以從左邊選單找到「監視 > 紀錄資料流」：

使用 Visual Studio 發佈到 Azure Functions

現在讓我們把寫好的 Functions 佈到前面申請的 Azure Functions 服務上運行。為了方便這邊就使用 Visual Studio 來示範，首先讓我們對專案點選發佈：

接著選取發佈目標，我們想要發到 Azure 雲端上：

接著會讓我們選擇目標，因為我們前面建立時的作業系統是選用建議的 Windows，因此選擇 Azure Functions (Windows)：

接著就可以選取符合條件的 Azure Functions，這邊當然是選擇我們前面建立好的「林北ㄟ Functions」

註：如果先前沒有建立過 Azure Functions 服務，發佈的時候也可以從 Visual Studio 中建立，可以說是相當貼心：

按下完成之後，我們的發佈檔就建立完囉！

這邊要特別注意的是，我們先前有在 local.settings.json 加入一些設定值，例如 BusTracker 的公車路線等設定。因此我們這邊可以順手同步到目標服務上，在裝載的右上角點開「管理 Azure App Service 設定」：

就可以看到我們目前在 Local 的組態設定值，以及 Azure 服務裡的組態設定值。這邊為了將 Local 的設定值同步上去，就直接按下「插入本機的值」：

註：按下「插入本機的值」並確定後，設定值就會同步到 Azure Functions 服務的組態中：

反過來說，如果沒有從本機同步上去，而是在 Azure 上設定組態也是完全 OK 的

現在一切就緒，讓我們按下發佈吧！

接著就可以看到我們撰寫的 Functions 被發佈上去，並且幫我們重啟了 Azure Functions 服務：

現在讓我們回到 Azure Functions 服務的函式看看：

可以確認我們撰寫的 Functions 已經出現囉！

回到概觀來複製一下我們 Azure Functions 的 Url：

並且加上我們的 HttpTrigger 路由 api/BusReminder 呼叫看看：

大功告成！

小結

終於把這個小提醒給上雲啦！唉呀不得不說 Azure Functions 真是香。

接下來只要下班前收到公車到站通知，然後在公車來之前下班就可以啦！

……只要在公車來之前下班，就可以……吧？

參考資料

使用 Powershell + 工作排程器 + Line Notify 來定時提醒公車到站時間

Igouist (Igouist) — Sat, 03 Sep 2022 14:40:00 +0800

事情發生在一個風和日麗的平凡下午：

我：（把手上的事情弄到一個段落再下班吧）

～～十分鐘過後～～

我：差不多可以走了，公車也差不多要來了叭？
公車：（一分鐘前離站）
我：(ﾟдﾟ)

這時候才明白愛恨情仇，最傷最痛是後悔。如果我早知道公車快到站了，也許我就不會錯過。

抱著這股傷痛，決定乾脆寫個小腳本，每天下班提醒我一下，避免重蹈覆轍。

綜上所述！目標是：每天下班前十分鐘，告訴我下一班到達的公車時間

因此至少能夠拆分成三個階段：

每天下班前十分鐘（定時執行）
告訴我（通知功能）
下一班到達的公車時間（查詢資訊）

那麼，我們開始吧！

章節目錄

使用 MOTC API 服務取得公車資訊

首先，最重要的是要有資料來源。幸好我們先前在 Api 筆記的時候，就有介紹過公共運輸動態服務 MOTC Transport API，我們只需要使用這組 API 就能輕鬆拿到公車資訊了，感謝開發該服務的朋朋。

2024.11.25 更新：發現 MOTC 的 API 已經下架了，現在公車資訊已經被整合到運輸資料服務 TDX (Transport Data eXchange)，有要動手串公車資訊的朋友可能得觀察新版 API 再進行調整了 QQ

我們的場景是在辦公室查詢下一班目標公車到站時間，比對了 Swagger 上提供的中文敘述後，決定嘗試看看「市區公車之預估到站資料」（EstimatedTimeOfArrival/City/{City}/{RouteName}）這支 API

註：為了避免被查水表，以下就用台北的 307 號公車為例，並假設目標站點是「台北車站（忠孝）」

嘗試把縣市和公車路線名稱代入後，可以取得公車行經的站牌資訊，其中就有我們最想要的估計到站時間（秒）：

接著讓我們調整一下參數，把取前幾筆的 $top 調大一點，來取得我們目標站點台北車站的站牌 ID：

有了站牌 ID，我們就可以根據官方提供的查詢語法來篩選出目標站牌：

如果有需要指定回程，也可以再加上 and direction eq 1 的條件。

如此一來我們就可以呼叫 MOTC API 來取得目標站牌＋指定公車的到站估計時間囉：

註：沒有申請會員的話有每日 50 次的使用上限，不過這次的目標也就下班打那一次，十分足夠了 XD

使用 Powershell 呼叫 API 取得資料

現在已經保障了資料來源，接下來就是要有個腳本來去打 API 拿資料回來囉！

基於懶惰方便的原則，決定用 Powershell 寫個小東西直接打資料回來就好。

這邊就直接用路線名稱和站牌 ID 來串 Uri，並且直接用 Invoke-RestMethod 來呼叫 API 吧：

$busName = '307' # 公車路線名稱
$stopId = 15250  # 站台 ID

# 呼叫 MOTC API 取得公車資訊
$uri = "https://ptx.transportdata.tw/MOTC/v2/Bus/EstimatedTimeOfArrival/City/Taipei/$($busName)?%24filter=StopId%20eq%20'$stopId'&%24top=1&%24format=JSON"

$response = Invoke-RestMethod -Uri $uri

# 把結果轉成 Json 確認一下
$response | ConvertTo-Json

小提醒：原本我們下的 $filter = StopId eq '15250' 的參數，其中 $ 和空白符在 Uri 會轉換成 HTML 編碼的 %24($) 和 %20(空白)，並不是亂碼，請不要緊張

另存成 .ps1 檔案來測試一下：

看來查詢資料已經沒有問題了，接下來就是通知快要下班的我了

使用 Powershell 彈出通知視窗（初版）

第一次嘗試採用了彈跳視窗，想了一想還是順手記錄下來好了

首先將我們目標的 EstimateTime 取出來，然後顯示還有幾分鐘到站、預計幾點幾分到站

最後用 Wscript.Shell 來顯示彈跳視窗：

$estimateSec = $response.EstimateTime

# 組裝要顯示的訊息
$estimateMin = $estimateSec / 60
$estimateTime = (Get-date).AddSeconds($estimateSec).ToString("HH:mm")
$message = "Bus $($busName) - EstimateTime: in $([Math]::Floor($estimateMin)) minute(s), $estimateTime"

# 使用彈跳視窗將預計抵達的時間列印出來
$wshell = New-Object -ComObject Wscript.Shell
$wshell.Popup($message)

雖然運作順利，但是……

總覺得有點不是很好看啊，而且工作到一半在畫面正中間跳出這個會煩死吧囧

使用 Powershell 傳送 Line Notify

2024.10 更新: Line Notify 將於 2025 年 3 月停止服務（LINE Notify 結束服務公告），有看到這篇的朋朋請選擇一組新的通知服務來串吧 QQ

就在此時一個靈光乍現，對呀我之前爬訂便當的時候不是用過 Line Notify 嗎！

當下一個直衝 Line Notify 高速申請權杖：

複製權杖之後，衝回 Powershell，前人教學抄起來，Invoke-RestMethod 就直接打下去：

# 使用 Line Notify 傳送通知
$lineUri = 'https://notify-api.line.me/api/notify'
$lineToken = 'Bearer YOUR_LINE_TOKEN'
$header = @{ Authorization = $lineToken }
$body = @{ message = $message }
Invoke-RestMethod -Uri $lineUri -Method Post -Headers $header -Body $body

Line 也不負期望地彈出來：

大功告成！搞定拿資料和通知的部分啦～

補充：如果訊息內容有使用中文的朋友，請注意編碼問題。必須存成 Utf-8 with BOM，否則會出現亂碼：

這時候就需要更改編碼為 Utf-8 with BOM；

再重新嘗試一次就會正常了：

原本卡在這步搞不定，正好黑暗執行緒大大發了篇 PowerShell .ps1 檔 UTF-8 編碼問題之變形錯誤，才知道 PowerShell 5.x 有編碼解析的問題，改成 Utf-8 with BOM 順利完工。這邊補充給各位朋朋，望周知

到這邊 Powershell 的部份就處理好了，目前會長這樣：

$busName = '307' # 公車路線名稱
$stopId = 15250  # 站台 ID

# 呼叫 MOTC API 取得公車資訊
$uri = "https://ptx.transportdata.tw/MOTC/v2/Bus/EstimatedTimeOfArrival/City/Taipei/$($busName)?%24filter=StopId%20eq%20'$stopId'&%24top=1&%24format=JSON"
$response = Invoke-RestMethod -Uri $uri
$estimateSec = $response.EstimateTime

# 組裝要顯示的訊息
$estimateMin = $estimateSec / 60
$estimateTime = (Get-date).AddSeconds($estimateSec).ToString("HH:mm")
$message = "Bus $($busName) - EstimateTime: in $([Math]::Floor($estimateMin)) minute(s), $estimateTime"

# 使用 Line Notify 傳送通知
$lineUri = 'https://notify-api.line.me/api/notify'
$lineToken = 'Bearer YOUR_LINE_TOKEN'
$header = @{ Authorization = $lineToken }
$body = @{ message = $message }
Invoke-RestMethod -Uri $lineUri -Method Post -Headers $header -Body $body

使用工作排程器定時執行 Powershell 腳本

秉持著前面選擇 Powershell 的偷懶簡單精神，這邊的定時執行就直接使用 Windows 內建的工作排程器來處理：

因為我們的場景相對簡單，只有要在特定時間幫我們呼叫 Powershell 腳本，因此直接選擇「建立基本動作」

接著讓我們選擇每週，並指定平日的時候再執行：

最後選擇啟動程式，讓工作排程器開啟 Powershell 並呼叫我們的腳本：

這邊的「程式或指令碼」輸入 powershell，接著在「新增引數」的部份告訴 Powershell 我們要執行的腳本 -File "C:\Scripts\BusReminder.ps1"（記得換成你的腳本路徑呦）

註：沒有調整過執行原則的朋友們，可以在引數上加入 -ExecutionPolicy Bypass 來關閉警告，也就是 -ExecutionPolicy Bypass -File "C:\Scripts\BusReminder.ps1" 這樣子的感覺

註：如果跟我一樣會把腳本做成 Function 並存成 psm1 檔案的朋朋，這邊的引數會需要變成跟 Profile 一樣的處理方式，先 Import 進來再呼叫方法（這邊假設為 Run-BusNotify()）例如，：Import-Module "C:\Scripts\BusReminder.psm1";Run-BusNotify;

接著只需要完成就可以在排程中找到囉，馬上就來執行看看是不是正常運作吧：

大功告成！

後日談

自從有了公車到站提醒後，下班再也沒有煩惱了呢

提醒：公車還有十分鐘　
我：（還有十分鐘耶，把手上的事情弄到一個段落再下班吧）
～～弄了十五分鐘～～
公車：（離站）
我：(ﾟдﾟ)

這時候才明白科技終究是有極限的。

參考資料

菜雞抓蟲：Azure Functions ServiceBus Trigger 執行過久時會重複觸發 Functions

Igouist (Igouist) — Sat, 27 Aug 2022 10:09:00 +0800

TL;DR

當發現需要執行很久的 ServiceBus Trigger Function 有重複執行的情況出現時，可以嘗試到官方的 Host.json 設定指引，按照 SDK 版本找到對應的「訊息鎖定最大持續時間」設定，例如 maxAutoLockRenewalDuration（延伸模組 5.x+）或 maxAutoRenewDuration（Functions 2.x），並加入專案的 Host.json

因為 ServiceBus 在傳遞訊息之後，如果超過一段時間（MaxAutoRenewDuration）內沒有得到回應，就會解除信件的鎖並嘗試重新傳遞，這時候如果原先的 Function 仍在執行，就會一前一後重複執行 Function 並發生許多光怪陸離的事，例如寫入兩筆資訊、重複複製資料之類的。

建議如果調整了有 ServiceBus Trigger Function 的 Azure Functions Timeout 設定時，或是發現某支 ServiceBus Trigger 的 Functions 執行時間過長，就要一併注意 MaxAutoRenewDuration 的設定，避免重複執行的情況出現。

事發原由

工作時將一段需要呼叫其他 API、執行相當久的程式片段搬上 Azure Functions，並使用 Service Bus 來傳遞訊息觸發 Functions 執行，這時卻發現 Function 被執行了兩次！

現在就讓我們來重建當時的情況吧。首先我們有個 Service Bus Trigger 的 Azure Function，這邊就直接從 Visual Studio 提供的已隔離（Isolated）範本進行建立。

為了重現執行很久的特點，我們讓它 Delay 個八分鐘，並在開始和結束的時候告訴我們一下：

/// <summary>
/// ServiceBus Trigger 測試用 Function
/// </summary>
/// <param name="myQueueItem">My queue item.</param>
[Function("ServiceBusTriggerSample")]
public async Task Run(
    [ServiceBusTrigger(
        queueName: "%QueueName%",
        Connection = "ServiceBus")]
    string myQueueItem)
{
    _logger.LogInformation("開始處理訊息: {myQueueItem}", myQueueItem);

    await Task.Delay(new TimeSpan(0, 8, 0));
    
    _logger.LogInformation("結束處理訊息: {myQueueItem}", myQueueItem);
}

並且簡單地用之前 Service Bus 文章的範例送個 “Hello” 進去 Queue 裡，準備觸發 Function：

async Task Main()
{
	var context = "Hello!";
	
	await using var client = new ServiceBusClient(_connectionString);
	await using var sender = client.CreateSender(_queueName);
	var message = new ServiceBusMessage(context);
	await sender.SendMessageAsync(message);
}

在 Function 接收到訊息後，讓我們觀察 Console：

可以發現第一次執行尚未結束的時候，大概經過五分鐘就又執行了第二次！

調整訊息鎖定最大持續時間

原先以為是 Function 執行失敗導致 ServiceBus 重新傳遞之類的狀況，但找了老半天沒有頭緒，嘗試了調整一些設定也沒有起色，陷入了深深的混亂

幸好天無絕人之路，最終在 Stackoverflow 海巡的時候了發現一線生機！

原來 Azure Functions 的 Service Bus Trigger 有個「訊息鎖定最大持續時間」設定！

當 Service Bus 傳遞訊息到 Function 的時候，Function 會根據執行結果告訴 Service Bus 該訊息要標記成功或是失敗；但如果訊息就這麼一去不回時，Service Bus 會先觀望一下，直到超過了「訊息鎖定最大持續時間」就會下令解除訊息的鎖定，嘗試重新傳遞。

這次的事件就是因為我們即使調長了 Timeout 時間，但當該 Function 執行超過預設的鎖定時間（五分鐘）時，Service Bus 再度傳遞了訊息，才導致 Function 重複被執行而造成各種奇怪的資料錯誤

那麼這個「訊息鎖定最大持續時間」怎麼設定呢？我們可以參照官方的 Host.json 設定指引，按照 SDK 版本找到對應的「訊息鎖定最大持續時間」設定，例如 maxAutoLockRenewalDuration（延伸模組 5.x+）或 maxAutoRenewDuration（Functions 2.x），並加入專案的 Host.json。

現在讓我們在範例專案加入 maxAutoRenewDuration 的設定，這邊就改成比前面的執行時間八分鐘更長的十分鐘：

接著再重新傳遞一次訊息：

可以看到過程中沒有重新傳遞訊息了，大功告成！

總之，學到了調整 ServiceBus Trigger Function 的 Azure Functions Timeout 設定時，或是發現某支 ServiceBus Trigger 的 Functions 執行時間過長，就要一併注意 MaxAutoRenewDuration 的設定，避免重複執行。

如此如此，這般這般，一天又平安的過去了，感謝 Stackoverflow 大大們的努力。

參考資料

DevToys —— 開發人員的瑞士刀工具箱

Igouist (Igouist) — Sat, 20 Aug 2022 08:00:00 +0800

嗨各位朋朋，又双叒叕到了「同事推薦的好用工具」時間！

今天要介紹的是 Devtoys：這是一套包含了許多貼心小工具的工具箱，例如 UUID 產生器、Base64 編碼解碼、JSON Format 都可以在這邊找到，省下 Google 這些小工具的時間。

進入官網或 Store 下載之後，點開就能在畫面上看到一整堆小工具：

左邊的工具列也有工具分類和搜尋可以使用，具體有哪些工具這邊就不再贅述。可以到 Github 上看一下工具列表，或是就直接下載下來看看更清楚：

例如說當我原本複製了一坨 Json，為了保護眼睛和心靈，我就得上網先找個 Json Formatter 來轉一下；現在我知道 Devtoys 就有，直接打開來用就可以。

如果真的很常用到的工具，也可以加到最愛，就會直接出現在左上角的列表中：

同時 DevToys 也支援釘選到 Windows 的「開始」功能表，如果真的很常用也可以直接釘起來：

其他遇到的場景還有：複製了 JWT Token 想快速解開、想從 Unix 時間戳轉出時間等等

例如我個人最近常跟排程類的服務打交道，就會需要時常調整 Crontab 語法，而 DevToys 當然也有提供工具來幫助我們迅速確認 Cron 的執行時間。

像這種時候只要先確認一下 DevToys，也許就能找到對應的工具，下次再遇到就可以省下找工具的時間，可謂是方便方便。

那麼這次的小工具分享就到這邊，~~再度成功一個工具水一篇文~~，推薦大家下載試試！

Ｑ：這類小工具箱還蠻多的吧？為什麼挑這款呢

Ａ：因為它好看啊，好看就完事了

使用 Azure Service Bus 來建立簡單的訊息佇列（Message Queue）吧

Igouist (Igouist) — Sat, 13 Aug 2022 16:50:00 +0800

在工作上遇到在兩個 Azure 工具間建立訊息佇列（Message Queue）的需求，因此接觸到了 Azure Service Bus（中文：服務匯流排 ~~燴牛排？~~），在前輩的協助下建立了一組簡單的 Demo，這就來筆記一下。

什麼是訊息佇列（Message Queue, MQ）

首先讓我們簡單認識一下訊息佇列。假設我們有生產者和消費者兩個服務，其中生產者負責產生資料，而消費者負責消費這些資料：

各位也可以這樣理解：生產者就像是壽司師傅，他會不斷的捏壽司出來；而這時候來了一位大胃王顧客，他就是消費者，會不斷地把壽司吃掉

大概對這兩個角色有點認識就行了。那麼，假設我們有兩組 API 服務：其中一個是負責寫入 Log 的服務，而另一個是產品服務。

產品服務會將 Log 內容丟給 Log 服務去紀錄 Log，這時候產生了這些日誌資料的產品服務就是生產者，而消費這些日誌資料去寫 Log 的服務就是消費者。

也就是：產品服務（生產者） —— 資料 —> Log 服務（消費者） 這樣的狀況。

然而像這樣直接相依的兩個服務，可能就會遇到一些問題：像是消費者突然掛掉，導致生產者也跟著掛掉；又或是消費者的變動和擴展會連帶影響到生產者必須跟著變動等等。

這樣說可能有些模糊。就以上面提到的 Log 服務來說，在直接呼叫 API 的情況下，我們常常會需要在產品服務中直接明確寫出 Log 服務的資訊，像是站台位址、API 路由之類的。

但當 Log 服務的站台或方法有變動，我們就被迫要修改產品服務對應的程式碼；而如果我們今天想要擴展 Log 服務的站台，就會需要修改產品服務裡關於 Log 服務的資訊。

而今天如果 Log 服務短暫掛掉了，可能就會連帶讓我們的產品服務一起掛掉，就算有進行簡單的錯誤處理，當時該記的 Log 內容也就遺失了。

那面對這些問題的時候怎麼辦呢？這時候我們就可以在中間加一條佇列：

用前面的壽司店來說就是這樣（很堅持要用壽司舉例）：

我們加入訊息佇列之後得到的好處有：

解除耦合
- 生產者不需要知道消費者的資訊，消費者的變動也不會直接影響到生產者
提高擴展性
- 即使我們要增加消費者的數量，變成三個消費者來處理這些資料，也只要讓佇列處理轉發就好，而不用影響生產者
非同步
- 生產者現在只要把訊息丟到佇列就可以回頭繼續做自己的事了，不用管也不用等待消費者處理這些訊息
緩衝
- 佇列讓消費者多了一段緩衝區，即使消費者忙不過來，也有佇列可以讓訊息好好排隊

除此之外還可以玩一些花式處理，例如藉由佇列來做到限制流量等等，此處先按下不表。

現在我們大概知道訊息佇列在幹嘛了。接著就讓我們來玩玩 Azure Service Bus 這個訊息佇列服務吧！

想更了解 Message Queue 的朋友，也可以閱讀以下的參考資料呦：

[基礎觀念系列] 讓任務排隊吧：Message Queue — (1) - 莫力全 Kyle Mo

什么是消息队列？ - Java3y (qq.com)

消息队列（Message Queue）基本概念 | NingG 个人博客

Message Queue - (1) - iT 邦幫忙 (ithome.com.tw)

Producer Consumer 模式 - iT 邦幫忙 (ithome.com.tw)

什麼是訊息佇列？ (amazon.com)

建立 Azure Service Bus 資源

小提示：Azure Service Bus 是一項收費服務，你可能會想先了解定價

首先讓我們先到 Azure，建立一個新的資源：

找到 Service Bus 並新建它：

接著選擇要掛資源的帳戶和群組後，替我們的 Service Bus 取個好記的名字。

這邊示範的方案當然就直接選最便宜的 XD

除了基本設定以外，這邊還能變更最低 TLS 版本（維護老舊專案者注意，或是準備踩雷）等等，可以頁籤都戳一戳。

確認之後就可以勇敢按下「審核 + 建立」囉！

按下後會部署個幾分鐘，部屬完畢之後就可以直接前往資源：

抵達我們的 Service Bus 資源頁面：

這樣我們就成功建立 Service Bus 啦！

建立佇列（Queue）

接著就讓我們來建立一條佇列吧，首先讓我們再看一眼微軟把拔提供的佇列概念圖：

回到 Azure 的 Service Bus 資源頁面，讓我們在畫面上點選建立佇列：

並且取個好名字，等等發訊息的時候會用到：

這邊會需要注意一下「最大傳遞計數」（Maximum Delivery Count），簡單來說就是這封訊息會嘗試傳遞幾次，如果超過次數都沒有傳遞成功就會被丟到無效信件。可以參閱服務匯流排寄不出的信件佇列的概觀中的「最大傳遞計數」小節

這篇我們不會用到下面選項的資料分割、到期自動轉無效信件等功能，有興趣的朋友可以再自己研究一下呦～

建立完就會出現在我們 Service Bus 的頁面下方囉：

取得 ServiceBus 的連線字串

接著為了讓我們後續可以順利連線，先到左邊的 「設定 > 共用存取原則」拿到我們的連線字串：

這邊直接使用預設的原則，如果有需要控管不同使用者的權限，例如說某組連線字串只能接收或讀取等等，也可以在這邊新增原則來管理。

將訊息放入佇列

現在 Queue 已經建立起來了，接著就是要嘗試把訊息丟到 Queue 裡面囉！

為了方便測試，這邊就採用 Visual Studio 內建的 API 樣板，直接在 Controller 簡單建立一個範例，要實際應用在專案中的朋友請再依據專案架構自行調整。

那麼就讓我們開始吧，首先我們會需要安裝 Azure.Messaging.ServiceBus 這個套件包：

接著是我們本次的範例用 Controller，以及尚未實作傳送訊息的 Function：

/// <summary>
/// Service Bus Queue 示範用 Controller
/// </summary>
[ApiController]
[Route("[controller]")]
public class QueueController : ControllerBase
{
    /// <summary>
    /// 將訊息放入佇列
    /// </summary>
    [HttpPost]
    public async Task Enqueue([FromBody] string context)
    {
        // 我們要在這裡實作傳送訊息到 Queue 的方法
    }
}

傳送一則訊息到佇列

接著讓我們來傳送訊息吧，這邊會需要：

用 ServiceBus 的連線字串建立 ServiceBusClient
用 Queue 的名稱，從 ServiceBusClient 建立 ServiceBusSender
用 ServiceBusSender 來傳送訊息到 Queue

/// <summary>
/// 將訊息放入佇列
/// </summary>
[HttpPost]
public async Task Enqueue([FromBody] string context)
{
    // 用 ServiceBus 的連線字串建立 Client
    // 連線字串可以在 Azure ServiceBus 頁面的共用存取原則找到
    // ServiceBusClient 用完記得要呼叫 DisposeAsync() 來關掉
    // 或是直接使用 await using 包起來
    var connectionString = "YOUR SERVICE BUS CONNECTION STRING";
    await using var client = new ServiceBusClient(connectionString);

    // 傳遞 Queue 的名字給 CreateSender 方法來建立 Sender
    // 和 ServiceBusClient 一樣，有提供 DisposeAsync 方法來關閉
    // 或是直接使用 await using 包起來
    var queueName = "YOUR QUEUE NAME";
    await using var sender = client.CreateSender(queueName);

    // 將要傳送的訊息包裝成 ServiceBusMessage
    // 並使用 ServiceBusSender.SendMessageAsync 傳送出去
    var message = new ServiceBusMessage(context);
    await sender.SendMessageAsync(message);
}

提醒一下將來會跑回來複製貼上的我和各位朋朋：記得把連線字串跟佇列名稱改成你的！

現在讓我們來呼叫ＡＰＩ，丟個 "Hello" 進去試試：

接著到 Azure Service Bus 的 Queue 介面瞧瞧：

Queue 也確實收到一則訊息了，看來我們成功把 Hello 丟進去啦！

傳送一批訊息到佇列

當然在實務上，我們有時候會想要傳一卡車的訊息；例如我們剛處理完一批客戶，想把它們丟到佇列去讓另一個服務做點事，這時候如果還得一封一封塞訊息就有點怪怪的。

雖然我們可以直接粗暴地把 Sender 的 SendMessageAsync 加個 s 變成 SendMessagesAsync，這樣它就能接收串列的 IEnumerable<ServiceBusMessage> 了（真貼心啊 Azure）

不過，我們還可以選擇使用 ServiceBusMessageBatch 這個工具來幫我們一次發他個一批訊息。

這邊也示範一下。~~讓我之後可以回來抄~~

/// <summary>
/// 將一堆訊息放入佇列
/// </summary>
/// <param name="context"></param>
/// <returns></returns>
[HttpPost("Batch")]
public async Task EnqueueBatch([FromBody] string context)
{
    // 把訊息重複個十次，假裝我們有很多訊息
    var contexts = Enumerable.Repeat(context, 10);
    
    // 和單則訊息的場合一樣：先建立 Client 及 Sender
    var connectionString = "YOUR SERVICE BUS CONNECTION STRING";
    await using var client = new ServiceBusClient(connectionString);
    
    var queueName = "YOUR QUEUE NAME";
    await using var sender = client.CreateSender(queueName);

    // 從 Sender 來建立一批訊息（類似郵差包的感覺）
    using var messageBatch = await sender.CreateMessageBatchAsync();

    // 將訊息逐一嘗試放到這批訊息中（把信塞到郵差包的感覺）
    foreach (var text in contexts)
    {
        var message = new ServiceBusMessage(text);
        if (messageBatch.TryAddMessage(message) is false)
        {
            throw new Exception("放入訊息失敗");
        }
    }

    // 把整個郵差包丟出去
    await sender.SendMessagesAsync(messageBatch);
}

直接多十條訊息，看起來沒問題：

傳送物件到佇列

Ｑ：我要傳的東西不是 string 而是物件怎麼辦？

Ａ：山不轉路轉，就用 JsonSerializer.Serialize 轉成 Json 再傳。

好的結案。

從佇列取出訊息

現在我們已經可以把訊息丟到 Queue 中了，接下來當然就是要拿出來囉！

拿出來的時候也有幾個不同的姿勢，接著就讓我們一一介紹下：

從佇列中讀取一則訊息

就像我們要寫入訊息的時候，要從 ServiceBusClient 建立一個 ServiceBusSender 一樣，當我們要寄送訊息的時候，也要從 ServiceBusClient 建立一個 ServiceBusReceiver 來幫我們處理訊息：

/// <summary>
/// 取出佇列中的單則訊息
/// </summary>
/// <returns></returns>
[HttpGet("Receive")]
public async Task<string> Receive()
{
    // 和發送訊息的場合差不多：先建立 Client 及 Receiver
    var connectionString = "YOUR SERVICE BUS CONNECTION STRING";
    await using var client = new ServiceBusClient(connectionString);

    // 和前面的 ServiceBusSender 一樣，有提供 DisposeAsync 方法讓我們用完時關閉
    // 或是直接使用 await using 包起來
    var queueName = "YOUR QUEUE NAME";
    await using var receiver = client.CreateReceiver(queueName);

    // 使用 ReceiveMessageAsync 來把訊息讀取出來
    var message = await receiver.ReceiveMessageAsync();
    var body = message.Body.ToString();

    // 告訴 Service Bus 這個訊息有成功處理了
    await receiver.CompleteMessageAsync(message);
    return body;
}

過程相當的簡單，只需要叫 ServiceBusReceiver 幫忙拿出來就好。現在讓我們呼叫試試：

成功取得我們前面放進去的訊息囉！

從佇列中持續讀取訊息

前面提到的 ServiceBusReceiver 可以從佇列中取出一則訊息，但大多時候訊息的接收方是被動的，也就說接收方其實並不知道發送方傳訊息了沒、現在有沒有訊息，更不用說主動去取出訊息了。

因此通常的作法是採用被動接收訊息再進行處理的方式：事先註冊好處理訊息的事件，當有訊息進來的時候就按照指示去進行處理，這時候我們就會需要用到 ServiceBusProcessor。

並且當 ServiceBusProcessor 建立之後，我們會需要告訴他兩件事：我們想怎麼處理訊息、出錯的時候該怎麼辦。

這些都設定完之後，ServiceBusProcessor 就會上工站崗。只要有訊息進來，它就會按照我們給的小抄去執行

整理一下，我們接收 Service Queue 的訊息時會需要：

用 ServiceBus 的連線字串建立 ServiceBusClient
用 Queue 的名稱，從 ServiceBusClient 建立 ServiceBusProcessor
設定接收到訊息之後的處理方式 ProcessMessageAsync
設定出錯時的處理方式 ProcessErrorAsync
讓 ServiceBusProcessor 持續接收訊息

/// <summary>
/// 取出佇列中的訊息
/// </summary>
/// <returns></returns>
public async Task Dequeue()
{
    // 和發送訊息的場合差不多：先建立 Client 及 Processor
    var connectionString = "YOUR SERVICE BUS CONNECTION STRING";
    await using var client = new ServiceBusClient(connectionString);

    // 和前面的 ServiceBusSender 一樣，有提供 DisposeAsync 方法讓我們用完時關閉
    // 或是直接使用 await using 包起來
    var queueName = "YOUR QUEUE NAME";
    await using var processor = client.CreateProcessor(queueName);

    // 告訴 Processor 我們想怎麼處理訊息
    processor.ProcessMessageAsync += MessageHandler;
    processor.ProcessErrorAsync += ErrorHandler;

    // 讓 Processor 上工，開始接收訊息
    await processor.StartProcessingAsync();

    // 實際上會掛著讓 processor 一直處理送來的訊息
    // 這邊示範而已就意思意思跑個一下下
    await Task.Delay(1000);

    // 讓 Processor 下班休息
    await processor.StopProcessingAsync();
}

/// <summary>
/// 處理佇列訊息
/// </summary>
/// <returns></returns>
private static async Task MessageHandler(ProcessMessageEventArgs args)
{
    // 從訊息的 Body 取出我們發送時塞進去的內容
    var message = args.Message.Body.ToString();

    // 對訊息內容做你想做的事
    // 這邊就印出來看個一眼意思意思
    Console.WriteLine(message);

    // 告訴 Service Bus 這個訊息有成功處理了
    await args.CompleteMessageAsync(args.Message);
}

/// <summary>
/// 處理佇列錯誤訊息
/// </summary>
/// <returns></returns>
private static async Task ErrorHandler(ProcessErrorEventArgs args)
{
    // 從訊息中取出錯誤訊息$$
    var exception = args.Exception.ToString();

    // 對訊息做一些錯誤處理，例如存到日誌系統之類的
    // 這邊也印出來看個一眼意思意思
    Console.WriteLine(exception);
}

接著就讓我們呼叫看看：

可以看見我們確實收到了前面發送的「Hello」，接收大成功！

補充：在 ServiceBus Explorer 確認訊息

除了直接在程式中接收訊息以外，我們在 Azure 的頁面上其實也能確認傳遞中的訊息內容。

首先到佇列左側的列表找到「Service Bus Explorer」，就可以確認目前佇列和無效信件中的訊息數量。

點下從頭查看後，就可以看見訊息列表的內容，並點擊訊息查看本文和屬性：

在找問題的時候還蠻好用，想確認訊息內容的時候可以試試。

建立主題（Topic）

除了佇列（Queue）以外，Service Bus 還提供了另一種傳輸模式：主題（Topic）

讓我們看一下微軟把拔提供的主題概念圖，可以和前面佇列的圖做一下比較：

簡單來說就是傳送出去之後，會有多個接收者等著收訊息。

現在就讓我們回到 Azure Service Bus 的頁面，點選上方的「＋主題」來建立新主題吧：

小提示：主題（Topic）是標準定價層才提供的功能。如果是使用最便宜的基本定價層的朋友，「＋主題」的按鈕應該會反灰的，這時候就要需要從 Service Bus 概觀頁面的「定價層」變更到標準（Standard）才能建立主題。

當然不同定價層的價格也會不一樣，要記得確認一下價格呦！

接著就和前面的佇列一樣取個好名字：

建立完就會出現在我們的 ServiceBus 服務中囉：

和單純一對一的佇列不一樣，我們還會需要替主題建立訂用帳戶（Subscriptions），這樣主題才知道它到底要把訊息送給哪些對象。

現在讓我們進入主題的頁面，並找到訂用帳戶：

進去之後讓我們來新增訂用帳戶：

首先當然是要取個好名字，這邊就先用 Sub1 來當作一號訂閱者的暱稱吧：

這邊和佇列的時候一樣，要注意「最大傳遞計數」（Maximum Delivery Count），簡單來說就是這封訊息會嘗試傳遞幾次，如果超過次數都沒有傳遞成功就會被丟到無效信件。可以參閱服務匯流排寄不出的信件佇列的概觀。

另一個要注意的部份是「啟用工作階段」（Session）：簡單來說就是保證訊息的先進先出（FIFO），藉由在訊息中傳遞 SessionID，然後根據訊息的 SessionID 和接收者建立連線之後發送，讓同個工作階段的訊息按照順序發送到同個對象進行處理。

這功能在佇列和主題都可以使用，但要定價層在標準和以上才支援。當你有多台機器在接收訊息時會對工作階段比較有感覺（例如說 SessionID 寫死然後開了很多台來處理訊息，結果因為工作階段會全部卡在同一台囧）

詳細可以參閱 Azure 服務匯流排訊息工作階段，圖片說明會比較好理解。

建立完畢之後回到訂用帳戶就會看到囉，這邊為了等等能夠示範傳遞訊息給多個訂用者，所以也順便開了 Sub2：

這樣就完成了主題的建立啦！接著讓我們回到程式中來撰寫訊息吧～

將訊息放入主題

基本上來說，訊息放入主題的方式就和放入佇列的方式一樣：

/// <summary>
/// 將訊息放入主題
/// </summary>
[HttpPost]
public async Task Enqueue([FromBody] string context)
{
    // 用 ServiceBus 的連線字串建立 Client
    // 連線字串可以在 Azure ServiceBus 頁面的共用存取原則找到
    // ServiceBusClient 用完記得要呼叫 DisposeAsync() 來關掉
    // 或是直接使用 await using 包起來
    var connectionString = "YOUR SERVICE BUS CONNECTION STRING";
    await using var client = new ServiceBusClient(connectionString);

    // 傳遞 Topic 的名字給 CreateSender 方法來建立 Sender
    // 和 ServiceBusClient 一樣，有提供 DisposeAsync 方法來關閉
    // 或是直接使用 await using 包起來
    var topicName = "YOUR TOPIC NAME";
    await using var sender = client.CreateSender(topicName);

    // 將要傳送的訊息包裝成 ServiceBusMessage
    // 並使用 ServiceBusSender.SendMessageAsync 傳送出去
    var message = new ServiceBusMessage(context);
    await sender.SendMessageAsync(message);
}

不用當成大家來找碴，因為真的就是一樣的放法。畢竟 CreateSender 的參數名稱是這樣的：

事不宜遲，我們馬上就來傳一封訊息試試：

這時候再到我們的主題下的訂用帳戶，可以看見訂用帳戶中已經有訊息囉：

因為主題會傳送給所有訂用帳戶，所以兩個訂用帳戶都會分別收到這則訊息，讓我們也確認一眼吧：

看來我們很順利地把訊息傳送出去啦！那因為整批放入的方式也和佇列一樣，這邊就不再贅述。接下來就讓我們把訊息取出來試試吧～

從主題中讀取訊息

就像前面寫入訊息到主題和寫入佇列長得九成像一樣，讀取也是差不多的。最大的差別是在建立 Processor 時，需要多給訂用帳戶名稱：

// 需要同時告訴 Processor 主題名稱和訂用帳戶名稱
var queueName = "YOUR QUEUE NAME";
var subscriptionName = "Sub1";
await using var processor = client.CreateProcessor(topicName, subscriptionName);

讓我們修改成 Topic 名稱以及剛剛的訂用帳戶 Sub1 之後執行看看：

可以看見訂用帳戶 Sub1 的訊息也消耗掉了：

而訂用帳戶 Sub2 的訊息還在，當我們使用 Sub2 來建立 Processor 並接收訊息之後才會消失：

其餘的部份都和處理佇列的時候一樣。但為了版面一致 ~~我之後回來複製的時候方便~~ 這邊還是附上程式碼：

/// <summary>
/// 取出主題中的訊息
/// </summary>
/// <returns></returns>
[HttpGet]
public async Task Dequeue()
{
    // 和發送訊息的場合差不多：先建立 Client 及 Processor
    var connectionString = "YOUR SERVICE BUS CONNECTION STRING";
    await using var client = new ServiceBusClient(connectionString);

    // 和前面的 ServiceBusSender 一樣，有提供 DisposeAsync 方法讓我們用完時關閉
    // 或是直接使用 await using 包起來
    // 和佇列不一樣的是：需要同時告訴 Processor 主題名稱和訂用帳戶名稱
    var topicName = "YOUR TOPIC NAME";
    var subscriptionName = "YOUR SUBSCRIPTION NAME";
    await using var processor = client.CreateProcessor(topicName, subscriptionName);

    // 告訴 Processor 我們想怎麼處理訊息
    processor.ProcessMessageAsync += MessageHandler;
    processor.ProcessErrorAsync += ErrorHandler;

    // 讓 Processor 上工，開始接收訊息
    await processor.StartProcessingAsync();

    // 實際上會掛著讓 processor 一直處理送來的訊息
    // 這邊就意思意思跑個一下下
    await Task.Delay(1000);

    // 讓 Processor 下班休息
    await processor.StopProcessingAsync();
}

/// <summary>
/// 處理主題訊息
/// </summary>
/// <returns></returns>
private static async Task MessageHandler(ProcessMessageEventArgs args)
{
    // 從訊息的 Body 取出我們發送時塞進去的內容
    var message = args.Message.Body.ToString();
    
    // 對訊息內容做你想做的事。這邊就印出來看個一眼意思意思
    Console.WriteLine(message);

    // 告訴 Service Bus 這個訊息有成功處理了
    await args.CompleteMessageAsync(args.Message);
}

/// <summary>
/// 處理主題錯誤訊息
/// </summary>
/// <returns></returns>
private static async Task ErrorHandler(ProcessErrorEventArgs args)
{
    // 從訊息中取出錯誤訊息
    var exception = args.Exception.ToString();

    // 對訊息做錯誤處理，例如存到日誌系統之類的。這邊也印出來看個一眼意思意思
    Console.WriteLine(exception);
}

稍作整理

我們已經介紹完了 ServiceBus 的兩種主要工具：佇列和主題的基本操作。

接下來我將稍微對現在的範例程式碼做點簡單的整理，給有興趣的朋友參考。

其餘的朋友可以直接跳到最後的小結。

使用 IAzureClientFactory 搭配依賴注入來建立 Azure Client

這一小節會用到 .Net Core 的依賴注入，還沒有概念的朋友可以參照使用依賴注入 (Dependency Injection) 來解除強耦合吧

在範例中我們總是直接 new ServiceBusClient。但根據官方建議，ServiceBusClient 應該只建立一份並重複使用，以避免重新連線之類的效能損失。

針對 ServiceBusClient 的建立和管理，我們可以使用 IAzureClientFactory 來讓它自動控制，替我們管理 Client 的實例和連線，用起來就像 HttpClientFactory 一樣。

要使用 IAzureClientFactory，我們需要先安裝 Microsoft.Extensions.Azure 套件：

現在讓我們移動到 Program.cs 並加上 ServiceBusClient 的註冊：

builder.Services.AddAzureClients(clientsBuilder =>
{
    var connectionString = "YOUR SERVICE BUS CONNECTION STRING";
    
    clientsBuilder
        .AddServiceBusClient(connectionString)
        .WithName("ServiceBusClient");
});

看起來應該會像這樣：

註：示範專案是使用 .Net 6。如果是使用其他版本或其他 DI 工具的朋友，請再按照自己的狀況調整吧！

例如在 HostBuilder 的場合，可能就要在 ConfigureServices 中進行配置等等，只能祝各位好運。

註：除了 WithName 替 Client 實例取名以外，也可以呼叫 ConfigureOptions 來對 ServiceBusClient 進行各式各樣的設定

關於 ServiceBusClient 的設定內容可以參閱 ServiceBusClientOptions

而關於 AddAzureClients 的註冊則可以參閱 How to register ServiceBusClient for dependency injection? - stackoverflow

現在我們註冊完了。接著只需要回到使用的類別讓 IAzureClientFactory 注入進來就可以囉：

/// <summary>
/// Service Bus Queue + IAzureClientFactory 示範用 Controller
/// </summary>
[ApiController]
[Route("[controller]")]
public class QueueWithDiController : ControllerBase
{
    private readonly ServiceBusClient _serviceBusClient;

    public QueueWithDiController(
        IAzureClientFactory<ServiceBusClient> azureClientFactory)
    {
        // 使用注入進來的 IAzureClientFactory 來建立 ServiceBusClient
        _serviceBusClient = azureClientFactory.CreateClient(name: "ServiceBusClient");
    }
}

接著我們就可以把原本範例中的呼叫也改成使用這個 Client 來操作囉：

var queueName = "YOUR QUEUE NAME";
await using var sender = _serviceBusClient.CreateSender(queueName);

註：在前面的官方建議中，除了 ServiceBusClient 以外，其實也建議 ServiceBusSender、ServiceBusReceiver、ServiceBusProcessor 這幾個也應該要維持單例，保持和伺服器的連線以減少建立連線的效能和時間損失。

ServiceBusClient 已經藉由前面提到的 IAzureClientFactory 來解決；而像是 ServiceBusSender 的後面三項，我們就需要根據專案的狀況來規劃如何重複使用。

例如只需要一個 Sender 的場合，我們可以直接在注入的時候註冊成單例；而要和多個 Queue 連線所以需要多個 Sender 的時候，就可以考慮建立一個工廠來管理，並且在工廠裡面優先返回已經建好的實例等等。這部份就請再各位朋友保持柔軟的彈性來處理。

將連線字串抽取到 Config

把鏡頭回到我們註冊的地方：

builder.Services.AddAzureClients(clientsBuilder =>
{
    var connectionString = "YOUR SERVICE BUS CONNECTION STRING";
    
    clientsBuilder
        .AddServiceBusClient(connectionString)
        .WithName("ServiceBusClient");
});

可以看到現在的連線字串是寫死在 Program.cs 中的（即使是前面的範例也是直接寫死在 Controller）

但實務上我們大多會將連線字串放在設定檔，例如 Config 或 Appsettings，方便在正式環境或是 Azure 服務上運行時，能夠由外部去設定 or 變更組態來置換連線字串。因此這邊也應該要改成從組態中進行讀取。

首先讓我們把連線字串丟到 appsettings.json 的 ConnectionStrings 區塊：

"ConnectionStrings": {
    "ServiceBus": "YOUR SERVICE BUS CONNECTION STRING"
}

那麼我們就可以更彈性靈活地使用連線字串來註冊 Client 囉：

builder.Services.AddAzureClients(clientsBuilder =>
{
    var connectionString = builder.Configuration
        .GetConnectionString("ServiceBus");
    
    clientsBuilder
        .AddServiceBusClient(connectionString)
        .WithName("ServiceBusClient");
});

小結

這篇我們稍微紀錄了訊息佇列（Message Queue）的用途：拆分生產者和消費者的直接依賴，在中間架設佇列來傳遞訊息。以及這樣做的幾個好處：解除耦合、提高擴展、非同步和提供了緩衝區。

接著介紹了 Azure 的訊息佇列服務：Azure Service Bus，並對其中的兩種模式：佇列和主題，各做了簡單的操作範例。

最後補充了一些範例能優化的方向；使用 IAzureClientFactory 來注入 Client、保持 Sender 等連線重複使用，以及將連線字串拆出到組態處理。

當然還有一些進階的使用場景，例如交易處理、異地複寫等等，但因為這邊還沒有接觸過，就交給需要深入了解的朋朋自行研究囉。

這算是我第一次接觸 Azure 相關的工具，加減筆記一下簡單的使用場景（傳入訊息到佇列／從佇列取出訊息），範例也已經丟到 Github 上囉，有缺漏的也歡迎各位朋朋幫忙補充，感謝感謝。

那麼今天的紀錄就到這邊囉，希望以後還能回來抄。~~總不會筆記寫完就要改用 RabbitMQ 了吧囧~~

參考資料

Snispate —— 方便的截圖小幫手，放下剪取工具和小畫家吧

Igouist (Igouist) — Sun, 07 Aug 2022 11:44:00 +0800

嗨各位朋朋，又到了「同事推薦的好用工具」時間！

今天要推薦的是 Snipaste 這套香香的截圖工具。

在遠古時代的時候，我寫部落格或是測ＡＰＩ要貼圖附結果時，都是使用 Windows 內建的剪取工具（Shift + Win + S）來螢幕截圖，之後貼到小畫家上再進行標記（例如畫底線、紅色框框等等）

但有了 Snispate，這個動作就可以一氣呵成！

Snipaste 可以直接按下 F1 進入截圖，這時候我們能用滑鼠拖曳來選取截圖範圍，也能夠用拖拉邊界、鍵盤慢慢移動一像素的方式來調整截圖範圍

其中最方便的部份，就是滑鼠點擊某個區塊時，Snipaste 會嘗試幫你偵測該區塊的範圍，例如直接選取某個視窗，在截圖某些網頁的時候相當方便。此外也還有重複選取上次截圖範圍等貼心功能：

選取截圖範圍之後，就會跳出一排工具列：

這時候我們就可以直接對截圖內容做標記和加註，例如用框框把重點框選起來，直接加入文字方塊說明，甚至把一些機密資訊馬賽克一下：

而編輯好了之後，就可以選擇最右邊的複製到剪貼簿或存檔囉！

像我個人截圖時幾乎都是為了貼到別的地方，所以就時常使用 Snispate 直接 截圖 → 標記 → 複製 → 貼上，一氣呵成！

此外要特別講一下的就是複製左邊的這個釘選圖片，它可以讓你把現在的截圖釘選在螢幕上：

有些時候我們可能正在整理資料，這時候就可以先用釘選的方式把截圖都卡在螢幕上，方便我們快速整合。

這個釘選功能用起來，就會像一些警探／偵探片追查犯人時的牆壁和白板那樣，把照片和資料直接釘在上面看出關聯那樣 ~~用起來還蠻帥的~~

截圖軟體其實還蠻多套的，Snipaste 讓我用起來感覺相當順手，並且釘選貼圖功能也讓有多螢幕的我在整合資料的時候更加流暢。有興趣的朋友也可以試試看，這邊附上 Windows Store 載點：Snipaste

參考資料

使用 Wox & Everything 在 Windows 上得到良好的搜尋體驗

Igouist (Igouist) — Sat, 18 Jun 2022 20:11:00 +0800

介紹一下同事推薦的 Windows 好用工具：方便的快速啟動工具 Wox 以及能快速搜尋檔案的 Everything。

如果你曾經有看著檔案總管轉圈圈、等到火都上來了的經驗；或是懶得伸伸手用滑鼠點資料夾，那也許你能試試 Wox + Everything 的組合來稍稍拯救你的心理健康。

Everything

Everything 是一款簡單的搜尋工具，它會抓取系統裡的檔案名稱來建立索引，因此搜尋的時候並不是像檔案總管即時整個海撈，而是直接抓取 Everything 做好的檔名索引，搜尋速度當然就會快上許多。

當然，如果不是想找檔案名稱的時候就沒辦法囉。但大多數找檔案時的搜尋場景都是檔案名稱，所以 Everything

總之到下載頁面把對應的安裝檔抓下來後，就是慣例的下一步下一步式安裝。

安裝完畢之後打開，應該就會看到一個相當簡潔的畫面：上面是搜尋欄，下面是搜尋結果，支援多關鍵字。就是這麼簡單！

Wox

要發揮 Everything 的力量，就需要搭配他的好朋友 Wox！

Wox 是一款搜尋列工具，基本上就是能讓你用快捷鍵就呼叫出一個搜尋欄來使用。如果有在隔壁棚 Mac 看過 Spotlight 的朋友可能會比較有概念。

一樣讓我們到下載頁面把 Wox 載回來並安裝。

安裝完畢之後，使用 Alt + 空白鍵 的快捷鍵，就可以叫出 Wox：

除了和 Everything 結合來搜尋檔案以外，已經安裝的應用程式也是沒問題的：

除此之外，Wox 還支援安裝模組來讓搜尋框更好用！

讓我們對運行中的 Wox 右鍵進入設定選單：

設定中可以調整主題等等：

接著我們來看看模組，可以看到已經安裝了一些模組，例如網頁搜尋和命令列指令：

大多數的模組也可以自訂觸發關鍵字。例如網頁搜尋的觸發關鍵字 g，就可以這樣使用：

但我最常用到這功能的場景還是 Code 噴 Error 的時候，直接 Alt + Space 叫出 Wox 然後 g 貼上錯誤訊息啦 XD

Wox 搭配人人都會的 Alt + Tab 起來用，切換視窗／檔案也算是相當方便了，不過其實會安裝這些工具，說穿了就是手懶得離開鍵盤嘛哈哈

參考資料

C#: 使用 AngleSharp 爬蟲工具來抓取網頁內容吧

Igouist (Igouist) — Sun, 05 Jun 2022 00:21:00 +0800

前一次用到 AngleSharp 已經是去年抓網路小說的時候，想不到最近又用上了，乾脆就來筆記一下。

AngleSharp 是一款簡單方便的 C# 爬蟲套件，撈網頁時支援 QuerySelector 的語法來篩選網頁元素，並且撈回來的資料集合也都能用 Linq 操作，讓我們能對爬取的網頁內容快速進行篩選和處理，只需要短短的語法就可以開心抓想要的內容。

說到要示範爬蟲，果然還是要用爬蟲界默認的經典範例 PTT 表特版來操作（？），接著就讓我們來寫一個簡單的腳本來抓取文章吧！

章節目錄

安裝套件

首先要先從 Nuget 安裝 AngleSharp

確認安裝完畢後就可以開始撰寫囉～

本篇接下來會使用 Linqpad 來進行簡單的範例，使用 VisualStudio 的朋友遇到 Dump() 之類的語法就請再自己調整一下呦

建立 Browser 抓取網頁內容

首先我們需要先建立一個 Browser 來代替我們做事：

void Main()
{
    // 建立 Browser 的配置
	var config = AngleSharp.Configuration.Default.WithDefaultLoader();

    // 根據配置建立出我們的 Browser 
	var browser = BrowsingContext.New(config);
}

建立之後就可以用這個 browser 的 OpenAsync() 來抓取網頁內容囉：

// 這邊為了方便處理也順便把 `Main` 改成非同步的版本
async Task Main()
{
	var config = AngleSharp.Configuration.Default.WithDefaultLoader();
	var browser = BrowsingContext.New(config);
	
    // 這邊用的型別是 AngleSharp 提供的 AngleSharp.Dom.Url
	var url = new Url("https://www.ptt.cc/bbs/Beauty/index.html");

    // 使用 OpenAsync 來打開網頁抓回內容
	var document = await browser.OpenAsync(url);
	document.Dump();
}

可以看到抓了一堆東西回來，包含網頁的 Uri、Body 等等：

在前一個步驟我們雖然把網頁抓回來了，但讓我們看一下 context.Body.InnerHtml 的內容：

看起來跟我們要的文章列表有點差距啊！這是因為 PTT 會先跳出一個視窗詢問是否滿十八歲，選擇「是」之後會記錄一筆 over18=1 到 Cookie 中，只有持有這個 Cookie 才能進入到文章列表。

因此我們現在要先把答案準備到 Cookie 裡，這時候我們就需要調整一下前面的配置內容。

首先先在配置裡加上預設的 Cookies：

// 加上 `WithDefaultCookies()` 來加上預設的 Cookie
var config = AngleSharp.Configuration.Default
    .WithDefaultLoader()
    .WithDefaultCookies();

var browser = BrowsingContext.New(config);

接著在我們開啟網頁之前，使用 SetCookie 對目標指定要用的 Cookie：

var url = new Url("https://www.ptt.cc/bbs/Beauty/index.html");

// 加上已滿十八歲的 Cookie 來通過年齡驗證頁面
browser.SetCookie(url, "over18=1'"); 

var document = await browser.OpenAsync(url);

現在會長得像這樣：

async Task Main()
{
	var config = AngleSharp.Configuration.Default
		.WithDefaultLoader()
		.WithDefaultCookies();
		
	var browser = BrowsingContext.New(config);
	
	var url = new Url("https://www.ptt.cc/bbs/Beauty/index.html");
	browser.SetCookie(url, "over18=1'"); 
	
	var document = await browser.OpenAsync(url);	
	document.Body.InnerHtml.Dump();
}

接著讓我們來確認爬回來的 HTML：

可以看到我們成功進到看板囉！

註：另一個很常在配置處理的是使用 LoaderOptions 加上 AngleSharp.Css 提供的 WithCss() 來抓取 CSS 處理後的結果，例如：
Configuration.Default
    .WithDefaultLoader(new LoaderOptions 
    { 
        IsResourceLoadingEnabled = true 
    })
    .WithCss();
不過這些場景（需要掛 Cookie 啦、要先等 CSS 啦）通常都是遇到之後才去 Google 的，這邊就不再贅述。

註：browser.OpenAsync 除了提供網址讓他直接抓回來以外，有時候我們也會遇到本機已經有 Html 檔案要處理，或是已經用 HttpClient 等方法把網頁內容拿回來了的狀況

這種時候也可以用 OpenAsync 提供的委派方法來把 HTML 字串讀取成 AngleSharp 的物件。例如：OpenAsync(res => res.Content(html))，同時委派中的 VirtualResponse 也提供了對這物件設定 Cookie 等資訊的方法，有這個需求的朋友可以再動手試試。

使用篩選器來抓指定的內容

現在我們已經成功把網頁內容抓回來了，接著就是要使用選擇器來抓出我們想要的內容囉。

如果有用過 JQuery 或是整天寫 CSS 的朋友應該不會陌生，大致上是這樣的：

div: 就是抓 <div>
#wow: 抓 id 是 wow 的元素
.hello: 抓 class 是 hello 的元素

當然也可以加以組合，例如 div#wow, div > p.hello 等，有興趣的朋友可以再看一眼菜鳥教程的 CSS 選擇器說明，其他狀況就等需要的時候再查表即可。

首先讓我們好好觀察 HTML 結構，可以發現標題框是放在 class="r-ent" 的 div 裡，那我們就可以這樣下 Selector：div.r-ent

接著我們就能用 QuerySelectorAll() 這個方法來用 Selector 抓取我們想要的元素：

document
    .QuerySelectorAll("div.r-ent") // 指定 class 為 r-ent 的 div
    .Select(node => node.InnerHtml) // 直接抓內容出來看看
    .Dump();

可以看到我們成功抓了一排標題資訊回來囉！

當然 AngleSharp 也提供了 QuerySelector 來抓取單個元素，這兩個方法用起來和 JavaScript 的體驗應該是差不多啦。

確定我們有把要的內容抓回來，也不會再用到網頁內容的話，就可以補一行 document.Close(); 把開啟的網頁內容順手清掉囉。

註：現在都２０２２年了，瀏覽器當然也有提供直接抓 Selector 的功能了

這邊以 Edge 為例，讓我們到目標網頁按下Ｆ１２打開開發人員工具，直接選取目標：

選取目標後就會告訴我們這是哪個元素，我們只需要對該元素右鍵，然後複製它的 Selector 就行啦

不過這樣抓到的 Selector 語法通常會比較囉嗦一點，例如這個頁面就是 #main-container > div.r-list-container.action-bar-margin.bbs-screen，這部份就再自己調整一下囉

整理抓取到的內容

現在讓我們建立一個類別用來處理標題資訊吧，這邊我只需要名稱、推噓數和文章連結，其他像是作者什麼的不太需要：

public class Post
{
	public string Title { get; set; }
	public int Push { get; set; }
	public string Link { get; set; }
}

接著就來把我們剛剛抓到的每一則文章標題轉換成我們要的物件吧！

觀察上面抓到的標題資訊，可以發現標題的文字和文章連結都放在 <div class="title"> 裡的 <a>，這邊我們就可以利用 QuerySelector 來抓到這個元素

而為了拿到連結，這邊會需要使用 GetAttribute 來抓取元素的 href 屬性。這樣標題和連結就搞定了。

另外要注意的是：如果文章被刪掉了，可是抓不到這些東西的！所以可以在 QuerySelector 之後用 ?. 的方式來做個 Null 時的防呆，最後也可以再用 Where 來過濾掉無效的文章。

var titleElement = post.QuerySelector("div.title > a");
var title = titleElement?.InnerHtml; // 標題文字
var link = titleElement?.GetAttribute("href"); // 文章連結

剩下的推噓數可以看到是放在 <div class="nrec"> 裡面，這邊我希望能轉換成數字，方便我們後續如果要用推噓數做篩選。所以讓我們額外處理一下：

只顯示「爆」，這時候我們就視作 100
如果有明確的數字，轉換為 Int
沒有數字的話就當成 0。

var pushString = post.QuerySelector("div.nrec > span")?.InnerHtml;

var pushCount = 
    pushString == "爆" ? 100 : 
    Int16.TryParse(pushString, out var push) ? push : 0;

最後就把這些資訊拿來組裝我們的物件，那麼現在的程式碼就會像這樣：

var posts = postSource.Select(post => 
{
    var titleElement = post.QuerySelector("div.title > a");
    var title = titleElement?.InnerHtml;
    var link = titleElement?.GetAttribute("href");
    
    var pushString = post.QuerySelector("div.nrec > span")?.InnerHtml;
    var pushCount = 
        pushString == "爆" ? 100 : 
        Int16.TryParse(pushString, out var push) ? push : 0;
        
    return new Post
    {
        Title = title,
        Link = link,
        Push = pushCount
    };
})
.Where(post => post.Title != null)
.Dump();

到這邊我們就成功把網頁的內容抓下來、篩選出我們要的內容囉！

註：除了我們前面使用的 QuerySelector、GetAttribute 以外，AngleSharp 還提供了 GetElementsByTagName、Children 等屬性和方法讓我們能方便地在 DOM 中到處抓取元素。

有興趣的朋友再自己摸索一下吧，我自己是比較習慣無腦 QuerySelector 了啦哈哈。

搭配遞迴來多撈幾頁

其實我們前面已經把 AngleSharp 的基本操作跑完一輪了，基本上不外乎是「打開目標網頁 → 找到目標元素 → 用篩選器抓出來」這樣的 Loop，這節只是單純讓這個腳本完善一點而已。

因此不感興趣的朋友也可以直接跳過這一段，直接前往小結，準備出發去動手抓自己想要的網頁囉。

現在讓我們回到文章列表來，只抓第一頁實在沒什麼搞頭。如果我們想要換頁，那麼首先就要先抓出這個換頁按鈕：

利用前面提到的Ｆ１２大法，我們可以拿到這個按鈕的 Selector 語法，讓我們直接丟到 QuerySelector 裡，並且取得它的 href 屬性：

var nextPageLink = document
	.QuerySelector("div.btn-group.btn-group-paging > a:nth-child(2)")
	.GetAttribute("href")
	.Dump(); // = /bbs/Beauty/index3980.html

現在我們有了往前一頁的連結了，後續只需要把站台的 Url 和下一頁的相對 Url 就可以拼湊出換頁的連結了。

如此一來就可以做出「抓文章 → 下一頁 → 抓文章…」的循環。像這種場合直接使用遞迴，寫起來會快一點。

首先讓我們把抓取文章的處理過程抽出去當作方法，當然會重複用到我們的 Browser，還有站台 Url 以及每一頁的 Url，最後再丟個數字控制要抓幾頁，大概像這樣：

private async Task<IEnumerable<Post>> GetPosts(
	IBrowsingContext browser,
	string baseUrl, 
	string pageUrl,
	int remainingPages)
{
}

現在讓我們把上面的處理步驟逐一搬移到方法中，預期會需要：

先組裝 Url、設定 Cookie 然後 Open 抓回網頁內容
抓取這一頁的所有文章標題
取得下一頁的連結
遞迴取得下一頁及往後頁數的文章列表
把這一頁和下一頁往後的文章列表組裝起來回傳

private async Task<IEnumerable<Post>> GetPosts(
	IBrowsingContext browser, 
	string baseUrl, 
	string pageUrl,
	int remainingPages)
{
	// 組裝 Url 並設定 Cookie
	var url = new Url(baseUrl + pageUrl);
	browser.SetCookie(url, "over18=1'");
	var document = await browser.OpenAsync(url);

	// 取出所有文章標題
	var postSource = document.QuerySelectorAll("div.r-ent");

	var posts = postSource.Select(post =>
	{
		var titleElement = post.QuerySelector("div.title > a");
		var title = titleElement?.InnerHtml;
		var link = titleElement?.GetAttribute("href");

		var pushString = post.QuerySelector("div.nrec > span")?.InnerHtml;
		var pushCount =
			pushString == "爆" ? 100 :
			Int16.TryParse(pushString, out var push) ? push : 0;

		return new Post
		{
			Title = title,
			Link = link,
			Push = pushCount
		};
	})
	.Where(post => post.Title != null);

	// 取得下一頁的連結
	var nextPageUrl = document
		.QuerySelector("div.btn-group.btn-group-paging > a:nth-child(2)")
		.GetAttribute("href");
		
	document.Close();
	
	// 檢查剩餘頁數
	remainingPages--;
	if (remainingPages == 0)
	{
		return posts;
	}

    // 組裝遞迴取得的文章列表
	var nextPagePosts = await GetPosts(browser, baseUrl, nextPageUrl, remainingPages);
	return posts.Concat(nextPagePosts);
}

雖然也可以把詳細的步驟再拆得更細，像是把組裝 Post 的部分拆出去私有方法，或是多加一層迴圈進到文章內抓取照片等等，不過現在我們只需要穩定拿到文章資訊就行

接著再稍微修改一下，外面呼叫方法的部份只需要負責建立 Broswer 和定下第一頁的 Url 就好了

async Task Main()
{
	var config = AngleSharp.Configuration.Default
		.WithDefaultLoader()
		.WithDefaultCookies();
		
	var browser = BrowsingContext.New(config);

	var baseUrl = "https://www.ptt.cc";
	var indexUrl = "/bbs/Beauty/index.html";

	var pages = 10;
	var posts = await GetPosts(browser, baseUrl, indexUrl, pages);
}

這樣就大功告成，一次抓它個十頁都沒有問題囉！

最後就可以按照我們的要求來處理 posts 的文章啦，例如：

posts.Where(post => post.Push > 90).Dump();

馬上就可以抓出十頁內 90 推以上的文，所以說 Linq 就是方便哪。

到這邊我們已經可以很靈活地去運用這個列表了，像是把撈出來的文章連結搭配 LineNotify 做個推播通知啦，還是乾脆掛到排程服務去定時爬資料啦，都是很彈性很自由的了。

小結

最後再一次整理本篇的操作流程：

從 AngleSharp.Configuration.Default 建立組態
使用 BrowsingContext.New(config) 來建立 Browser
根據需求調整組態和 Browser，例如 SetCookie
使用 browser.OpenAsync(url) 把網頁內容抓回來
使用篩選器搭配 QuerySelector 等方法，從網頁內容中抓出我們要的資訊
網頁爬完之後可以順手 Close()
自由發揮

步驟其實非常簡單，各位朋友可以出發去動手抓自己想要的網頁囉！

例如說抓一下股票資訊啦、稽查朋友在 PTT 的留言啦，都蠻有趣（？）的呢

總之，當你需要在 C# 能簡單使用的小爬蟲，就是 AngleSharp 出場的時候啦！

參考資料

《艾爾登法環》白金心得

Igouist (Igouist) — Fri, 03 Jun 2022 23:25:00 +0800

這是一篇遲來的白金炫耀廢文。

這次的成就對蒐集東西的要求比較少，沒有像黑魂一樣需要在同個場景來回打怪刷道具。通常只需要經歷幾個主要的劇情，然後到各地探險、打倒一些Ｂｏｓｓ，白金獎盃就幾乎到手了。

對我這種一半時間都在到處逛街、動不動迷路然後就被王打死的人來說，實在是福音。畢竟我真的很討厭重複打同隻怪刷東西，去年的黑魂也卡在刷誓約物品很久很久。讚美法環，法環拯救了我的靈魂。

另外，Ｂｏｓｓ戰給玩家的攻略手段也變得很多。除了可以正面舉起武器硬肛以外，也可以搭配一些強勢或對Ｂｏｓｓ有利的技能，甚至可以召喚ＮＰＣ和其他玩家衝上去一陣圍毆。

我個人是覺得這樣的處理方式很棒，能同時滿足一般玩家、自我挑戰的苦行僧、不擇手段的外鄉人。

更有趣的是可以看社群互嘴，假老屁股嘴新玩家是草莓族之類的。畢竟我的樂趣一半以上都建立在跟朋友聊法環梗，還有看社群嘴砲及搞笑影片、各派法環歷史學家對遊戲劇情的分析（腦補）等等，社群論戰是絕不可少的

另外不得不說的是：這遊戲雖然大多時候是個單機遊戲，但玩家間的互動相當活絡，除了遊戲裡可以召喚朋友一起打架，或是跟其他玩家打架以外，玩家也能在地版上留言給其他玩家，例如

懸崖前面留「前有寶箱」騙人跳崖
牆壁前面寫「有隱藏道路」讓人撞牆
在烏龜前面寫「很可能是狗」
在龍前面寫「狗」（到底什麼不是狗？）

但雖然搞笑留言跟惡意玩家真的很多（我就跳崖了幾次），但也會看見很暖的留言，尤其是打王前通常都會有「加油！不要放棄」，被怪物襲擊的地方前也都會有其他玩家的警告。啊啊，讚美太陽。

和黑魂的另一個最大差別是開放世界，這其實也大大降低了遊戲難度。畢竟以前卡關的時候就是只能一直死、一直死、死到關遊戲。

現在可以先去打打別的地方，提升一下等級和武器再回來挑戰，甚至還有熱門練功點，整個推圖的壓力就小了不少，像我就逛街逛到沒什麼推主線進度，都在到處找地城倒斗搶東西，還有找風景和劇情過場拍照。

說到地城，我原本以為會像上古卷軸的洞窟那樣，絕大多數都是免洗寶箱探勘處，進去就是閉著眼睛一路殺。但想不到竟然還有利用重複場景和屍體來欺騙玩家的神奇地城

那種「我怎麼又走回來了！？」的焦躁感真是冒險精隨，迷路半小時也不會氣憤，反而在搞懂之後會忍不住讚嘆。英高！你果然是最會搞玩家的男人！

大概這樣。現正受到同事的蠱惑，又開了新角色挑戰限制等級＋只用長劍和盾牌通關，結果被碎星大哥壓在地上磨擦ＩＮＧ囧。 ~~太痛苦了，乾脆來寫廢文，所以才更了這篇。~~

富樫都開始畫獵人了，乾脆在血源上ＰＣ前來挑戰部落格週更吧？開玩笑的。

菜雞新訓記 (7): 使用 Fluent Validation 來驗證參數吧

Igouist (Igouist) — Sun, 13 Mar 2022 20:03:00 +0800

章節目錄

這是俺整理公司新訓內容的第七篇文章，目標是紀錄 Fluent Validation 這個好用套件。

FluentValidation 可以幫我們將 Api 傳入的參數的檢查用更口語、更乾淨的方式去處理，除了可以將檢查邏輯拆分成單獨的 Validator 類別，更提供了許多內建的檢查規則和自訂的彈性，相當方便。

並且因為將參數的檢查邏輯整理出去，就可以和 Controller 本身的工作做簡單的拆分，達到關注點分離的目標。

現在就讓我們來認識一下這個好用工具吧！首先要從很久很久以前開始說起…

前言

西元前的某一天，憂心的皇帝在朝堂內繞著柱子走，突然大臣奪門而入。

大臣：「陛下！敵軍已經攻到國境內啦！」

皇帝大驚：『邊境的那些檢查站和關口難道都陷落了嗎？不可能！』

大臣：「陛下，有內奸和敵國勾結，檢查站完全沒檢查！髒資料已經闖進來了！」

皇帝喊了一聲：『怎麼可能！讓朕看看！』就打開 Controller 和前一個版本的 Git Log，這一看差點就昏了過去。

原來 Controller 的舊程式碼就已經很亂了，檢查參數的條件 if/else 和其他呼叫的方法、組裝資料都雜在一起。結果這次專案改動時，某一行就被內奸改壞了，關鍵的參數竟然沒檢查到！

『可，可惡！來人啊，把工程師推出午門斬首！』

「皇上！他已經離職啦！」

皇帝跌坐在地，懊悔地說：『如果當初有好好把檢查參數跟實際組資料的部份都拆開的話，也許就不會這樣了…』

「是啊，如果我們有用 Fluent Validation…！」

專案現況

大臣提到的 FluentValidation 是一套能幫我們把傳入參數的分離出去、用更口語化的方式去撰寫的工具。

……如果當時他們有使用 Fluent Validation 來把驗證的邏輯和規則跟原本很亂的 Controller 切分的話，說不定就能及時發現問題吧，大概。

為了不要步上他們的後塵，就讓我們直接回到本系列的卡牌管理 API 服務來加上這個好用工具吧！

假設我們在新增一張新的卡牌時，會針對裡面的欄位做一連串檢查：

/// <summary>
/// 新增卡片
/// </summary>
/// <param name="parameter">卡片參數</param>
/// <returns></returns>
[HttpPost]
public IActionResult Insert([FromBody] CardParameter parameter)
{
    // 這邊需要對參數做檢查
    if (parameter.Attack < 0)
    {
        return BadRequest("卡片的攻擊力不可為負數");
    }

    if (parameter.Health < 0)
    {
        return BadRequest("卡片的生命值不可為負數");
    }

    if (parameter.Cost < 0)
    {
        return BadRequest("卡片的使用成本不可為負數");
    }

    if (parameter.Description != null &&
        parameter.Description.Length > 30)
    {
        return BadRequest("卡片的敘述說明必須少於三十字");
    }

    if (string.IsNullOrWhiteSpace(parameter.Name))
    {
        return BadRequest("卡片的名稱不可為空白");
    }

    if (parameter.Name.Length > 15)
    {
        return BadRequest("卡片的名稱必須少於十五字");
    }

    // 用 AutoMapper 把 Parameter Model 轉換成 Info Model
    var info = this._mapper.Map<CardParameter, CardInfo>(parameter);

    // 呼叫依賴的 Service 層寫入資料
    var isInsertSuccess = this._cardService.Insert(info);
    if (isInsertSuccess)
    {
        return Ok();
    }
    return StatusCode(500);
}

可以看到這個新增卡片的方法中，真正操作的只有最後呼叫相關服務來寫入資料的部份，前面就是針對參數做一整串的 if 檢查。隨著傳入參數要檢查的東西變多，檢查的過程也會越來越大坨。

這時候，只要有了 Fluent Validation，我們就可以在參數檢查上做得更好！

安裝 Fluent Validation

因為我們的示範專案是 .net Core 的 Api，所以讓我們安裝 FluentValidation.AspNetCore

註：這包裡面包含了 Fluent Validation 本體和支援 Dotnet Core 的 DI（DependencyInjection）工具。如果習慣將驗證部分拆成其他類別庫，或是不需要 DI 的朋友可以嘗試安裝 Fluent Validation 就好。

撰寫 Validator

要使用 Fluent Validation 來驗證參數，首先我們必須建立一個針對該參數的驗證器（Validator），並繼承 AbstractValidator<T>。

其中 <T> 的泛型選擇驗證對象的類別即可，接著就可以在 Validator 的建構式來註冊我們要的驗證邏輯。

現在就讓我們針對前面例子的 CardParameter 來建立 CardParameterValidator 吧：

/// <summary>
/// Card Parameter 的驗證器
/// </summary>
public class CardParameterValidator : AbstractValidator<CardParameter>
{
    /// <summary>
    /// 驗證器的建構式: 在這裡註冊我們要驗證的規則
    /// </summary>
    public CardParameterValidator()
    {

    }
}

使用內建的驗證規則

現在我們已經針對 CardParameter 建立了驗證器，接著讓我們處理驗證邏輯的部分吧。

當我們要驗證某個欄位的時候，就需要使用 RuleFor 來告訴驗證器現在驗證的欄位，後面再利用 Fluent Validation 提供的各種驗證語法來進行驗證。

例如我們前面的「卡片的攻擊力不應為負數」，也就是 Attack 必須大於等於０，這邊就可以使用 GreaterThanOrEqualTo：

/// <summary>
/// 驗證器建構式: 在這裡註冊我們要驗證的規則
/// </summary>
public CardParameterValidator()
{
    this.RuleFor(card => card.Attack)
        .GreaterThanOrEqualTo(0);
}

如果驗證的對象是個串列之類的，也支援用 RuleForEach

例如我們的卡片可以有多個別名（List<string> Alias 之類的），且裡面每個別名都不可以是空的，就可以：

/// <summary>
/// 驗證器建構式: 在這裡註冊我們要驗證的規則
/// </summary>
public CardParameterValidator()
{
    this.RuleForEach(card => card.Alias)
        .NotEmpty(); // 不可為空
}

大部份的狀況下，使用內建的驗證語法就很夠用了。可以參照官方文檔的 Built-in Validators，裡面每一項都有範例和參數說明。

平常比較會遇到的就是 NotNull、NotEmpty 和字串長度檢查或是數值大小的。如果是ㄧ些表單需要驗證的話，就還會用到 EmailAddress 等等。

那俺身為一個懶惰節能減碳工程師，當然有在 Linqpad 中準備一份範例 ~~才能隨時抄嘛~~，這邊也會附在文末的附錄。

使用 Must 來自訂驗證規則

當然，我們也會遇到內建的驗證規則不夠用的情況。這時候就可以使用 Must() 來傳入自訂的規則，例如：

/// <summary>
/// 驗證器建構式: 在這裡註冊我們要驗證的規則
/// </summary>
public CardParameterValidator()
{
    // 使用 Must 來自訂規則
    this.RuleFor(card => card.Attack)
        .Must(attack => attack > 0 && attack <= 3000);
}

只要在 Must 裡面指定要驗證的規則就可以囉！

使用 When 來指定驗證條件適用的場景

除了規則可以彈性處理以外，有時候我們也會遇到「有某個條件成立才驗證指定欄位」的情況

假設我們的卡牌又分成「怪獸卡」和「魔法卡」等等，而卡牌本身又有個 int? 的攻擊力欄位

規則又要求：「怪獸卡必須是具有攻擊力的」

雖然直覺上就會想要用 if (卡牌是怪獸卡) 之類的方式去另外做，但就會變得有點兒醜

這時候我們就能用 When 的方式來指定驗證條件的前提：

/// <summary>
/// 驗證器建構式: 在這裡註冊我們要驗證的規則
/// </summary>
public CardParameterValidator()
{
    // 目標：當 卡牌 是 怪獸卡 的時候，攻擊力不可為 Null 

    // 針對指定規則加上適用場景
    this.RuleFor(card => card.Attack)
        .NotNull()
        .When(card => card.CardType is CardType.Monster);

    // 針對指定場景加上適用規則，我個人比較喜歡這種
    this.When(card => card.CardType is CardType.Monster, () =>
    {
        this.RuleFor(card => card.Attack).NotNull();
    });

    // 以上兩種寫法是相同的，但我個人比較喜歡先 When 才指定規則
    // 除了比較符合日常口語以外，也能把同樣場景的規則整理在一起
}

就像 if 有 else，這邊的 When 也有 Otherwise 來幫忙處理剩下的狀況

假設我們除了怪獸卡以外的卡片，例如魔法卡之類的，都不應該有攻擊力，就可以這樣寫：

/// <summary>
/// 驗證器建構式: 在這裡註冊我們要驗證的規則
/// </summary>
public CardParameterValidator()
{
    // 目標：當 卡牌 是 怪獸卡 的時候，攻擊力不可為 Null
    // 目標：當 卡牌 不是 怪獸卡 的時候，攻擊力必須為 Null

    this.When(card => card.CardType is CardType.Monster, () =>
    {
        this.RuleFor(card => card.Attack).NotNull();
    })
    .Otherwise(() =>
    {
        this.RuleFor(card => card.Attack).Null();
    });
}

使用 WithName 和 WithMessage 來自訂驗證訊息

雖然內建的驗證規則都有提供制式的回傳訊息，例如對 Attack 做 .GreaterThanOrEqualTo(0) 驗證失敗時，會得到「‘Attack’ 必須大於或等於 ‘0’」的訊息

但我們也可以使用 WithMessage 來針對驗證規則指定失敗時的自訂訊息：

/// <summary>
/// 驗證器建構式: 在這裡註冊我們要驗證的規則
/// </summary>
public CardParameterValidator()
{
    this.RuleFor(card => card.Attack)
        .GreaterThanOrEqualTo(0)
        .WithMessage("卡片的攻擊力不可為負數");
}

這樣在驗證完的 ValidationResult 裡，就會變成我們指定了錯誤訊息了。

那如果我們想用內建的訊息，但又希望「Attack」這個欄位名稱不要顯示出來，而是顯示我們要的「攻擊力」這個名稱呢？這時候就可以使用 WithName()：

/// <summary>
/// 驗證器建構式: 在這裡註冊我們要驗證的規則
/// </summary>
public CardParameterValidator()
{
    this.RuleFor(card => card.Attack)
        .GreaterThanOrEqualTo(0)
        .WithName("攻擊力");
}

這樣原本的「‘Attack’ 必須大於或等於 ‘0’」，就會變成「‘攻擊力’ 必須大於或等於 ‘0’」囉！

當然，要把兩個結合起來用也是可以的，只要在字串加上 {PropertyName} 讓他去讀欄位名稱就好囉：

/// <summary>
/// 驗證器建構式: 在這裡註冊我們要驗證的規則
/// </summary>
public CardParameterValidator()
{
    this.RuleFor(card => card.Attack)
        .GreaterThanOrEqualTo(0)
        .WithName("攻擊力")
        .WithMessage("卡片的{PropertyName}不可為負數");
}

這樣就能拿到「卡片的攻擊力不可為負數」囉！

使用 SetValidator 來指定成員的驗證器

我們前面說了許多針對欄位驗證的工具，但平常我們的類別內的成員有可能會是另一個類別。這時候我們就可以用 SetValidator 來指定該成員的驗證器。

假設說我們的卡片怪獸現在能夠穿戴裝備了，同時我們也有裝備的 Validator：

public class Card
{
	public CardType Type { get; set; }
	public int Cost { get; set; }
	public string Name { get; set; }
	public int Attack { get; set; }
	
	public Equipment Equipment { get; set;} // 可以穿裝備了！
}

public class Equipment { }
public class EquipmentValidator : AbstractValidator<Card> { }

這時候我們在寫規則的時候就可以：

/// <summary>
/// 驗證器建構式: 在這裡註冊我們要驗證的規則
/// </summary>
public CardParameterValidator()
{
    this.RuleFor(card => card.Equipment)
        .SetValidator(new EquipmentValidator());
}

指定 CascadeMode.Stop 來提早返回

很多時候，我們並不需要全部的規則都驗證完才返回，而是只要檢查清單中的一項不符合，那就直接掰掰。這時我們就可以更改驗證器的 CascadeMode：

/// <summary>
/// 驗證器建構式: 在這裡註冊我們要驗證的規則
/// </summary>
public CardParameterValidator()
{
    // 驗證失敗時即停止
    this.CascadeMode = FluentValidation.CascadeMode.Stop;

    this.RuleFor(card => card.Attack)
        .GreaterThanOrEqualTo(0);
}

CascadeMode 原先預設會是 Continue，也就是即使驗證失敗也會繼續執行

例如說它可能一口氣犯了好幾條，就會全部驗證完再一併列出所有驗證失敗的項目：

當我們把驗證器的 CascadeMode 指定為 Stop 之後，犯第一條就會直接原地遣返：

除了指定整個驗證器以外，我們也可以單獨指定某一條規則為天條：

/// <summary>
/// 驗證器建構式: 在這裡註冊我們要驗證的規則
/// </summary>
public CardParameterValidator()
{
    this.RuleFor(card => card.Attack)
        .Cascade(CascadeMode.Stop)
        .GreaterThanOrEqualTo(0);
}

如此一來只要觸犯這條就會直接送客，皆大歡喜。

將前述的規則實作成 Validator

前面我們介紹了如何撰寫一個 Validator，是時候讓我們來處理文章最一開始的範例了！

這邊附一下文章開頭的範例，也就是目前的卡牌系統 Controller 裡的新增卡片方法：

/// <summary>
/// 新增卡片
/// </summary>
/// <param name="parameter">卡片參數</param>
/// <returns></returns>
[HttpPost]
public IActionResult Insert([FromBody] CardParameter parameter)
{
    // 一堆檢查
    if (parameter.Attack < 0)
    {
        return BadRequest("卡片的攻擊力不可為負數");
    }

    if (parameter.Health < 0)
    {
        return BadRequest("卡片的生命值不可為負數");
    }

    if (parameter.Cost < 0)
    {
        return BadRequest("卡片的使用成本不可為負數");
    }

    if (parameter.Description != null &&
        parameter.Description.Length > 30)
    {
        return BadRequest("卡片的敘述說明必須少於三十字");
    }

    if (string.IsNullOrWhiteSpace(parameter.Name))
    {
        return BadRequest("卡片的名稱不可為空白");
    }

    if (parameter.Name.Length > 15)
    {
        return BadRequest("卡片的名稱必須少於十五字");
    }

    // 用 AutoMapper 把 Parameter Model 轉換成 Info Model
    var info = this._mapper.Map<CardParameter, CardInfo>(parameter);

    // 呼叫依賴的 Service 層寫入資料
    var isInsertSuccess = this._cardService.Insert(info);
    if (isInsertSuccess)
    {
        return Ok();
    }
    return StatusCode(500);
}

可以看到在範例中，我們針對一張新的卡牌，需要檢查的項目有：

攻擊力不可為負數
生命值不可為負數
使用成本不可為負數
敘述說明必須少於三十字
名稱不可以為空值
名稱必須少於十五字

現在讓我們建立 CardParameter 的 Validator，並用 RuleFor 加上這些規則吧：

/// <summary>
/// Card Parameter 的驗證器
/// </summary>
public class CardParameterValidator : AbstractValidator<CardParameter>
{
    /// <summary>
    /// 驗證器的建構式: 在這裡註冊我們要驗證的規則
    /// </summary>
    public CardParameterValidator()
    {
        this.RuleFor(card => card.Attack)
            .GreaterThanOrEqualTo(0);

        this.RuleFor(card => card.Health)
            .GreaterThanOrEqualTo(0);

        this.RuleFor(card => card.Cost)
            .GreaterThanOrEqualTo(0);

        this.RuleFor(card => card.Description)
            .NotNull()
            .MaximumLength(30);

        this.RuleFor(card => card.Name)
            .NotEmpty()
            .MaximumLength(15);
    }
}

可以感覺到比起整串 if/else，這邊整理得更加簡短、也更加口語了。

使用 Validator 進行驗證

現在我們已經準備好了 Validator 了，讓我們回到原本的 Controller 來使用它吧！

首先讓我們把原本的 if/else 部分移除：

/// <summary>
/// 新增卡片
/// </summary>
/// <param name="parameter">卡片參數</param>
/// <returns></returns>
[HttpPost]
public IActionResult Insert(
    [FromBody] CardParameter parameter)
{
    // 這邊需要對參數做檢查

    // 用 AutoMapper 轉換 Model
    var info = this._mapper.Map<CardParameter,CardInfo>(parameter);

    // 呼叫 Service 層寫入資料
    var isInsertSuccess = this._cardService.Insert(info);
    if (isInsertSuccess)
    {
        return Ok();
    }
    return StatusCode(500);
}

接著讓我們直接建立一個驗證器出來使用，並且用 Validate 來驗證參數：

var validator = new CardParameterValidator();
var validationResult = validator.Validate(parameter);

加上驗證器的樣子是像這樣的：

/// <summary>
/// 新增卡片
/// </summary>
/// <param name="parameter">卡片參數</param>
/// <returns></returns>
[HttpPost]
public IActionResult Insert(
    [FromBody] CardParameter parameter)
{
    // 這邊需要對參數做檢查
    var validator = new CardParameterValidator();
    var validationResult = validator.Validate(parameter);

    // 用 AutoMapper 把 Parameter Model 轉換成 Info Model
    var info = this._mapper.Map<CardParameter, CardInfo>(parameter);

    // 呼叫依賴的 Service 層寫入資料
    var isInsertSuccess = this._cardService.Insert(info);
    if (isInsertSuccess)
    {
        return Ok();
    }
    return StatusCode(500);
}

接著我們就可以使用 Validate 回傳的 ValidationResult 來看驗證結果。

先讓我們用 Linqpad 的小範例把 ValidationResult 的內容印出來看看：

可以看到，IsValid 會告訴我們是不是有通過驗證。如果沒有通過驗證的話，Errors 就會有驗證失敗的內容。

現在讓我們加上驗證結果的檢查吧：

/// <summary>
/// 新增卡片
/// </summary>
/// <param name="parameter">卡片參數</param>
/// <returns></returns>
[HttpPost]
public IActionResult Insert(
    [FromBody] CardParameter parameter)
{
    // 這邊需要對參數做檢查
    var validator = new CardParameterValidator();
    var validationResult = validator.Validate(parameter);

    // 如果沒有通過檢查，就把訊息串一串丟回去
    if (validationResult.IsValid is false)
    {
        var errorMessages = validationResult.Errors.Select(e => e.ErrorMessage);
        var resultMessage = string.Join(",", errorMessages);
        return BadRequest(resultMessage); // 直接回傳 400 + 錯誤訊息
    }

    // 用 AutoMapper 把 Parameter Model 轉換成 Info Model
    var info = this._mapper.Map<CardParameter, CardInfo>(parameter);

    // 呼叫依賴的 Service 層寫入資料
    var isInsertSuccess = this._cardService.Insert(info);
    if (isInsertSuccess)
    {
        return Ok();
    }
    return StatusCode(500);
}

現在讓我們來呼叫 API 試試吧！

這邊直接使用先前建置好的 Swagger 頁面來測試，並且故意把攻擊力打成負數：

可以看到回傳的確變成了我們驗證失敗的訊息。

註冊 Validator 來自動進行驗證

不過都已經到了 .net Core 時代，依賴注入已經是內建的功能下，還要用 new 一個驗證器這種直接依賴的方式還是有點不太舒服……所以 Fluent Validation 也有提供自動驗證的作法！

首先讓我們到熟悉的 Startup.cs → ConfigureServices 進行註冊：

services.AddFluentValidation();
services.AddTransient<IValidator<CardParameter>, CardParameterValidator>();

補充：如果不想明確註冊每個類別的 Validator，也可以直接在 AddFluentValidation 的時候，使用反射組件自動註冊的方式來抓該組件底下所有的 Validator，比較不怕出錯、也更方便：

services.AddFluentValidation(fv => fv.RegisterValidatorsFromAssemblyContaining<Startup>());

註冊好了之後就讓我們回到 Controller，並大膽地把驗證器相關的部分刪掉吧：

/// <summary>
/// 新增卡片
/// </summary>
/// <param name="parameter">卡片參數</param>
/// <returns></returns>
[HttpPost]
public IActionResult Insert(
    [FromBody] CardParameter parameter)
{
    // 將原本的參數檢查刪掉了！

    // 用 AutoMapper 把 Parameter Model 轉換成 Info Model
    var info = this._mapper.Map<CardParameter, CardInfo>(parameter);

    // 呼叫依賴的 Service 層寫入資料
    var isInsertSuccess = this._cardService.Insert(info);
    if (isInsertSuccess)
    {
        return Ok();
    }
    return StatusCode(500);
}

然後讓我們用 Swagger 再試一次看看：

可以看到 Fluent Validation 自動幫我們擋了下來！

小結

當檢查參數的過程越來越冗長，為了做到關注點分離、讓方法本體更專注在流程上的處理，我們會選擇將檢查參數的邏輯拆分出去，例如拆成一個私有的 Function 等等。

這時候 Fluent Validation 就提供了我們一個更棒、更優雅的選擇。

本篇稍微記錄了 Fluent Validation 的基本用法，足夠應付大多數的使用場景。簡單小結如下：

繼承 AbstractValidator<T> 來實作我們的驗證器
- 使用 RuleFor 來針對參數的欄位撰寫規則
- 有許多內建的規則可以使用；或是使用 Must 來自定規則
- 使用 When 可以指定規則生效的前提
- 使用 WithName 可以指定欄位在訊息顯示的名稱
- 使用 WithMessage 可以自訂驗證失敗時的訊息
- 使用 SetValidator 可以指定參數某個成員要用的驗證器
- 加上 CascadeMode.Stop 就可以在驗證失敗時直接跳出
使用 Validator 進行驗證
- 可以直接建立驗證器來驗證
  - 如：new CardParameterValidator().Validate(parameter);
- 也可以註冊進行自動驗證
  - 在 Startup 的 ConfigureServices 加上 AddFluentValidation 及驗證器的註冊

當然，FluentValidation 還有許多進階的應用可以探索，例如：

使用 FluentValidation.TestHelper 來替驗證器寫單元測試
使用 RuleSets 來將驗證器規則分成多個規則集，再針對狀況使用
- 例如新增和更新的功能共用同個參數的時候，就可以考慮使用規則集來指定各自要驗證哪些規則
需要客製化驗證失敗時回傳的 ViewModel 時，可以將 validator.Validate 包裝到 Attribute 裡進行攔截及驗證
- 實際案例，敝司對 API 回傳格式有嚴格規範，於是前輩就在 Attribute 裡實例化 Validator 再從 actionContext 抓出參數驗證…

諸如此類，畢竟在參數驗證的路上發生什麼事也不奇怪，請再根據狀況自由地調整吧。

那麼，我們下回見～

參考資料

同系列文章

附錄：FluentValidation 內建驗證方法小抄

void Main()
{
    var sut = new Card
    {
        Cost = 10,
        Name = "Blue-Eyes White Dragon",
        Type = CardType.Monster
    };
    
    var validator = new CardValidator();
    var result = validator.Validate(sut);
    
    result.Dump();
}

public class Card
{
    public CardType Type { get; set; }
    public int Cost { get; set; }
    public string Name { get; set; }
}

public enum CardType
{
    Monster = 0
}

public class CardValidator : AbstractValidator<Card>
{
    public CardValidator()
    {
        // Fluent Validation 的 驗證器請參照
        // https://docs.fluentvalidation.net/en/latest/built-in-validators.html

		// 驗證失敗時即停止
		//this.CascadeMode = FluentValidation.CascadeMode.Stop;

        // 為了示範所以做成變數，平時可以直接 RuleFor().XXX() 串接驗證器即可
        var name = this.RuleFor(card => card.Name);
        var cost = this.RuleFor(card => card.Cost);
        var type = this.RuleFor(card => card.Type);

        // 不可為 Null    
        name.NotNull();
        
        // 必須為 Null
        //name.Null();
        
        // 不可為空
        name.NotEmpty();
        
        // 必須為空
        //name.Empty();
        
        // 不可相同
        name.NotEqual("Test Card");

        // 不可相同：也支持 StringComparer
        name.NotEqual("Test Card", StringComparer.OrdinalIgnoreCase);
        
        // 不可相同：也可以比較其他欄位（大多驗證器都支援）
        name.NotEqual(card => card.Type.ToString());
        
        // 必須相同，其餘用法可參考 NotEqual
        name.Equal("Blue-Eyes White Dragon");
        
        // 長度限制，限定１～２００
        name.Length(1, 200);
        
        // 最大長度限制
        name.MaximumLength(200);
        
        // 最小長度限制
        name.MinimumLength(0);
        
        // 數值需低於目標值
        cost.LessThan(11);
        
        // 數值需低於或等於目標值
        cost.LessThanOrEqualTo(10);
        
        // 數值需高於目標值
        cost.GreaterThan(0);
        
        // 數值需高於或等於目標值
        cost.GreaterThanOrEqualTo(0);
        
        // 數值需介於兩個目標值之間
        cost.ExclusiveBetween(0, 11);
        
        // 數值需介於兩個目標值之間（包含目標值）
        cost.InclusiveBetween(1, 10);
        
        // 檢查是否具有指定的位數，例如 (1, 4) = 小數點限１位、總位數限４位
        this.RuleFor(x => (decimal)x.Cost).ScalePrecision(0, 2);
        
        // 正則表達式
        name.Matches(@"^[a-zA-Z-' ]*$");
        
        // 必須為信箱格式
        //name.EmailAddress();
        
        // 必須為信用卡格式
        //name.CreditCard();
        
        // 必須包含在列舉中
        type.IsInEnum();

        // 必須包含在列舉名稱中
        //name.IsEnumName(typeof(CardType));
        
        // 指定驗證場景
        cost.GreaterThan(0).When(card => card.Type is CardType.Monster);

        // 指定驗證場景
        this.When(card => card.Type is CardType.Monster, () =>
        {
            cost.GreaterThan(0);
        });
        // .Otherwise(() => { cost.GreaterThan(0); });

        // 最終大絕招：自訂驗證器
        cost.Must(power => power > 0 && power <= 3000);
    }
}

Omni —— 實用的 Chrome 分頁書籤搜尋欄

Igouist (Igouist) — Sun, 13 Mar 2022 20:00:00 +0800

Omni 是一款 Chrome 的擴充功能。它能夠讓你用快捷鍵叫出搜尋框，並直接搜尋當前開啟的分頁、書籤、歷史紀錄等等。

這個工具適合：

習慣分頁開很多的人，尤其是像我這種能分頁分組摺疊之後就開更多
懶得用滑鼠去找分頁、也懶得 Ctrl Tab 逐個分頁切換的人
書籤存了一大堆但每次都忘記放在哪裡，最後還是重新搜尋一次的人
想在瀏覽器有方便的搜尋框（就像 Mac 的 Alfred 或 Windows 的 Powertoy 那樣）
即使只有三個分頁，還是要在朋友面前打字裝潮的人

首先讓我們到擴充功能商店把 Omni 安裝進來：

安裝完畢重開一下瀏覽器就可以開始使用囉！

接著只要按下快捷鍵（預設為 Ctrl + Shift + K）就可以叫出搜尋視窗：

補充：如果覺得預設的快捷鍵太卡，也可以設定擴充功能的快捷鍵。

像我個人就習慣設定成和 Visual Studio 的跳轉 Ctrl+T 有關的按法（例如 Ctrl Shift T）

這邊提供 Chrome 和 Edge 快捷鍵更改方式，如下：

Chrome: 右上角擴充功能按鈕 → 管理擴充功能 → 左上工具列 → 鍵盤快捷鍵

Edge: 右上角延伸模組按鈕 → 管理延伸模組 → 左側工具列 → 鍵盤快捷鍵

叫出搜尋欄時，除了當前開著的分頁以外，也會顯示一些 Chrome 內建常用的快捷鍵。

除此之外，Omni 也有提供 Google 日曆的新增、Notion 的新增筆記等等頁面快捷鍵（不過這部分的場景蠻特定的，應該沒有搜尋分頁等功能常用）

而在搜尋窗輸入文字後，就可以在分頁、書籤搜尋有該關鍵字的頁面。也可以使用關鍵字來指定搜尋範圍：

/tabs 搜尋分頁
/bookmarks 搜尋書籤
/history 搜尋歷史紀錄

整個擴充功能的使用就只有 「打開搜尋窗 → 輸入關鍵字 → 找到分頁 or 書籤」 這麼簡單

但在一些開了三四十個分頁的場合，或是像我一樣會將公司各個站台存放到書籤／我的最愛時，簡單的搜尋就能有不錯的效果。在這邊推薦給有同樣習慣的朋友們。

參考資料

AutoMapper 使用 ConvertUsing 自定義類型轉換，將包含串列成員的物件映射為一組串列

Igouist (Igouist) — Sun, 05 Dec 2021 11:20:00 +0800

從朋友那兒聽到了用 AutoMapper 把串列成員物件攤平成一組串列的問題，發現了 ConvertUsing 的好用，這邊就紀錄一下。

事情是這樣的，首先有一個 Parent 類別，其中包含著兩個成員：Id 和串列的 Child 類別，而 Child 類別則只有一個成員 Val，如下：

public class Parent
{
    public int Id { get; set; }
    public IEnumerable<Child> Children { get; set; }
}

public class Child
{
    public double Val { get; set; }
}

另外還有一個 Target 類別，包含 Id 和 Val 兩個成員：

public class Target
{
    public int Id { get; set; }
    public double Val { get; set; }
}

現在的目標是：將一個有著 Child 串列的 Parent 映射成 Target 串列。

也就是說，假設我們的來源是這樣子：

var boo = new Parent
{
    Id = 1,
    Children = new List<Child>
    {
        new Child { Val = 1 },
        new Child { Val = 2 },
    }
};

希望可以變成這樣子：

var expect = new List<Target>
{
    new Target { Id = 1, Val = 1 },
    new Target { Id = 1, Val = 2 },
};

我之前遇到的時候，會直覺地將 Child 直接 Map 到 Target，再對 Target 做個 Foreach 來補上 Parent 的 Id。

這次和朋友討論時，提到了另一個角度：雖然這樣的做法相當直覺快速，但其實並不能保證後續維護的人使用這組 Mappings 時，都知道這裡要補資料；況且此處的對應關係的確是 Parent 到 List<Target>，並非 Child 到 Target 而已，直覺上就怪怪的。若要解決這個問題，可能就要再包裝一層，把 Mapper 隔離出去做個轉換器之類的。

但想想又覺得 AutoMapper 不可能沒提供這個場景能使用的方法才對，最後餵狗發現 AutoMapper 確實有提供 ConvertUsing 來讓我們客製化轉換過程，這邊就紀錄一下。

在我們註冊映射關係的時候，可以用 ConvertUsing 來直接定義轉換的過程。以這個例子來說，就可以：

var config = new MapperConfiguration(cfg =>
{
    cfg
        .CreateMap<Parent, IEnumerable<Target>>()
        .ConvertUsing(parent => parent.Children.Select(child => new Target
        {
            Id = parent.Id,
            Val = child.Val
        }));
});

像這樣告訴 AutoMapper：「從 Parent 轉換到 IEnumerable<Target> 的時候，幫我用 Children 來 Select 出 Target」

註冊後就可以順利進行轉換了，讓我們直接用 Linqpad 試試：

如果是比較複雜的狀況，也可以用實作型別轉換器（ITypeConverter）的方式來處理。以這個例子來說，就可以：

// c實作從 Parent 轉換到 IEnumerable<Target> 的 ITypeConverter
public class ParentToTargetsTypeConverter : ITypeConverter<Parent, IEnumerable<Target>>
{
    // 轉換方法本體
    public IEnumerable<Target> Convert(
        Parent parent,
        IEnumerable<Target> targets,
        ResolutionContext context)
    {
        targets = parent.Children.Select(child => new Target
        {
            Id = parent.Id,
            Val = child.Val
        });
        return targets;
    }
}

接著再把轉換器註冊到 ConvertUsing 上，丟實體或是泛型都行：

var config = new MapperConfiguration(cfg =>
{
        //cfg
        //    .CreateMap<Parent, IEnumerable<Target>>()
        //    .ConvertUsing(new ParentToTargetsTypeConverter());

        // OR

        cfg
            .CreateMap<Parent, IEnumerable<Target>>()
            .ConvertUsing<ParentToTargetsTypeConverter>();
});

測試轉換：

之後當遇到型別轉換的過程並非單純欄位一對一的時候，就可以使用 ConvertUsing 的方式來自行處理。

最後附上測試用的 Linqpad Code ~~方便我之後回來複製~~

void Main()
{
    Sut().Dump();
}

public IEnumerable<Target> Sut()
{
    var boo = new Parent
    {
        Id = 1,
        Children = new List<Child>
        {
            new Child { Val = 1 },
            new Child { Val = 2 },
        }
    };

    var mapper = CreateMapperConfig().CreateMapper();
    var result = mapper.Map<Parent, IEnumerable<Target>>(boo);
    return result;
}

public MapperConfiguration CreateMapperConfig()
{
    var config = new MapperConfiguration(cfg =>
    {
        // 1. 使用 Lambda
        
        //cfg
        //    .CreateMap<Parent, IEnumerable<Target>>()
        //    .ConvertUsing(parent => parent.Children.Select(child => new Target
        //    {
        //        Id = parent.Id,
        //        Val = child.Val
        //    }));
        
        // 2. 使用 TypeConverter
        
        //cfg
        //    .CreateMap<Parent, IEnumerable<Target>>()
        //    .ConvertUsing(new ParentToTargetsTypeConverter());

        cfg
            .CreateMap<Parent, IEnumerable<Target>>()
            .ConvertUsing<ParentToTargetsTypeConverter>();
    });
    return config;
}

public class ParentToTargetsTypeConverter : ITypeConverter<Parent, IEnumerable<Target>>
{
    public IEnumerable<Target> Convert(
        Parent parent,
        IEnumerable<Target> targets,
        ResolutionContext context)
    {
        targets = parent.Children.Select(child => new Target
        {
            Id = parent.Id,
            Val = child.Val
        });
        return targets;
    }
}

public class Parent
{
    public int Id { get; set; }
    public IEnumerable<Child> Children { get; set; }
}

public class Child
{
    public double Val { get; set; }
}

public class Target
{
    public int Id { get; set; }
    public double Val { get; set; }
}

參考資料

AutoMapper —— 類別轉換超省力

菜雞新訓記 (6): 使用依賴注入 (Dependency Injection) 來解除強耦合吧

Igouist (Igouist) — Sun, 28 Nov 2021 20:13:00 +0800

這是俺整理公司新訓內容的第六篇文章，目標是紀錄什麼是依賴注入（Dependency Injection）。包含：

並用 .net Core 實際跑一次依賴注入，藉由將控制權轉移給注入容器，解除分層與分層間、類別與類別間的依賴和耦合關係，達到以介面分離實作的目標。

前言

西元前的某一天，憂心的皇帝在朝堂內繞著柱子走，正巧被路過的廷尉看見。

廷尉：「敢問陛下在煩惱什麼呢？」

皇帝：『朕這是在想封賞的事兒哪。前朝之所以覆滅，根本的原因就在於大肆封賞臣下，四處分封土地給他們做諸侯。

這些諸侯，肆意起用自己喜歡的人擔任要職、結黨營私，心情好就 new 將軍("我ㄉ朋友");，十天就封了十個將軍。這些人若犯了錯，要處理他們還得看諸侯面子；而諸侯一聲令下，這些人便群起造反。

並且，這些諸侯之間彼此喜歡直接往來，動不動就在自家裡下命令給 隔壁諸侯.借糧草(100)，哪天就變成 隔壁諸侯.揪團造反()。彼此之間偷來暗去，實在難以掌握。

最後呢，一個逆賊起來造反，若要將他給辦了，附近諸侯就一起響應，每個都一齊報錯，Exception 成千上百，國家也就這樣滅了，想到這朕就頭痛得很，不知愛卿可有法子？』

廷尉想了一想，便說：「陛下，此事要點還是在於諸侯之間相互依賴、彼此耦合，致生禍端。

臣有一計，先收回諸侯的人事任命權，使其不可私自 new 自己人，所有人事異動，須由中央進行管理與派遣。這樣即使諸侯要造反，也不知道下面這群打工仔是不是自己人。大家各司其職，諸侯做好自己的行政作業，打工仔派到崗位就做好自己的工作，彼此不直接依賴，這樣出事的機率就少了。

其次，明令禁止諸侯私自往來，對諸侯們進行隔離，若是有公務上的需要，一律藉由中央提供的接口來溝通，彼此之間明訂契約，由中央進行隔離與調派，諸侯間就只需要按照協議好的合約下去合作，這樣勾結的機會也就少了，耦合也就降低了。陛下覺得如何？」

皇帝大喜：『如此甚好！治眾如治寡，在於分而治之。此計可有名字？』

「此乃－－依賴注入之計！」

為什麼需要依賴注入

各位好，我們前面引用了民明書坊的《朕的郡縣制哪有這麼耦合》，相信各位對依賴注入應該已經有初步的了解了。說到依賴注入的觀念，就得先從 SOILD 中的依賴反轉原則開始談。

這部份我們之前在依賴反轉原則篇已經有詳細的說明，基於江湖道義，接下來就引用該篇的例子來快速帶過一下。

註：想好好了解的朋友，也可以從依序閱讀這幾篇相關文章後再回到這篇呦：

多型

介面

依賴反轉原則

讓我們從之前依賴反轉的範例開始吧：假設現在有間小小公司，老闆請來了小明當工程師，並請他開工撰寫產品程式碼。

當「撰寫產品程式」對「工程師」直接依賴的時候，狀況可能是這樣的：

public Product Work() // 撰寫產品程式
{
    Ming programmer = new Ming();
    var product = programmer.Programming();
    return product;
}

過一陣子，老闆發現小明寫出來的東西似乎不太行，於是把小明趕走，另外請了小華。這時候因為用到的類別不一樣了，我們就必須要改一次程式碼：

public Product Work()
{
    Hua programmer = new Hua(); // 把小明改成小華
    var product = programmer.Programming();
    return product;
}

又過了好一陣子，老闆又另外請了小美來工作。於是又要再改一次，而且小美的工作方式甚至不叫做 Programming，而是 Coding：

public Product Work()
{
    Mei programmer = new Mei(); // 把小華改成小美
    var product = programmer.Coding(); // 呼叫方法也要改
    return product;
}

現在有感覺到一點問題了嗎？如果一直換人，Work 的程式碼豈不是每次都要修改？

但我們平常開發程式的思維，會習慣從大範圍到小細節、從抽象到具體、從整體目標逐漸拆解成各個步驟的方向去處理，也就是從高階模組往低階模組的方向設計。

例如說我們需要「會員查詢」功能，才用「DB 連線方法」和「資料篩選方法」等具體方式去達成我們要「會員查詢」這個目標。

然而以上面工程師的例子來看：低階模組的變更，卻會導致使用它的高階模組連帶受到影響，在我們決定大方向大目標的時候卻被實作細節綁手綁腳，實在是很怪的一件事，和我們上述的習慣是相悖的。

而依賴的低階模組越多，會被影響的機會就越高、修改的範圍和頻率也會急遽地拉高，變得無法掌握修改程式碼時影響的範圍，最終導致架構變得不穩固、程式碼到處都是不健康的耦合。

面對這樣的困境，依賴反轉原則告訴我們：
高階模組不應該依賴於低階模組。兩者都應該依賴抽象。

也就是指，我們不要讓高階模組直接去依賴低階模組，而是使用抽象的、具有契約精神的介面來對他們進行隔離。

如此一來，只要介面的契約成立了，高階模組就可以專心做好自己的事情（職責），而不用去管低階模組的方法名稱之類的鳥事、低階模組也只要專注在實作介面要求的契約內容就行了。

在這裡的重要前提是，我們必須了解到：並不是高階模組去依賴低階模組，而是高階模組提出它需要的功能，低階模組去實作出這些功能、達成高階模組的目標，這也比較接近我們開發程式時的思維。

例如前面的會員查詢：我們並不是因為有「DB 的連線方法」和「處理會員資料的方法」所以才說「我們有這兩個東西欸，那我們來組成會員查詢功能吧」；而是「我們想做一個會員查詢功能，所以我們需要連線到 DB，然後對這些資料做篩選和處理」

而用工程師的例子來看，應該是要這樣的：「老闆為了製造產品（高階模組的目標），開出了工程師的應徵條件（介面），而小明前來應徵（低階模組的實作）」

如此一來，依賴就「反轉」了。

原本是 高階模組 → 低階模組 的關係，變成了 高階模組 → 介面 ← 低階模組。

現在讓我們把上面例子的「工程師」改成介面，如此一來就會變成：

// 工程師的介面
public interface IProgrammer
{
    void Programming();
}

// 小明，一位工程師
public class Ming : IProgrammer
{
    public void Programming() { /* Work */ }
}

public Product Work()
{
	// 這邊需要一名工程師，呼叫小明前來
    IProgrammer programmer = new Ming();

	// 根據介面的契約，工程師一定都有 Programming 方法
    var product = programmer.Programming();
    return product;
}

這邊就會遇到我們介面篇結束時所問的問題：我們使用功能之前，必須先建立該類別的實例，也就是 new Ming()，那麼，我們不就還是直接依賴了實作嗎？

面對這個問題，大大們提出了許多個解決的方法，其中最常見的就是：控制反轉 (Inversion of Control, IoC)。

思路非常的簡單：我們把實例的建立和實例的使用切分開來就好了，讓建立的去建立、讓使用的去使用，不再是由高階模組去建立並控制低階模組，而是我們讓一個控制反轉中心去建立低階模組，然後高階模組要使用的時候再把這個低階模組交給高階模組使用。

如此一來，控制權也跟著反轉過來了，高階模組從主動建立低階模組，變成被動接收低階模組；

也就是從原先的：高階模組 —(建立)→ 低階模組
變成了：高階模組 ←(傳遞低階模組)— 控制反轉中心

也就是說，高階模組再也不需要關心如何建立，該建立哪個實體，只專注於使用功能，真正達到介面的精神。低階模組也只需要等待控制反轉中心分發，到了崗位就把份內事做好，專心在自己的職責身上即可。如此一來就能解除兩者之間的耦合。

但是，要怎麼把控制中心建立的低階模組，交給高階模組做使用呢？這時候的實作方式就是我們今天的主角：依賴注入 (Dependency Injection)。

依賴注入的種類

白話一點來說，「注入」也就是「丟進去」的意思。所以依賴注入就是指用各種方法把低階模組丟到高階模組裡。

主要常見的有三種作法：建構式注入、方法注入、屬性注入。也就是從建構式丟進去、從方法丟進去、從屬性丟進去。

建構式注入

建構式注入顧名思義就是從建立物件時的建構式進行注入。

現在假設我們有個「法師」的類別，並且它有個屬性用來表示他目前裝備的法術：

public class Wizard
{
    // 只有建構式時會給值，所以可以順手加上 readonly 防止被變動
    private readonly ISpell _spell;

    // 在建構式決定要裝備什麼法術
    public Wizard(ISpell spell)
    {
        this._spell = spell;
    }
}

public interface ISpell { } // 法術介面

而建立物件時也使用建構式來傳遞：

void Main()
{
    var spell = new Fireball();
    var wizard = new Wizard(spell);
}

public class Fireball : ISpell { } // 火球術

由於建構式注入比較符合封裝的「管控邊界」精神、能明確地讓維護者一看就知道哪些東西會被注入，因此絕大部分的時候都應該使用建構式注入，只有特殊情況可以使用方法注入和屬性注入。而到了 .Net Core 的時代，預設的 DI 容器更是只提供建構式注入。所以理想的情況下，建構式注入應該要是最熟悉的注入方式。

補充：要注意，對建構式做多載可能會造成 DI 容器混淆，不知道要選哪個建構式才好。因此設計類別時盡量以一個建構式為主，或是先了解一下使用的 DI 容器有沒有特別的處理方式再決定。

關於在 .Net Core 裡面對多個建構式的對象註冊 DI 的作法，可以參閱黑大的這篇 ASP.NET Core DI 之多建構式問題

方法注入

方法注入適用於「呼叫方法時需要注入不同的依賴對象」時。例如說該方法在不同地方被呼叫的依賴對象不一樣，又或者是第一次呼叫和第二次呼叫時的依賴對象不一樣。

這時候我們就可以在呼叫方法的時候才把依賴對象一起丟進去，讓使用端來決定要注入什麼。

例如說我們的法師可以隨身攜帶法術卷軸，使用卷軸就可以放出對應的法術，因此法師類別就會有一個使用法術卷軸的方法。而我們想要等到施法的時候再決定要用哪個卷軸的咒語，這時候就可以把這件事情交給外部決定：

public class Wizard
{
    // 施放指定的法術卷軸
    public void Enchant(ISpellScroll scroll)
    {
        scroll.CastSpell(); // 詠唱
    }
}

// 法術卷軸介面
public interface ISpellScroll
{
    void CastSpell();
}

那我們等到實際使用（使用卷軸施法）的時候再把依賴對象（卷軸）丟進去即可

void Main()
{
	var wizard = new Wizard();
	var scroll = new LevitationCharmScroll();

	wizard.Enchant(scroll); // 使用卷軸施放漂浮咒
}

// 漂浮咒
public class LevitationCharmScroll : ISpellScroll
{
    public void CastSpell() {}
}

如此一來就可以處理一些每次操作依賴對象都會不同的狀況了。但在使用方法注入的時候要注意：由於該方法的呼叫端需要準備依賴對象給方法當作參數使用，整個過程是在方法被呼叫的時候才動態處理的，所以呼叫端還是需要想辦法弄到該依賴對象，也就是再從上一層注入或是工廠製造之類的。

在這個過程中就會增加類別或介面之間的依賴關係、並且讓注入的位置散落在各地等等，維護的時候就必須多注意一下。

我個人比較常在一些輔助工具，例如擴充方法或是 Helper 看到方法注入，像這類單純操作邏輯的場合，就可以考慮採用方法注入的方式去處理。

註：絕對不要把方法注入的依賴對象留在物件內部給其他方法使用，例如Ａ方法注入了某個物件，保留給之後呼叫Ｂ方法的時候用，這樣容易造成時序耦合（Temporal Coupling）的問題，也就是使用者（通常是後續的維護人員）如果沒照你想好的順序呼叫這些方法的話，服務就會直接死去。

如果使用者不清楚這些方法之間的關係，就很容易踩到地雷，而這樣挖坑的行為很明顯違反了封裝精神，並且也容易產生預期外的副作用。如果真的有需要針對依賴對象做初始化，還是考慮用建構式注入吧。

屬性注入

接著讓我們來看看屬性注入，顧名思義就是從公開的屬性丟進去，因此也會被叫做設值注入。

通常我們會在 「外部使用者要能夠隨時切換依賴對象」或是「類別已經有預設值了，但希望提供使用者可以覆寫掉預設值的彈性」時用到屬性注入，例如說我們的法師同時只能裝備／記得一個法術，預設是火球術，但同時我們又想要可以從外部來替換裝備中的法術：

public class Wizard
{
	// 因為屬性注入的特性，請不要 readonly
    private ISpell _spell; 
    
    // 提供屬性給外部控制
    public ISpell Spell
    {
        get 
        { 
            // 屬性注入的時候要注意: 如果沒有預設值很容易會發生錯誤
            if (this._spell is null)
            {
                this._spell = new Fireball();
            }
            return this._spell; 
        }
        set 
        { 
            this._spell = value; 
        }
    }
}

public interface ISpell {} // 法術介面
public class Fireball : ISpell { } // 火球術

使用的時候就可以直接對屬性賦值，例如我們現在有個法師就不想用火球術，而是使用邪王炎殺黑龍波：

void Main()
{
    var wizard = new Wizard();
    var spell = new DragonOfTheDarknessFlame();
    wizard.Spell = spell;
}

public class DragonOfTheDarknessFlame : ISpell { } // 邪王炎殺黑龍波

我個人是覺得屬性注入的範例其實就是使用介面的封裝小範例啦…。

提到封裝，由於使用者並不會知道物件內部的狀態，所以屬性注入沒有提供預設值的話就很容易壞掉，但給預設值的時候又不可避免地產生耦合（例如上例的法師為了預設是火球術，所以和火球術產生了耦合）

因此如果有為了將來的可擴充性而設計成「預設值使用內建的、通常會存在的類別，但允許外部隨時替換」，也就是讓呼叫端決定「要不要」依賴的場合，再考慮使用會比較合適。否則一律推薦建構式注入。

組合根（Composition Root）

認識完注入的方式之後，讓我們來聊聊組合根吧。前面的例子可以注意到：即使我們要注入法術給法師，也還是要在呼叫端建立法術的實體。而如果呼叫端也使用依賴注入，就會需要呼叫端的呼叫端來注入實體。層層反轉之下，最終就會有一個地方來注入和分配全部的實體給各個物件。

這也就是我們在前面提到的：我們會需要一個負責把各個材料注入到需要的類別中的「控制反轉中心」－－也就是叫做「組合根」的部份。

由於每一個類別會將依賴的對象交給外部，也就是呼叫者去決定。而呼叫者又會再往上拋給它的呼叫者，如此不斷往外推之後，就會集中到整個應用程式的啟動點，如此一來我們也就必須在啟動點進行依賴關係的處理。

因此這個組合根的位置通常會盡可能地靠近程式的啟動點，例如整個應用程式 Startup 的地方，或是各個 DI 容器最終註冊的部分。在我們的實作例子中，也就是 API 的專案部份。

補充：請注意，組合根並不一定是在展示層，並且從「為了管理依賴關係而產生組合根」和「為了切分職責而產生展示層」是不同的觀點，不能混為一談。退一步說，我們也可能會把啟動點、組合根之類的切分出去，減少展示層的耦合。所以還是要看專案架構怎麼設計的才能確定組合根的位置。

同時，由於組合根必須分配各個類別前往自己負責的崗位，因此它可以說是和所有模組都有直接依賴的關係（並且也應該只有組合根可以知道整體的物件關聯）。因此，我們應該要在應用程式啟動的部份，找個風水寶地去統一管理我們的組合根和依賴關係，而不能讓注入的部分散亂在各地。

不過這個部份現在的 DI 容器都已經處理好了，例如 Unity 的 UnityConfig、.net Core 的 ConfigureServices 等等，所以只要注意別在其他地方偷偷搞注入、挖坑給別人跳就好囉。

註：不要以為真的遇不到……同事維護的專案就有遇到前同事直接在單元測試案例裡把 DI 容器叫出來註冊依賴注入的，都不知道從哪裡開始吐槽囧

如果在別的地方去亂對依賴關係動手動腳，很可能就會踩到一些坑。總之，盡量別在組合根以外的地方使用 DI 容器。

.Net Core 中的依賴注入

接著讓我們回到本系列的專案吧。可喜可賀的是：在 .net Core 的時代，依賴注入已經是內建提供的功能了！

補充：使用 .net Framework 的朋友也不用擔心，可以使用 Unity, AutoFac 這幾個猛猛的 IoC 容器。教學文章也是網路一抓一大把那種。

甚至到了預設使用建構式注入的 .net Core 時代，還是不少人會為了要用動態代理之類的花式注入手段而把 Autofac 裝回來呢。

我們得有一個地方來做我們的組合根，註冊介面和實體的關係，並讓它可以將實體注入進來。也就是要告訴應用程式：「某某介面對應的就是某某實作，請幫我在需要到的時候丟進來。」

在 .Net Core 中，我們可以在 Startup.cs 的 ConfigureServices 註冊我們需要的服務：

public void ConfigureServices(IServiceCollection services)
{
	services.AddControllers();

	// 這邊可能還有其他註冊的服務，Swagger 之類的
}

例如在先前的 Swagger 我們就在這裡用套件提供的 AddSwaggerGen() 註冊過 Swagger UI 服務。

使用 AddScoped 來註冊介面對應的實作類別

而當我們要註冊我們的介面和實作時，例如說我們有一個 ITestService 的介面，希望告訴 DI 容器對應的實作是 TestService，我們就可以使用 AddScoped<> 來註冊對應關係：

// 註冊 ITestService 的實作為 TestService
services.AddScoped<ITestService, TestService>();

如此一來，當 DI 容器發現要注入 ITestService 的場合，就會替我們建構 TestService 並注入。

例如說我們的 TestController 的建構式部分如下，可以看到我們有使用建構式注入：

public TestController(ITestService testService)
{
	this._testService = testService;
}

當 TestController 建立的時候，DI 容器就會知道需要 ITestService 來注入，並找到我們註冊的 TestService 來注入到 TestController。

這時候如果 TestService 也有需要注入的依賴對象，DI 容器就會再回來找我們註冊對應的實作，依此類推，不斷遞迴下去，直到注入都完成為止。

使用 AddScoped 和委派來註冊介面對應的實作類別的產生方法

有些朋友可能會有疑問：我的物件建立時還需要做一些處理才能建立，沒辦法直接告訴 AddScoped 就完事了。

不用擔心，AddScoped 也提供了委派的做法，讓我們可以直接告訴 DI 容器這個實作的產生方法，這個產生過程中我們就能進行一些操作，現在讓我們來示範一次。

假設我們的 TestService 必須要傳遞一個服務 Token 的字串進去，就會像是這樣：

services.AddScoped<ITestService>(sp =>
{
	var token = @"TestServiceToken";
	return new TestService(token);
});

那如果不只是字串這種寫死的狀況，而是我們基於一些原因，想要指定拿到註冊中其他服務的實作的話，就可以使用委派傳入的 ServiceProvider 來取得目前註冊的內容，例如這個 token 其實是另一個 ITokenService 提供的話：

services.AddScoped<ITestService>(sp =>
{
	var tokenService = sp.GetRequiredService<ITokenService>();
	var token = tokenService.Get();
	return new TestService(token);
});

可以看到，我們能藉由 ServiceProvider 的 GetRequiredService 這個方法來取得其他註冊的實體，並利用這個實體來完成注入所需的材料。

依賴注入的三種生命週期 Transient、Scoped、Singleton

除了 AddScoped() 以外，.net Core 還提供了另外兩種注入方法：AddTransient() 和 AddSingleton()，他們對應的是三種不同的生命週期：

Transient（一次性）：每次注入都建立一個新的
Scoped（作用域）：每次 Request 都建立一個新的，同個 Request 重複利用同一個
Singleton（單例）：只建立一個新的，每次都重複利用同一個

假設我們有一個 ILogger 類別，專門幫我們寫 Log。然後我們的 API 會經過 TestController、TestService、TestRepository 這三層物件去查詢資料，其中每一層都注入了 ILogger。那麼：

Transient：每一層物件都有自己的、全新的 ILogger
Scoped：同一次 API 呼叫裡的每一層物件都是用同一個 ILogger，等到下一次呼叫才建立新的 ILogger
Singleton：不論哪次呼叫、不論哪一層注入，所有人都共用同一個 ILogger

一般來說最常用的會是 Scoped，例如功能服務或登入者資訊，在同一次呼叫中保持同一個即可。但面對 HttpCilent 這類能共用同個實例節省資源的，我們就可以考慮使用 Singleton。這邊就再請各位按照使用場景來決定該用哪種生命週期。

另外，注入時請注意生命週期的範圍。例如註冊為 Singleton 的類別不能依賴註冊為 Scoped 的類別，因為如果大家一起用的 Singleton 程式跑到一半，綁在 Request 的 Scoped 依賴對象先消失了，問題可就大了，不可不慎。

關於 HttpClient 的部份，更棒的做法是使用 HttpClientFactory。可以參照：

HttpClient，該 using 還是 static? - 黑暗執行緒

在 ASP.NET Core 中使用 IHttpClientFactory 發出 HTTP 要求 | Microsoft Docs

關於 Singleton 的部份，有興趣的朋友可以了解看看。

單例模式 Singleton Pattern – LinZiyou Dev Blog

Singleton Pattern 介紹，是否為 Anti-pattern？ | by Camel | 嗨，世界

補充：.Net Core 使用 BuildServiceProvider 會建立多個實體

我們在前面提到過藉由 AddScoped 傳入委派的 ServiceProvider 的 GetRequiredService 方法來取得其他註冊的實體這個做法。

那可能就有一些比較聰明的朋友，知道 ServiceProvider 能拿到其他註冊的實體之後，為了在沒有 ServiceProvider 的地方也能取得其他實體（例如想直接在 ConfigureServices 就直接拿到實體，然後經過處理再提供給多個注入使用等等）

所以 Google 了一下怎麼弄出個 ServiceProvider，就用了 BuildServiceProvider 來建立一個 ServiceProvider，但這實際上是相當危險的。

因為 BuildServiceProvider 建立的是一個全新的 ServiceProvider，並非注入時 DI 容易幫我們建來使用的那一個 ServiceProvider，這樣就會造成有兩個 ServiceProvider 在場的狀況。

如此一來如果使用一些 Singleton 的服務，可能就會產生預期外的結果。因此建議還是乖乖在 AddScoped 之類的方法內使用委派的 ServiceProvider 比較好。

參考資料：

實作

現在我們稍微了解了 .net Core 裡的注入方式，接著就延續我們在分層架構篇的進度，來把依賴注入導入到我們本系列的 ProjectN 菜雞專案吧。在上一期，我們利用分層的概念將整個流程拆分成 Controller, Service, Repository 三個主要區塊。

其中有直接依賴的部分，會在 Controller 銜接到 Service 以及 Service 銜接到 Repository 的部份。例如：


public class CardService : ICardService
{
	private readonly ICardRepository _cardRepository;

	/// <summary>
	/// 建構式
	/// </summary>
	public CardService()
	{
		this._cardRepository = new CardRepository();
	}
}

可以注意到我們在 CardService 裡面直接 new 了 CardRepository 來使用，這就是直接依賴。

註：前篇分層時用到的 AutoMapper 套件的注入方式，請參見 AutoMapper#走向注入，此處暫且忽略。

基於依賴反轉原則，我們會希望達成「CardService 依賴的是 ICardRepository 這個介面，並由 CardRepository 實作該介面，藉由介面隔離實作來解除耦合」的目標。

對這個概念不太熟悉的朋友，可以參照介面與依賴反轉原則的說明

開始重構為建構式注入

現在讓我們改成使用建構式注入吧：

public class CardService : ICardService
{
	private readonly ICardRepository _cardRepository;

	/// <summary>
	/// 建構式
	/// </summary>
	public CardService(ICardRepository cardRepository)
	{
		this._cardRepository = cardRepository;
	}
}

接著為了要讓 DI 容器知道 ICardRepository 對應的實作是 CardRepository，讓我們前往 Startup.cs 的 ConfigureServices 把它註冊起來：

public void ConfigureServices(IServiceCollection services)
{
	// 註冊 ICardRepository 的實作為 CardRepository
	services.AddScoped<ICardRepository, CardRepository>();

	services.AddControllers();

	// 這邊可能還有其他註冊的服務，Swagger 之類的
}

補充：請注意前面提到過的「組合根會直接依賴所有註冊的模組」因此這邊有需要的話記得把參考 using 補上呦。

並且由於這個範例的組合根在展示層，因此和上篇的三層式架構圖略有不同，展示層也會依賴到資料存取層，還請注意。

接著讓我們如法炮製，把 Controller 裡直接依賴的 Service 也拆開吧：

[ApiController]
[Route("[controller]")]
public class CardController : ControllerBase
{
	private readonly ICardService _cardService;

	/// <summary>
	/// 建構式
	/// </summary>
	public CardController(ICardService cardService)
	{
		this._cardService = cardService;
	}
}

然後補上註冊。

public void ConfigureServices(IServiceCollection services)
{
	services.AddScoped<ICardService, CardService>();

	services.AddScoped<ICardRepository, CardRepository>();

	services.AddControllers();

	// 這邊可能還有其他註冊的服務，Swagger 之類的
}

最後再將前面系列用到的一些工具，例如 AutoMapper, Dapper 給注入好（這部分就請根據自己專案的內容調整囉），就完成啦。

那我們前面有提到，可以用「告訴 DI 容器該物件的產生方法」來做一些額外的事情，這邊就讓我們優化一下。

我們在先前的 CardRepository 有用私有欄位來存放連線字串：

/// <summary>
/// 卡片管理
/// </summary>
/// <seealso cref="ProjectN.Repository.Interface.ICardRepository" />
public class CardRepository : ICardRepository
{
	/// <summary>
	/// 連線字串
	/// </summary>
	private readonly string _connectString = @"Server=(LocalDB)\MSSQLLocalDB;Database=Newbie;Trusted_Connection=True;";
}

現在我們希望連線字串不要寫死在類別裡，而是用建構式注入的方式丟進去，就會變成：

/// <summary>
/// 卡片管理
/// </summary>
/// <seealso cref="ProjectN.Repository.Interface.ICardRepository" />
public class CardRepository : ICardRepository
{
	/// <summary>
	/// 連線字串
	/// </summary>
	private readonly string _connectString;

	public CardRepository(string connectString)
	{
		this._connectString = connectString;
	}
}

接著讓我們回到註冊 ICardRepository 的地方，因為 CardRepository 的建構式現在必須要提供連線字串了，所以我們要改一下 AddScoped 的寫法，把連線字串丟給它：

services.AddScoped<ICardRepository>(sp =>
{
	var connectString = @"Server=(LocalDB)\MSSQLLocalDB;Database=Newbie;Trusted_Connection=True;";
	return new CardRepository(connectString);
});

可以看到我們用 AddScoped 提供了 ICardRepository 對應物件的產生方法。

這樣 .net Core 就會知道要先執行裡面的委派與匿名函式 sp => {}，就能拿到 CardRepository 來用囉！

補充：從 appsettings.json 取得組態

另外補充一下，在連線字串這類字串的注入時，我個人偏好更進一步使用 appsettings.json（以前 .net framework 時用過 web.config 的朋友可能會比較熟）

關於 appsettings.json 的用法這邊就不再贅述，想了解的朋友可以參考這幾篇：

如何讀取 AppSettings.json 組態設定檔 | 余小章 @ 大內殿堂

ASP.NET Core 練習 - 使用 appSetting - 黑暗執行緒

如何取得 appsettings.json 組態設定 ~ m@rcus 學習筆記

因此這邊就把連線字串丟到 appsettings.json，增加一欄 ConnectionString：

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  },
  "AllowedHosts": "*",
  "ConnectionString": "Server=(LocalDB)\\MSSQLLocalDB;Database=Newbie;Trusted_Connection=True;"
}

接著回到 Startup 的建構式，建立一個連線字串的欄位 _connectionString 然後把連線字串讀出來：

public class Startup
{
	private readonly string _connectionString;

	public Startup(IConfiguration configuration)
	{
		Configuration = configuration;
		this._connectionString = configuration.GetValue<string>("ConnectionString");
	}
}

這樣我們就完成了 Startup 的連線字串注入囉，只要再把這個字串提供給 CardRepository 就行了：

services.AddScoped<ICardRepository>(sp =>
{
	return new CardRepository(_connectionString);
});

如果沒有多個類別共用同一個連線方法的話，我們也可以直接從組態拿就行了：

services.AddScoped<ICardRepository>(sp =>
{
	var connectionString = this.Configuration.GetValue<string>("ConnectionString");
	return new CardRepository(connectionString);
});

再請根據狀況靈活地運用 Configuration.GetValue 吧！

補充，也可以使用 IOption 的方式處理，或是包裝成一個專門提供的物件，像是 IConnectionProvider 之類的，可以彈性地選擇做法。

補充：組合根請稍作分類

這邊補充一下，在實務上由於一個應用程式的注入可能有數十個，因此我們會稍微用註解或可摺疊的 #Region 來分段一下，例如：

public void ConfigureServices(IServiceCollection services)
{
    // Service
	services.AddScoped<ICardService, CardService>();
	
    // Repository
	services.AddScoped<ICardRepository, CardRepository>();
	
    // Others
	services.AddControllers();
}

// 或是使用 region，數量很多的時候就可以收攏
public void ConfigureServices(IServiceCollection services)
{
    #region -- Service --
	
	services.AddScoped<ICardService, CardService>();
	
	#endregion
	
	#region -- Repository --
	
    // Repository
	services.AddScoped<ICardRepository, CardRepository>();
	
	#endregion
		
    // Others
	services.AddControllers();
}

而前幾個月的時候，敝司某服務的註冊數量多到一個連滑鼠中鍵滾輪都會痛哭的程度。咱同事就利用對 IServiceCollection 做擴充方法的方式，將組合根分類並切出去管理：

// ProjectN.DIExtensions

/// <summary>
/// Service 相關註冊
/// </summary>
public static class ServiceDIExtensions
{
	public static IServiceCollection AddServices(this IServiceCollection services)
	{
		services.AddScoped<ICardService, CardService>();

		return services;
	}
}

// Startup.cs
public void ConfigureServices(IServiceCollection services)
{
	services.AddServices(); // 呼叫 ServiceDIExtensions 進行註冊

	services.AddRepositories();

	services.AddControllers();
}

雖然可以有效把註冊切分出去，但也會沒辦法在同個地方管理所有註冊，略麻煩，還是請真的有需要的時候再嘗試。這邊就當作分享這個做法給大家。

驗證

現在我們已經將三層的內容都改成使用注入了，最後就來測試一下是否有串接成功吧！

下中斷點，可以看到我們 CardService 要求的 ICardRepository 的確傳入了實作的 CardRepository

也成功從資料庫中查詢到卡片了！打完收工～

小結

這篇文章介紹了一些依賴注入的作法，並在 .net Core 的專案上進行實作。這邊就做個小總結：

為什麼要依賴注入
- 解除類別與類別間的直接耦合
- 由組合根來負責物件的建立和傳遞，更能讓依賴雙方專注於自己的職責
依賴注入常見的做法有
- 建構式注入：把依賴對象從建構式扔進去
- 屬性注入：把依賴對象從公開屬性扔進去
- 方法注入：呼叫方法時再把依賴對象當參數扔進去
.Net Core 中的依賴注入
- 已內建，我們可以在 Startup.cs 的 ConfigureServices 進行註冊
- .Net Core 中，依賴注入的生命週期有
  - Transient（一次性）：每次注入都建立一個新的
  - Scoped（作用域）：每次 Request 都建立一個新的，同個 Request 重複利用同一個
  - Singleton（單例）：只建立一個新的，每次都重複利用同一個

最後還是要叮嚀一下，依賴注入在實務上還會遇到許多眉角，不同的 DI 容器也會提供不同的方法，或是面對眼前的架構不知道從何拆起之類的，這些都是重構日常。

例如說：

等等的問題。

但我個人認為只要有依賴反轉、隔離耦合這些依賴注入的基本觀念，剩下的就是了解工具如何使用、開 Google 查詢有哪些坑的步驟而已了。~~然後上班一半時間都在 Google~~

除了藉由依賴注入去解耦合，避免讓類別成為控制狂（就是指類別依賴的對象都自己 new 出來，從建立到生命週期都由類別自己控制，最終變成強耦合的狀況）以外，我們使用依賴注入的時候，有時會發生一些令人困惑的事情，這些其實就是讓我們動手重構的好幫手。

例如說循環依賴，當我們發現Ａ類別依賴了Ｂ類別，Ｂ類別又依賴Ａ類別而發生錯誤時，就可以考慮是不是能夠整合這兩個類別，例如抽出一個更高階的類別來統合這兩個類別的動作流程等等。

又或是像過度注入：當我們用建構式注入的時候，有時候會發現其中幾個類別的建構式會變得超級肥，可能光是傳入參數就多達二三十個等等。

這時候其實就是一種警示：這個類別為什麼會依賴這麼多對象？是不是這個類別的職責太多了？

諸如此類，依賴注入其實可以幫助我們重新梳理我們類別的邊界和耦合關係，讓我們注意到一些需要重構的徵象。這也是最近跟著同事重構的心得哪。

那麼今天就先到這兒，祝各位解耦順利、斷開魂結。那麼，我們下次見～

參考資料

其他參考資料：

本系列文章

在 Swagger UI 加上驗證按鈕，讓 Request Header 傳遞 Authorize Token

Igouist (Igouist) — Sat, 16 Oct 2021 23:50:00 +0800

在先前的菜雞新訓記 (4): 使用 Swagger 來自動產生簡單好看可測試的 API 文件吧中，我們介紹了在 .net Core 環境使用 Swashbuckle 套件來產生 Swagger 文檔，並且直接在 Swagger UI 中呼叫 API 來進行測試。

但很多時候，我們的 API 會需要先驗證才能使用，例如在 Header 傳遞 Token 來驗證身分等等。這時候 Swagger UI 就會整個廢掉，打了都會出錯，很不方便。

因此這篇文章就紀錄一下如何在 Swagger UI 上加入 Authorize Token 的傳遞，讓 Swagger UI 在需要身分驗證的環境也能直接呼叫使用。

章節目錄

環境佈置

首先範例專案直接參考 The Will Will Web 的這篇如何在 ASP.NET Core 3 使用 Token-based 身分驗證與授權 (JWT)，捏一個需要登入取得 JWT Token，然後將 Token 放到 Header 的 Authorize 才能查詢資料的專案。

專案的大致狀況和目前 Swagger UI 如下，有登入和查詢兩支方法：

那我們沒有登入的情況直接呼叫查詢方法就會報錯：

登入的話就能拿到 Token：

用 Postman 試試看把 Token 掛到 Authorization，查詢就可以成功：

但是我們的 Swagger 還沒有提供能放 Authorization Token 的地方，這樣用起來就會 Hen 不方便。

因此目標就是：可以將這組 Token 放到 Header 裡，讓查詢方法不要報錯。讓我們開始吧！

加入 Authorize 設置

首先讓我們先找到註冊 Swagger 產生器的地方，以先前的 Swagger 介紹文為例的話，會是在 Startup.cs 的 ConfigureServices 裡的 AddSwaggerGen。

裡面可能已經有包含 API 簡介等欄位，例如：

// 註冊 Swagger 產生器
services.AddSwaggerGen(options =>
{
    // API 服務簡介
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "JWT Demo",
        Description = "菜雞嘗試 JWT 的範例 API",
        TermsOfService = new Uri("https://igouist.github.io/"),
        Contact = new OpenApiContact
        {
            Name = "Igouist",
            Email = string.Empty,
            Url = new Uri("https://igouist.github.io/about/"),
        }
    });

    // 讀取 XML 檔案產生 API 說明
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    options.IncludeXmlComments(xmlPath);
});

首先讓我們用 Security Scheme 來告訴 Swagger 我們的驗證資訊吧。在 AddSwaggerGen 中加上 AddSecurityDefinition：

options.AddSecurityDefinition("Bearer", 
    new OpenApiSecurityScheme
    {
        Name = "Authorization",
        Type = SecuritySchemeType.ApiKey,
        Scheme = "Bearer",
        BearerFormat = "JWT",
        In = ParameterLocation.Header,
        Description = "JWT Authorization"
    });

加了之後就能在 Swagger UI 看見我們的 Authorize 按鈕囉：

點開就會看到我們上面定義的內容：

不過現在還不會作用，我們還得讓全部的呼叫都自動加上這個 Token 才行。接著在 AddSwaggerGen 中加上 AddSecurityRequirement，並且讓他去抓我們前面設定好 “Bearer” 的 SecurityScheme：

options.AddSecurityRequirement(
    new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "Bearer"
                }
            },
            new string[] {}
        }
    });

注意 Id 要和我們上一步加入的 Scheme 一致呦。

補充：OpenApiSecurityRequirement 是一個 Dictionary，所以中間那層 {} 不要忘囉

加完之後現在的 AddSwaggerGen 大概是這個樣子的：

// 註冊 Swagger 產生器
services.AddSwaggerGen(options =>
{
    // API 服務簡介
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "JWT Demo",
        Description = "菜雞嘗試 JWT 的範例 API",
        TermsOfService = new Uri("https://igouist.github.io/"),
        Contact = new OpenApiContact
        {
            Name = "Igouist",
            Email = string.Empty,
            Url = new Uri("https://igouist.github.io/about/"),
        }
    });

    // Authorization
    options.AddSecurityDefinition("Bearer", 
    new OpenApiSecurityScheme
        {
            Name = "Authorization",
            Type = SecuritySchemeType.ApiKey,
            Scheme = "Bearer",
            BearerFormat = "JWT",
            In = ParameterLocation.Header,
            Description = "JWT Authorization"
        });

    options.AddSecurityRequirement(
        new OpenApiSecurityRequirement
        {
            {
                new OpenApiSecurityScheme
                {
                    Reference = new OpenApiReference
                    {
                        Type = ReferenceType.SecurityScheme,
                        Id = "Bearer"
                    }
                },
                new string[] {}
            }
        });

    // 讀取 XML 檔案產生 API 說明
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    options.IncludeXmlComments(xmlPath);
});

完工測試

接著就讓我們啟動試試吧！

首先讓我們把登入的 Token 放到 Authorization 按鈕的欄位裡，不要忘記加上 Bearer：

加入之後就 Close，讓我們打看看查詢的方法：

可以看到成功拿到值啦！

從開發工具也可以看到 Header 的確有加上 Bearer Token 了：

大功告成，打完收工！

參考資料

菜雞抓蟲: DateTime.ToString() 之我們不一樣 & CultureInfo 文化特性小筆記

Igouist (Igouist) — Mon, 04 Oct 2021 22:00:00 +0800

事發緣由

咱們內部套件中有個方法，會將各個參數組合為 QueryString 去打指定的 Api。就是這麼稀鬆平常的場景，神奇的事情就發生了。

同樣的套件、同樣的語法，在團隊中兩個人的電腦上安裝執行，卻是一個成功一個失敗。

原來該方法的參數中，包含一欄型別為 DateTime 的資料，並且會把該欄位的值拿來 ToString() 再做為參數傳遞給目標 Api。

而呼叫失敗的人就是在這個 DateTime.ToString() 的過程中產生了中文字，使得目標 Api 接到參數後，無法將中文字轉換回 DateTime 而發生了錯誤。

問題就浮現了：同一行 DateTime.ToString() 在不同電腦執行的結果竟然不一樣？！

為了讓我們更快了解狀況，現在就簡單地使用 Linqpad 進行測試：

void Main()
{
    DateTime.Now.ToString().Dump();
}

首先，在我的 Windows 時間設定中，完整時間的格式為 09:40:07 ，也就是 24 小時制。

現在讓我們先執行上面這段語法看看：

// 2021/10/04 21:00:00

接著讓我們變更時間格式看看。

以我的 Win10 為例，在 Windows 工具列，也就是畫面的右下角右鍵，選擇 調整日期時間 → 日期時間格式設定 → 變更資料格式，將時間格式變更為 上午 09:40:07。

重新啟動 Linqpad 再執行如下：

// 2021/10/04 下午 09:00:00

可以看到 下午 兩個字就蹦出來了！

之所以會有這樣的差異，是因為 DateTime.ToString() 預設轉換的目標格式會是抓取目前執行緒的文化特性。

文化特性

在 CSharp 中有個專門負責處理文化特性、地區設定等在地化處理的類別：CultureInfo。舉凡國家地區的資訊、時間日期的格式、字串的排序方式等等，都是它的工作。

要取得當前的文化特性，我們可以使用 CultureInfo.CurrentCulture：

CultureInfo.CurrentCulture.Dump(); // zh-TW

可以看到我們目前的文化特性是 zh-TW，這個格式叫做 IETF 語言標籤，其中 zh 是指語言，TW 則是地區。例如說 en-US 就是「英語，美國」。

補充：關於語言標籤，有需要查詢的朋友可以翻看看 i18n 的 RFC 3066 表。
此外，我們平常用的語言標籤還會有一些子標籤之類的，例如 zh-Hant-HK，可以參見 Language tags in HTML and XML (w3.org)

補充：除了 CurrentCulture 以外，CultureInfo 還有另一組文化特性的設定：CurrentUICulture。從名稱上可以看得出來，前者是用來預設系統的文化設定，例如數值、排序等等；而加上 UI 的後者，則是用來預設使用者介面要顯示什麼語言。

當然，大多數時候這兩個文化特性會是一樣的，不過如果想要國際化，弄個使用者介面的多國語言版本，就需要特別注意一下囉！

What is the difference between CurrentCulture and CurrentUICulture properties of CultureInfo in .NET? - Stack Overflow

ASP.NET 多國語系 - 了解文化特性 | 余小章 @ 大內殿堂 - 點部落 (dotblogs.com.tw)

ASP.net Core 多國語系 Part 1 初探篇 | 高級打字員的技術雲 - 點部落 (dotblogs.azurewebsites.net)

接著讓我們來看看裡面包了哪些重要東西吧：

DateTimeFormat

DateTimeFormat 是用來放跟 DateTime 相關的設定值的，其中包含了該文化的日期時間的顯示格式。

我們同樣用 Linqpad 看一下裡面有些什麼：

CultureInfo.CurrentCulture.DateTimeFormat.Dump();

可以看到裡面包含了一年有哪些月份和名稱、一週有哪些日子和名稱，以及一堆時間格式。

那一堆時間格式主要是對照標準日期和時間格式字串的。

例如 ShortDatePattern 就是對應到文件中的簡短日期模式（"d"），也就是說，當我們 ToString 的時候，如果使用 “d” 的話，就會根據文化特性顯示該文化的「簡短日期」以此類推。

關於這部分的欄位內容，可以參照 Vito 大大的使用文化特性這篇文章，裡面的整理已經相當詳細，供各位參考。

補充：我們常常會看到 ToString("yyyy-MM-dd HH:mm:ss") 這種用法，但要小心這邊的 - 和 : 其實是用來標示日期和時間的分隔符號，並不是真正的 - 和 :。

所以 : 在 format 的時候，會被替換為 TimeSeparator；
而 / 同樣也會使用 DateSeparator

也就是說，如果你使用的文化特性 TimeSeparator 是 # 的話，HH:mm:ss 在 21:07:00 出來的結果將會是 21#07#00。如果發現 ToString 出來的結果怪怪的，可以優先檢查文化特性的這兩個分隔符號有沒有問題。

相關的說明請參見 Date and time separator specifiers 這一小節。

現在讓我們用 Thread.CurrentThread.CurrentCulture 來更改當前執行緒的時間，並用完整日期時間模式（"F"）來測試看看：

var date = new DateTime(2006, 1, 2, 3, 4, 5);

Thread.CurrentThread.CurrentCulture = new CultureInfo("zh-tw");
date.ToString("F").Dump(); // 2006年1月2日 03:04:05

Thread.CurrentThread.CurrentCulture = new CultureInfo("zh-cn");
date.ToString("F").Dump(); // 2006年1月2日 3:04:05

Thread.CurrentThread.CurrentCulture = new CultureInfo("en-us");
date.ToString("F").Dump(); // Monday, January 2, 2006 3:04:05 AM

當然，在 ToString 的時候直接扔文化特性進去也是可以的：

var date = new DateTime(2006, 1, 2, 3, 4, 5);

date.ToString(new CultureInfo("zh-tw")).Dump(); // 2006/1/2 03:04:05
date.ToString(new CultureInfo("zh-cn")).Dump(); // 2006/1/2 3:04:05
date.ToString(new CultureInfo("en-us")).Dump(); // 1/2/2006 3:04:05 AM

而本篇起因的翻船事件，我們可以試著觀察一下 CultureInfo 的預設曆法，也就是 Calendar 的內容：

void Main()
{
	CultureInfo.CurrentCulture.Calendar.Dump();
	CultureInfo.CurrentUICulture.Calendar.Dump();
}

// 完整時間格式: 15:04:05
// MinSupportedDateTime 0001/1/1 上午 12:00:00
// MaxSupportedDateTime 9999/12/31 下午 11:59:59

// 完整時間格式: 下午 03:04:05
// MinSupportedDateTime 0001/1/1 00:00:00
// MaxSupportedDateTime 9999/12/31 23:59:59

可以明確看到格式的變更，兇手就在我們之中！

其實文檔已經明確地說了：使用者可以透過主控台的『地區及語言選項』部分，選擇覆寫與 Windows 目前文化特性相關聯的一些值。（CultureInfo.Calendar 屬性 (System.Globalization) | Microsoft Docs）

當然，我們也可以調整 Calendar 來把曆法換掉。例如說當我們要做西元年轉民國年的時候，就可以把 Calendar 指定為 TaiwanCalendar 來處理。

這部分請參照：mrkt 的程式學習筆記: 基本題 - C# 西元年轉換取得民國年格式字串

有了這些日期時間的格式，我們就可以用它們來處理一些日常的時間處理囉～例如：

NumberFormat

除了日期格式以外，數值也是各個文化常常不同的部份。在 CultureInfo 中的 NumberFormat 就是用來處理數值相關的格式。

我們同樣用 Linqpad 看一下裡面有些什麼：

CultureInfo.CurrentCulture.NumberFormat.Dump();

可以看見裡面包含了 CurrencySymbol 貨幣符號、PercentSymbol 百分比符號、CurrencyNegativePattern 貨幣負數格式等等數值相關的設定。

現在讓我們使用 ToString("C") 來指定轉換為貨幣格式，並且丟不同的文化特性進去看看吧：

var price = -49.99;

price.ToString("C", new CultureInfo("zh-tw")).Dump(); // -NT$49.99
price.ToString("C", new CultureInfo("zh-cn")).Dump(); // ¥-49.99
price.ToString("C", new CultureInfo("en-us")).Dump(); // ($49.99)

可以看見整個格式都不一樣了呢。

備註：CurrencyNegativePattern 這類的格式只會存數字編號，例如 0 對應到 ($n) 之類的。各編號對應的格式可以參見 NumberFormatInfo.CurrencyNegativePattern 屬性 (System.Globalization) | Microsoft Docs

InvariantCulture

那麼，當我們想要統一格式的時候呢？例如說我們在世界各地都有服務，這些客戶端的資訊會集中傳回主伺服器。要是直接 ToString 那鐵定是每個地方回來的時間、貨幣和數值格式都不一樣的。該怎麼辦呢？總不能發個字串下去叫大家寫死吧囧？

這時候就可以使用 InvariantCulture 啦！

讓我們看看文檔是怎麼說明的：「取得與文化特性無關的 (不變的) CultureInfo 物件」、「不區分文化特性的文化特性不區分文化特性」（也太饒舌）

也就是說，只要使用約定好一起使用這組不變的文化特性，就可以保證大家的格式都是同一套囉。

使用的時候可以 CultureInfo.InvariantCulture 或是直接 new CultureInfo("") 就可以取得這組不變的文化特性。

var culinfo = CultureInfo.InvariantCulture;

var date = new DateTime(2006, 1, 2, 3, 4, 5);
date.ToString(culinfo).Dump(); // 01/02/2006 03:04:05

var price = -49.99;
price.ToString("C", culinfo).Dump(); // (¤49.99)

~~不過如果覺得月/日/年的格式很鳥的話，其實大家約好挑一組文化特性就好了齁？~~

後日談

最後交代一下篇頭的問題怎麼解決的：

直接把該套件打開然後把 .ToString() 加上 "yyyy/MM/dd" 打完收工囧。

就是這麼簡單。爽發一篇廢文，筆記筆記。

2022.05.06 補充：

朋友在將 Asp.net Framework 的服務佈到多台 Windows Server 上時，也遇到了時區設定不一致的問題。

經過一番排查，最後決定在 Web.config 中的 System.web 設定 Globalization 指定服務採用的時區來解決這個問題。

這邊也提供相關的資訊給遇到同樣問題的朋友們參考：

多國語系 - 了解文化特性 | 余小章 @ 大內殿堂 - 點部落 (dotblogs.com.tw)

請參閱：「在 Web.config 設定文化特性」一節

在 ASP.NET 中以程式設計方式設定目前的文化環境 | Microsoft Docs

參考資料

菜雞新訓記 (5): 使用三層式架構來切分服務的關注點和職責吧

Igouist (Igouist) — Sun, 03 Oct 2021 14:00:00 +0800

這是俺整理公司新訓內容的第五篇文章，目標是使用三層式架構 (3-Layer Architecture) 來切分服務的關注點和職責。

什麼是分層？分層可以吃嗎？

天地混沌如雞子，商業邏輯生其中。

萬八千歲，天地開闢。表現層為天。資料層為地。商業邏輯層在其中……

　　　　－－民明書坊《盤古與他的CRUD之旅》

根據民明書坊的文獻記載，我們常聽到的「天地玄黃，宇宙洪荒」云云，其實指的就是上古時期的開發狀況。當時世界還是一片混沌，所有的程式碼都混雜成一坨，不是所有東西寫在一起你儂我儂，一言不合就三千行；就是依賴關係交錯複雜，改了北極壞南極。

要說有多亂呢，大概就算前人嘗試引入了 MVC，也只是改成把所有程式都塞在 Controller 而已，其絕望程度可見一斑。

這時候隔壁課的老盤調過來接刀，一看不得了，便決定先對這屎山整頓一番。他大喝一聲，那些靠近使用者的便上浮起來化作了天，親近資料庫的便沉澱下去變成了地，而所有的商業邏輯就連接著兩者，支撐起了整個專案。這也就是分層架構的由來。

三層式架構

分層架構是運用最為廣泛的架構模式，幾乎每個軟體系統都需要通過層（Layer）來隔離不同的關注點（Concern Point），以此應對不同需求的變化，使得這種變化可以獨立進行；此外，分層架構模式還是隔離業務複雜度與技術複雜度的利器。－－ Ray’s Notes

一般來說，最常見的分層架構就是三層式架構了。

三層式架構顧名思義就是把應用程式分成三層，通常會分成「展示層、商業邏輯層、資料存取層」。

現在讓我們認識一些他們的分工吧！

三層式架構的常見分層有：

展示層（Presentation Layer）

咱們軟體的門面。負責搞定需要跟外部使用者互動的部份，例如接收使用者的請求、路由的控制、呼叫的流程控制等等
日常工作就是確實地接收使用者的請求，然後叫商業邏輯層去處理，最後把商業邏輯層弄好的東西奉上給使用者
大多時候的開發會在 Controller 進行，例如 ProductController

商業邏輯層（Business Layer）

咱們軟體的核心。負責處理商業邏輯，也就是商業規則和相關的邏輯處理都在這裡進行
日常工作就是接收展示層的呼叫、和資料存取層拿資料。在這個來往的過程中將資料內容進行商業邏輯的處理
常見的後綴有 BLL, Service 等等，例如 ProductService

資料存取層（Data Layer）

顧名思義，就是負責存取資料的相關操作
日常工作就是根據商業邏輯層的要求，去資料庫存取資料
常見的後綴有 DAL, Repository 等等，例如 ProductRepository

另外一些比較中大型的架構會把共用的部份抽出來，就會多一層：

共用層（Common Layer）
- 負責放一些各層之間會共用到的工具。例如擴充方法、列舉等等
- 因為是用來放各種工具的，所以需要分離出一層，來讓各層都可以使用

用最常見的餐廳來比喻的話，資料庫大概就像是存放食材的冰箱、其他服務的ＡＰＩ就像是供應商之類的，各層的分工就會像這樣：

資料層：負責採買食材、去冰箱拿食材等等
業務層：根據各式各樣的食譜把食材變成料理
展示層：負責櫃台的點餐，將做好的料理呈上給客人

對這種過於模糊的比喻不太能理解的朋友，假設今天某網站的管理後台有個查詢某客戶的請求，可能會是這樣子：

展示層收到使用者查詢客戶的請求
- ex: GET Cust/1 -> CustController.Get(int custId)
展示層檢查是否登入和權限 ex: [Authorize(Roles = UserRole.Admin)]
展示層呼叫商業邏輯層查詢客戶 ex: CustService.Get(int custId)
商業邏輯層呼叫資料存取層查詢客戶 ex: CustRepository.Get(int custId)
資料存取層從 Cust 資料表取回資料
商業邏輯層繼續執行，發現有「查詢客戶時需同時列出該客戶五筆最近訂單簡介」的規則
- ~~別問為什麼，問就是 Feature~~
商業邏輯層呼叫資料存取層
- ex: OrderRepository.GetLast(int custId, int count = 5)
資料存取層從 Order 資料表取回資料
商業邏輯層根據規則組裝資料，回傳給展示層
展示層取得商業邏輯層回覆的資料，回傳給使用者

大概就是這種感覺。

當然，這邊還是要再提醒一下：分層架構並不是只有三層式架構，根據需求也可能會再增加或是減少。同樣地，分層架構只是一種「分工的概念」，並不是只限於軟體，也不一定得就是這三層。

曾經也有聽過「瀏覽器（展示層）、伺服器（商業邏輯層）、資料庫（資料存取層）」的說法，也看過遊戲是用「整體策略、基本操作」等動作規模去分層的，因此只需要有「把工作依據職責切分到不同層」的概念就可以了，切莫要走火入魔。

關於 DTO

我們回到上面的例子，可以注意到各層之間必須要頻繁地溝通、傳遞資訊。因此我們就會需要一些物件來幫忙在各層之間傳遞這些資料，這些只有資料欄位、沒有任何方法的物件就是 DTO（Data Transfer Object, 資料傳輸物件）

在分層架構裡面使用 DTO 是絕對必要的，除了層與層之間需要讓資料傳遞之外，也能帶來幾個好處，例如：

封裝過多的參數
- 針對參數過多的方法，我們可以收納成 Dto 來隱藏複雜性
- 封裝前 GetProductList(int custLevel, string custName, int.....)
- 封裝後 GetProductList(GetProductParameter parameter)
減少層與層之間的耦合
- 當有修改欄位的時候，有時只需變動 DTO 就可以了
- 各層之間的溝通使用 Dto 傳輸，可以減少各層直接彼此影響的耦合狀況

這裡其實就是將「資料」和「方法」切割開來封裝的概念。如果切分得不錯的話，在呼叫的過程就會像是工廠流水線的感覺，資料隨著運輸帶到達每個工作區，然後工作區對資料進行處理之後，再送上運輸帶前往下個工作區，經歷了壯闊的旅程（？）之後最後終於到達使用者手上。

不過相對的，每層之間都用 DTO 去通訊、過多的參數封裝成 DTO 等等，都會增加整個系統中的類別數量，有時候甚至會多到畫面上列不下的程度（我的 DTO 就像宇宙一樣廣闊！區區方案總管休想裝得下我！），反而造成管理和修改上的困難。

因此 DTO 的應用場景，例如說是每一層都需要獨立的 DTO 嗎？或是使用同一個 DTO 來操作呢？會不會共用了參數反而造成耦合呢？都要到開發的時候來作取捨。

關於上面這段重複建立 DTO 的問題，我們在最後的 QA 階段再稍微聊一下吧，先讓我們把鏡頭轉回分層架構。

為什麼我們需要分層架構？

專案分層架構其目的就是為了要職責確立、關注點分離，讓不同的方法或類別去做該做的事情而且只專注於這些方法、類別的職責上－－ mrkt

當我們想知道為什麼要使用分層架構，最快的方式就是了解一下採用分層架構的諸多好處。且讓我數給你聽：

更符合單一職責、關注點分離

也就是我們在單一職責原則篇曾提到的：「把工作交給負責該職責的類別去做，自己只需要關注在自己正在處理的職責即可」。如果一來就可以封裝出邊界、減少彼此耦合影響的機會，也可以減少閱讀大量不相關的程式碼。

關於單一職責的介紹，和我們著重職責所帶來的好處等等，
可以參閱之前的：菜雞與物件導向 (10): 單一職責原則。

快速鎖定目標、縮小範圍

因為關注點分離成多個層（Layer）了，當物件的設計有符合職責的話，在開發或除錯時，甚至能像查詢表格一樣迅速！

當分層和類別的定義都合乎職責的時候，在接收到需求的同時也就能抓出目標範圍在哪了，例如：

這次針對某功能的一些判斷邏輯有變動 => OK，先從 Service 開始看
這個資料表的欄位名字被換掉了 => OK，往 Repository 前進
這個路由可以幫我調整一下嗎 => OK，Controller 改起來

原先你可能要先閱讀一坨又臭又長的程式碼，經歷一場垃圾探險記、花一堆時間從裡面找到你要改的地方才能開工。有明確的架構之後，就可以大幅地提升精準度，直接往相應職責的地方去就對了。

因此，乾淨、分工明確的架構可以給你大方向的指引，替你省下許多垃圾時間，實在是舒服許多。

適合多人合作、減少碰撞率

因為範圍縮小了，多人合作的時候就可以靈活地去調度、搭配，提升開發時的效率。

除了平常的你負責Ａ功能、我負責Ｂ功能以外，也可以嘗試讓比較熟悉資料庫的朋友處理資料存取層、負責和 API 使用端商談規格的朋友先在展示層開好 API 接口等等。

如此就有了可以根據狀況從分層或是功能等方向去分工的彈性。並且這樣的分工也能減少碰撞率 ……至少會讓 Git 的衝突少一點囧。

增加程式碼的複用性

最後也是最有感覺的就是增加程式碼的複用性了。在商業邏輯中可能很多地方都會用到其他來源的資料來加工組合，例如查詢客戶的時候要一併列出訂單、推薦商品的時候要附上目前的優惠活動等等。

這時候如果分層明確，一些像是資料存取層中的「查詢訂單」這種簡單又符合單一職責的方法，我們就可以加以取用，靈活組合出目前的需求。

比起到處都把同一段撈資料的 Code 複製貼上複製貼上，然後要修改的時候整個遍地開花的狀況，能夠重複使用實在是舒服許多。

到目前為止這應該是我最有感覺的一項，當你需要撈某個資料出來，發現隊友或是之前的自己已經寫好一個乾淨可用好擴充的 Function 在那邊讓你直接呼叫，那感覺真的是一個爽呀！

提供抽換的靈活度

這一項比較像是前面各項產生的結果。由於我們根據了不同職責來拆分出各層，因此當我們面臨問題的時候是可以整層進行抽換的。

例如說當我們除了原先的網頁以外，還要提供 API 服務，那麼展示層即使抽換成了 Web API 專案，對整體的架構仍不會有影響，還是能保持同一套商業邏輯。

又或者是說今天這個專案的資料來源要從 MySQL 換到 MSSQL 之類的，我們就可以把資料存取層替換掉，而不影響商業邏輯和展示層的運作。

享受以上優點的前提

但要真的享受到上述的各項優點，還是需要達成一定的條件的，並不是說直接切三塊就「完！」這樣。例如說：

物件的設計需要遵守 SOLID 原則
- 包括物件符合單一職責、各個物件之間使用介面來減少耦合等等
- 其實這一項還蠻直覺的：畢竟如果你的方法完全不管單一職責，動不動就塞個上百行的 SQL 之類的，當然就很難重複利用了嘛
需要降低各層之間的依賴
- 為了解除層與層之間的直接依賴，因此會需要使用介面和依賴注入等解耦手段
- 只有將各層之間的耦合降低，才能實現可替換、關注點分離等效果
- 關於依賴注入的概念，可以參照依賴注入章節
- 註：本篇的範例會先建立簡單的分層，下一篇才會進入依賴注入的實作
可能會有額外的開發成本
- 即使是再簡單的功能，例如單純的查詢，也必須要貫穿每一層。自然就增加了開發成本
  - 有時候只是為了要多提供一個欄位給使用者，就會變成從上到下的每一層都需要修改
- 不過我個人覺得比起東西都塞在一起然後動輒上千行還改東壞西的，我是很能接受這些成本啦囧

本節的參考資料

由於接下來我們就要進入實作了，因此在這邊先放上分層架構概念的參考資料，提供給想更了解三層式架構觀念的朋友們。

實作

實作範例的架構與前言

在這次的範例中，我會採用在公司時的切割標準：各層之間不同方向的通訊都有獨立的 DTO 來負責。

當然每一層和每個 DTO 的名稱都是很彈性的，例如 Ray 大大的範例中，Service 和 Repository 的 DTO 部份就是使用 Dto 和 Entity 來命名。

故這部份還請各位根據專案慣例作調整，我個人還是習慣用這套命名方式來處理。本範例的架構大致上會長這樣：

此外，實作部份主要的參考來源為：

mrkt 的程式學習筆記: ASP.NET MVC 專案分層架構系列
軟體分層設計模式 (Software Layered Architecture Pattern) | Ray’s Notes
公司的新訓文件以及同事 Sian 的整理

對想了解分層架構的朋友們，可以也看過 mrkt 大大的操作流程，整體的敘述比較深入。

但要特別注意，由於我個人平時工作上比較常收到動輒好幾項查詢條件要包裝成單一支 API 的 Parameter DTO 這類需求，故已較為習慣建出一卡車的 DTO 這種方式。

而像 mrkt 大大的系列文是示範將已有的程式拆分為分層架構的模式、Ray 大大的範例程式的 DTO 命名和這篇的範例不同等等，因為環境、條件和習慣的差別，各家的分層方式和命名都會不太一樣，主要還是看團隊的慣例啦。

~~而且畢竟都要寫了，當然要用我習慣的流程來記錄嘛。作者特權！~~

因此本篇的範例，或是說每一篇說明分層的範例在操作的流程、DTO 的建立和使用上都會有所不同。還請有交叉閱讀的朋友們稍加留意。

不過就像上面引用的 mrkt 大大說的：「『專案分層架構』這個題目相當難以說明，因為要分幾層、怎麼分層、各層有什麼職責、要做什麼事？這些都可以再細分成很多個主題來說明」

所以希望各位不要拘泥於流程上的順序或是命名之類的，而是理解到這些都會依照實務上的狀況去做決策和調整。最後再重申一次：分層架構是一種分工的概念，所謂「兵無常勢，水無常形」請各位施主見機行事。善哉善哉。

那麼我們就準備開始囉！

大致上的步驟

感謝和同事 Sian 的談話才整理這套步驟，基本上我習慣的流程如下：

建立 Service 層
建立 Repository 層
建立 Controller 及 DTO (Parameter、ViewModel)
建立 Service 的介面及 DTO (Info、ResultModel)
建立 Repository 的介面及 DTO (Condition、DataModel)
將 Service 注入到 Controller, 將 Repository 注入到 Service
安裝 AutoMapper，後續使用 AutoMapper 處理來處理 DTO 的轉換
Controller 實作，並接上 Service 的介面
Service 實作，並接上 Repository 的介面
Repository 實作
進行整合測試，呼叫 Controller 試試看是否成功取得資料
自由發揮

可以注意到其實就是：

切出分層
開介面和用到的 DTO
用實作銜接各層
測試

這樣子的流程。

但這邊要說明幾點：

第 3 項的 Controller 我們會沿用本系列的專案，等等會稍作說明
第 6 項的注入我們會在下一個章節再進行介紹。這邊就先直接使用 new 的方式處理
同上，由於尚未使用注入，故 8 ~ 10 的實作部分會改從 Repository 開始實作

以上部分就…等等實作就會瞭了。那讓我們先介紹一下目前的專案狀況吧！

範例專案背景

接著回到專案的介紹，如果並不是很在乎專案狀況，而是想看實作過程的朋友，請跳到建立分層繼續閱讀。

我們會使用這個系列的 ProjectN 專案繼續操作。該專案在先前的 Api 和 Dapper 章節中，已經建立了一個對卡牌資料表進行 CRUD 的 CardController。詳細部份就不附了（畢竟這篇都會打掉嘛）大致上長這樣：

[ApiController]
[Route("[controller]")]
public class CardController : ControllerBase
{
    /// <summary>
    /// 查詢卡片列表
    /// </summary>
    [HttpGet]
    [Produces("application/json")]
    public IEnumerable<CardViewModel> GetList()
    {
        // 查詢卡片的一些操作
    }

    /// <summary>
    /// 查詢卡片
    /// </summary>     
    [HttpGet]
    [Produces("application/json")]
    [ProducesResponseType(typeof(CardViewModel), 200)]
    [Route("{id}")]
    public CardViewModel Get(
        [FromRoute] int id)
    {
        // 查詢指定 ID 的卡片的一些操作
    }

    /// <summary>
    /// 新增卡片
    /// </summary>
    /// <param name="parameter">卡片參數</param>
    /// <returns></returns>
    [HttpPost]
    public IActionResult Insert(
        [FromBody] CardParameter parameter)
    {
        // 新增卡片的一些操作
    }

    /// <summary>
    /// 更新卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <param name="parameter">卡片參數</param>
    /// <returns></returns>
    [HttpPut]
    [Route("{id}")]
    public IActionResult Update(
        [FromRoute] int id,
        [FromBody] CardParameter parameter)
    {
        // 更新卡片的一些操作
    }

    /// <summary>
    /// 刪除卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <returns></returns>
    [HttpDelete]
    [Route("{id}")]
    public IActionResult Delete(
        [FromRoute] int id)
    {
        // 刪除卡片的一些操作
    }
}

其中用來回傳顯示卡片內容的 Card 類別為了和分層的 DTO 命名一致，已經改為 CardViewModel：

/// <summary>
/// 卡片
/// </summary>
public class CardViewModel
{
    /// <summary>
    /// 卡片編號
    /// </summary>
    public int Id { get; set; }

    /// <summary>
    /// 卡片名稱
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// 卡片描述
    /// </summary>
    public string Description { get; set; }

    /// <summary>
    /// 攻擊力
    /// </summary>
    public int Attack { get; set; }

    /// <summary>
    /// 血量
    /// </summary>
    public int Health { get; set; }

    /// <summary>
    /// 花費
    /// </summary>
    public int Cost { get; set; }
}

以及當新增及修改卡片時使用的 CardParameter

/// <summary>
/// 卡片參數
/// </summary>
public class CardParameter
{
    /// <summary>
    /// 卡片名稱
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// 卡片描述
    /// </summary>
    public string Description { get; set; }

    /// <summary>
    /// 攻擊力
    /// </summary>
    public int Attack { get; set; }

    /// <summary>
    /// 血量
    /// </summary>
    public int Health { get; set; }

    /// <summary>
    /// 花費
    /// </summary>
    public int Cost { get; set; }
}

如果像本節開頭提到的，並沒有切分查詢和傳入的 DTO 時，這兩個就有可能使用同一個 Model，遇到這種狀況還請不要太驚慌了。

不過既然已經提到說不採用共用 Model 而是全部獨立的原因是「常會有多條件的查詢參數」之類的，這邊就補一下查詢列表用的參數吧。

如此如此，在 Parameter 資料夾下新增了一個 CardSearchParameter：

/// <summary>
/// 卡片搜尋參數
/// </summary>
public class CardSearchParameter
{
    /// <summary>
    /// 卡片名稱
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// 攻擊力下限
    /// </summary>
    public int? MinAttack { get; set; }

    /// <summary>
    /// 攻擊力上限
    /// </summary>
    public int? MaxAttack { get; set; }

    /// <summary>
    /// 血量下限
    /// </summary>
    public int? MinHealth { get; set; }

    /// <summary>
    /// 血量上限
    /// </summary>
    public int? MaxHealth { get; set; }

    /// <summary>
    /// 花費值下限
    /// </summary>
    public int? MinCost { get; set; }

    /// <summary>
    /// 花費值上限
    /// </summary>
    public int? MaxCost { get; set; }
}

請注意因為參數是選填的，所以部分欄位使用的是 Nullable。畢竟在卡牌遊戲中，想查詢「攻擊力３以下的卡片」是很平常的需求嘛。

接著這個參數就放回到 CardController 的 GetList() 裡面作為參數吧：

/// <summary>
/// 查詢卡片列表
/// </summary>
/// <returns></returns>
[HttpGet]
[Produces("application/json")]
public IEnumerable<CardViewModel> GetList(
    [FromQuery] CardSearchParameter parameter)
{
        // 查詢卡片的一些操作
}

畢竟是 GET 方法，標示一下 FromQuery 才是好習慣呦。

到這邊就說明完目前的專案狀況了，讓我們捲起袖子，開始切分層吧！

建立分層

接著讓我們先來建立分層吧，這邊採用建立「類別庫」的方式來分層，對於一些比較小的專案，使用資料夾來分層也是沒有問題的。

首先，讓我們在方案總管對著方案按下右鍵，選擇加入 → 新增專案

接著找到類別庫，由於範例專案是使用 .net Core 3.1 的版本，故選擇 .net Core 為目標的類別庫：

接著讓我們用專案名稱 + Service 來命名這個專案：

下個畫面選擇完版本之後，就可以在解決方案看到多了一個 Service 的專案囉：

然後那個 Class1.cs 可以砍掉，我們不會用到。

接著請重複以上的步驟，建立 Repository 和 Common 的類別庫：

補充：如果想要把專案做排序或整理的朋友，可以對解決方案右鍵，選擇加入 → 新增方案資料夾，用資料夾去做排序和整理

~~有的時候我都懷疑其他人的分層用 Business 和 Data 命名，該不會是為了排序起來比較好看……？！~~

加入參考

建立完類別庫之後，接著我們就要來加入參考，也就是設定這些庫之間的依賴方向。

一般的分層架構的依賴關係會是從上到下，也就是展示層 → 商業邏輯層 → 資料存取層，然後他們三個都參考共用層。

現在讓我們從最外圍開始：對 ProjectN （或是你 WEB／API 等等所在的專案）右鍵 → 加入 → 專案參考

然後讓它參考我們的 Service 層以及共用的 Common：

同樣地，也請各位對 Service 和 Repository 進行同樣的操作加入參考。各層的參考關係現在應該要是這樣的：

API or APP: Service + Common
Service: Repository + Common
Repository: Common

小提示：如果想確認目前專案的相依性，可以在方案總管的解決方案上按下右鍵 → 專案相依性

建立介面與 DTO

在這個小節，你可能會需要對介面有些了解。還不太了解的朋友，可以參照上個系列的介面篇。

對於分層是否要使用介面有疑惑的朋友，可以參考 mrkt 大大的這篇專案分層架構建議中的「問題三、一定要用介面嗎？」的段落。

接著，讓我們開始著手處理介面的部分吧，先讓我們在 Service 中新增一個叫做 Interface 的資料夾來放我們的介面。

接著因為是做卡片管理的 CRUD，當然要用 Card 當前綴。並且由於習慣的關係，只要是 Interface 我會在最前面加上一個 I 來標示，所以讓我們在該資料夾下建立一個 ICardService：

如此一來就會建立一個空的介面。啊，記得加上 Public 呦。

/// <summary>
/// 卡片管理服務
/// </summary>
public interface ICardService
{

}

接著讓我們補上 CRUD 的五個方法，如果是去 Controller 複製的朋友要注意這邊的 DTO 已經不同囉：

/// <summary>
/// 卡片管理服務
/// </summary>
public interface ICardService
{
    /// <summary>
    /// 查詢卡片列表
    /// </summary>
    /// <returns></returns>
    IEnumerable<CardResultModel> GetList(CardSearchInfo info);

    /// <summary>
    /// 查詢卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <returns></returns>   
    CardResultModel Get(int id);

    /// <summary>
    /// 新增卡片
    /// </summary>
    /// <param name="parameter">卡片參數</param>
    /// <returns></returns>
    bool Insert(CardInfo info);

    /// <summary>
    /// 更新卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <param name="parameter">卡片參數</param>
    /// <returns></returns>
    bool Update(int id, CardInfo info);

    /// <summary>
    /// 刪除卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <returns></returns>
    bool Delete(int id);
}

因為我們還沒建立對應的 DTO，所以會有紅字也是正常的。我個人平常都是邊捏介面邊開 DTO 就是了。

畢竟介面就是各層之間溝通的契約，傳遞的 DTO 當然也就是契約內容了。所以在決定這功能要幹嘛的時候就會順便捏起來。

綜上所述，接著就讓我們來把 DTO 補上吧，因為我們只有 Card 一條線，所以這裡的 DTO 就會是對應展示層的那三個 DTO，反過來說也就是說，如果你的架構裡會有多個 Service 互相協作，或是 Service 需要從多個 Repository 取得資料的話，諸如此類需要多個部份互相配合的時侯，DTO 就不一定會是和上一層對照起來的了。這一點還請注意。

畢竟這個範例只有單線，已經是最最最簡單的狀況了，還是有蠻多亂七八糟的地方是難以表達的…屆時再請各位切身體會了。

所以請容我再貼一次九成像的 DTO 吧 XD。此外，因為都九成像了，呈現的時候就先不加上欄位註解囉。

關於存放的位置，我個人習慣會再開一個 Models 或是 Dtos 的資料夾來放這些 DTO，如果功能比較多的就再多一層做個分類。本範例的 DTO 路徑如註解。

// ProjectN.Service.Dtos.ResultModel
public class CardResultModel
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
    public int Attack { get; set; }
    public int Health { get; set; }
    public int Cost { get; set; }
}


// ProjectN.Service.Dtos.Info
public class CardInfo
{
    public string Name { get; set; }
    public string Description { get; set; }
    public int Attack { get; set; }
    public int Health { get; set; }
    public int Cost { get; set; }
}


// ProjectN.Service.Dtos.Info
public class CardSearchInfo
{
    public string Name { get; set; }
    public int? MinAttack { get; set; }
    public int? MaxAttack { get; set; }
    public int? MinHealth { get; set; }
    public int? MaxHealth { get; set; }
    public int? MinCost { get; set; }
    public int? MaxCost { get; set; }
}

不要忘了要回到 Interface 的地方好好 using 進來呦：

現在我們的 Service 層應該會是這個樣子的：

接著就讓我們用同樣的節奏來處理 Repository 吧。

首先仍然是先建立一個 Interface 資料夾、建立一個 ICardRepository，並加上我們的 CRUD 五天王：

/// <summary>
/// 卡片管理服務
/// </summary>
public interface ICardRepository
{
    /// <summary>
    /// 查詢卡片列表
    /// </summary>
    /// <returns></returns>
    IEnumerable<CardDataModel> GetList(CardSearchCondition info);

    /// <summary>
    /// 查詢卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <returns></returns>   
    CardDataModel Get(int id);

    /// <summary>
    /// 新增卡片
    /// </summary>
    /// <param name="parameter">卡片參數</param>
    /// <returns></returns>
    bool Insert(CardCondition info);

    /// <summary>
    /// 更新卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <param name="parameter">卡片參數</param>
    /// <returns></returns>
    bool Update(int id, CardCondition info);

    /// <summary>
    /// 刪除卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <returns></returns>
    bool Delete(int id);
}

接著是我們的 DTO 們：

// ProjectN.Repository.Dtos.DataModel
public class CardDataModel
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Description { get; set; }
    public int Attack { get; set; }
    public int Health { get; set; }
    public int Cost { get; set; }
}


// ProjectN.Repository.Dtos.Condition
public class CardCondition
{
    public string Name { get; set; }
    public string Description { get; set; }
    public int Attack { get; set; }
    public int Health { get; set; }
    public int Cost { get; set; }
}


// ProjectN.Repository.Dtos.Condition
public class CardSearchCondition
{
    public string Name { get; set; }
    public int? MinAttack { get; set; }
    public int? MaxAttack { get; set; }
    public int? MinHealth { get; set; }
    public int? MaxHealth { get; set; }
    public int? MinCost { get; set; }
    public int? MaxCost { get; set; }
}

這邊特別提一下 CardSearchCondition 好了。

我個人是喜歡先在 Repository 中把一些簡單、跟資料有關的欄位先用 Condition 允許第一次篩選，如果有複雜的、需要別的條件的就再 Service 進行篩選。如此一來如果有別的 Service 需要用差不多的條件查詢該資料的時候，就可以用組合這些參數的方式來重複使用這個 Repository。

也就是說和 Service 時提到的時候一樣：如果有需要多個資料來源合併處理時，每層的 DTO 就會有所不同。

這個時候的 Repository 參數應該注重在「針對這個資料，有哪些基本的過濾條件？」下去設計，維持這個篩選的條件是和這個資料來源有關的，這樣才真的能夠重複利用。

千萬不要為了需求需要多個資料來源，就打破單一職責原則，把所有參數都丟到 Repository 然後才想辦法把資料表之類的兜在一起去滿足需求，這樣就難以複用、本末倒置了。

如果這樣說可能有點難以理解的話，想像一個「查詢重要訂單」功能的參數同時有「該訂單的交易金額大於五十萬」和「該訂單客戶年收入大於五十萬」這兩個查詢條件，很明顯一個是從訂單本身的資料內容下去篩選、而另一個是從客戶的資料內容下去篩選。

這種時候就應該是分別去呼叫訂單的 Repo 和客戶的 Repo 來拿到相對應的資料，例如說有客戶年收入的條件時，先取出年收入符合的客戶，再用這些客戶的編號取得對應的訂單等等（具體順序看資料大小），那麼這種場合兩者的參數 DTO 就會自然地和 Service 的 DTO 不一樣了。

請盡量不要為了一路打到底就硬把這兩個條件綑綁在一起，弄成什麼「以交易金額與客戶年收入查詢訂單」的「專用」方法，這樣將來就很難重複使用了。

（不過凡事都有例外嘛，當你的效能爆炸到被要求只能在 SQL 就先做完篩選的時候，或是只能從舊有功能移植過來的時候，還是要乖乖想辦法就是了囧…）

聊得遠了，讓我們回到 ProjectN 的 Repository，目前應該會是長這個樣子：

到這邊我們的介面和功能都訂好啦，接著就讓我們開始實作這些介面吧！

實作 Repository

註：本篇範例還不會用到依賴注入，因此會將需要用到的依賴對象，例如 Controller 中的 IService 實體直接在建構式裡面建立出來。也因為必須建立實體的關係，故必須從最底的 Repository 開始實作。

如果是已經有在使用依賴注入的朋友，還請自行在腦內調整一下。不過我個人是覺得實作的順序沒有什麼關係啦，各位朋友有習慣的就按自己習慣的就好溜。

而還不太知道依賴注入的朋友們，我們下一篇再來說明。或是也可以先參照依賴反轉原則的範例自己改看看，此處就先按下不表。

首先讓我們從 Repository 開始實作吧！

第一步就是建立實作的資料夾，方便和 Interface 做個區隔，所以這邊在 Repository 建立一個 Implement 資料夾，並在裡面建立 CardRepository ：

建立之後，別忘記把類別改為 Public 並告訴他我們要實作介面 ICardRepository（記得 using）：

public class CardRepository : ICardRepository
{

}

接著 IDE 通常都會提醒一下說你有哪些要求沒有做到，這邊就讓我偷懶一下直接讓 IDE 產生空方法：

public class CardRepository : ICardRepository
{
    public IEnumerable<CardDataModel> GetList(CardSearchCondition info)
    {
        throw new NotImplementedException();
    }

    public CardDataModel Get(int id)
    {
        throw new NotImplementedException();
    }
    
    public bool Insert(CardCondition info)
    {
        throw new NotImplementedException();
    }

    public bool Update(int id, CardCondition info)
    {
        throw new NotImplementedException();
    }
    
    public bool Delete(int id)
    {
        throw new NotImplementedException();
    }
}

各位朋友在切出資料存取層的實作時，如果是從舊專案移植過來的，也可以從「把操作資料表的部份都先剪過來」來起手。

從資料庫裏面操作資料的 CRUD 相關部份我們在上一篇的 Dapper 章節已經做得差不多了，這邊就不再贅述，稍微補上這次新增的查詢列表就行。

補充：為了避免我之後回來抄的時候想不起來，這邊也放一下資料表目前狀況好了：

/// <summary>
/// 卡片管理
/// </summary>
/// <seealso cref="ProjectN.Repository.Interface.ICardRepository" />
public class CardRepository : ICardRepository
{
    /// <summary>
    /// 連線字串
    /// </summary>
    private readonly string _connectString = @"Server=(LocalDB)\MSSQLLocalDB;Database=Newbie;Trusted_Connection=True;";

    /// <summary>
    /// 查詢卡片列表
    /// </summary>
    /// <param name="info"></param>
    /// <returns></returns>
    public IEnumerable<CardDataModel> GetList(CardSearchCondition condition)
    {
        var sql = "SELECT * FROM Card";

        var sqlQuery = new List<string>();
        var parameter = new DynamicParameters();

        if (condition.MinCost.HasValue)
        {
            sqlQuery.Add($" Cost >= @MinCost ");
            parameter.Add("MinCost", condition.MinCost);
        }

        if (condition.MaxCost.HasValue)
        {
            sqlQuery.Add($" Cost <= @MaxCost ");
            parameter.Add("MaxCost", condition.MaxCost);
        }

        if (condition.MinAttack.HasValue)
        {
            sqlQuery.Add($" Attack >= @MinAttack ");
            parameter.Add("MinAttack", condition.MinAttack);
        }

        if (condition.MaxAttack.HasValue)
        {
            sqlQuery.Add($" Attack <= @MaxAttack ");
            parameter.Add("MaxAttack", condition.MaxAttack);
        }

        if (condition.MinHealth.HasValue)
        {
            sqlQuery.Add($" Health >= @MinHealth ");
            parameter.Add("MinHealth", condition.MinHealth);
        }

        if (condition.MaxHealth.HasValue)
        {
            sqlQuery.Add($" Health <= @MaxHealth ");
            parameter.Add("MaxHealth", condition.MaxHealth);
        }

        if (string.IsNullOrWhiteSpace(condition.Name) is false)
        {
            sqlQuery.Add($" Name LIKE @Name ");
            parameter.Add("Name", $"%{condition.Name}%");
        }
        
        if (sqlQuery.Any())
        {
            sql += $" WHERE {string.Join(" AND ", sqlQuery)} ";
        }

        using (var conn = new SqlConnection(_connectString))
        {
            var result = conn.Query<CardDataModel>(sql, parameter);
            return result;
        }
    }
	
    /// <summary>
    /// 查詢卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <returns></returns>
    public CardDataModel Get(int id)
    {
        var sql =
            @"		
                SELECT * 
                FROM Card 
                Where Id = @id
            ";

        var parameters = new DynamicParameters();
        parameters.Add("Id", id, System.Data.DbType.Int32);

        using (var conn = new SqlConnection(_connectString))
        {
            var result = conn.QueryFirstOrDefault<CardDataModel>(sql, parameters);
            return result;
        }
    }


    public bool Insert(CardCondition condition)
    {
        var sql =
            @"
                INSERT INTO Card 
                (
                   [Name]
                  ,[Description]
                  ,[Attack]
                  ,[Health]
                  ,[Cost]
                ) 
                VALUES 
                (
                    @Name
                   ,@Description
                   ,@Attack
                   ,@Health
                   ,@Cost
                );

                SELECT @@IDENTITY;
            ";

        using (var conn = new SqlConnection(_connectString))
        {
            var result = conn.Execute(sql, condition);
            return result > 0;
        }
    }

    /// <summary>
    /// 更新卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <param name="condition"></param>
    /// <returns></returns>
    public bool Update(int id, CardCondition condition)
    {
        var sql =
            @"
                UPDATE Card
                SET 
                    [Name] = @Name
                   ,[Description] = @Description
                   ,[Attack] = @Attack
                   ,[Health] = @Health
                   ,[Cost] = @Cost
                WHERE
                    Id = @id
            ";

        var parameters = new DynamicParameters();

        parameters.AddDynamicParams(condition);
        parameters.Add("Id", id, System.Data.DbType.Int32);

        using (var conn = new SqlConnection(_connectString))
        {
            var result = conn.Execute(sql, parameters);
            return result > 0;
        }
    }

    /// <summary>
    /// 刪除卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <returns></returns>
    public bool Delete(int id)
    {
        var sql =
            @"
                DELETE FROM Card
                WHERE Id = @Id
            ";

        var parameters = new DynamicParameters();
        parameters.Add("Id", id, System.Data.DbType.Int32);

        using (var conn = new SqlConnection(_connectString))
        {
            var result = conn.Execute(sql, parameters);
            return result > 0;
        }
    }
}

實作 Service

接著是我們 Service 層的實作。要注意的是，在 DTO 的轉換上，推薦使用 AutoMapper 來處理，讓方法關注在商業邏輯本身，而不用被 DTO 的賦值過程洗版。

補充：對 AutoMapper 不太熟悉的朋友，可以先閱讀 AutoMapper —— 類別轉換超省力

如果是在本篇流程不打算使用 AutoMapper 的朋友，請在使用到 AutoMapper 的場合自行 new 出目標物件並賦值即可。

首先一樣先建立實作用的資料夾，並建立 CardService：

並且讓 IDE 幫忙把要實作的介面都先列出來：

public class CardService : ICardService
{
    public IEnumerable<CardResultModel> GetList(CardSearchInfo info)
    {
        throw new NotImplementedException();
    }

    public CardResultModel Get(int id)
    {
        throw new NotImplementedException();
    }

    public bool Insert(CardInfo info)
    {
        throw new NotImplementedException();
    }

    public bool Update(int id, CardInfo info)
    {
        throw new NotImplementedException();
    }
    
    public bool Delete(int id)
    {
        throw new NotImplementedException();
    }
}

那因為這個範例還沒有什麼需要注意的商業邏輯，因此我們就先在 Service 做一個承上（Controller）啟下（Repository）的動作。

也就是說每個方法負責去接收 Controller 的請求，並呼叫 Repository 來完成工作，並用 AutoMapper 來進行過程的轉換。

因此我們的 Service 要能夠呼叫到 Repository 和 Mapper，現在先讓我們把 Repository 當作私有成員建立進來：

public class CardService : ICardService
{
    private readonly ICardRepository _cardRepository;

    /// <summary>
    /// 建構式
    /// </summary>
    public CardService()
    {
        this._cardRepository = new CardRepository();
    }

    // 其他實作部分
}

接著是 DTO 的對映部分，先建立 Service 的對映表。我個人習慣跟隨公司慣例開一個 Mappings 資料夾來放：

補充：當專案還有 Mappings, Enum（列舉）和其他設定檔等等，資料夾就會變得挺多的。

這種時候，也可以把這類基礎建設相關的都放到 Infrastructure 資料夾做個整理，閱讀和操作上會比較舒服。

public class ServiceMappings : Profile
{
    public ServiceMappings()
    {
        // Info -> Condition
        this.CreateMap<CardInfo, CardCondition>();
        this.CreateMap<CardSearchInfo, CardSearchCondition>();

        // DataModel -> ResultModel
        this.CreateMap<CardDataModel, CardResultModel>();
    }
}

接著讓我們也把 AutoMapper 的部份放到建構式裡面吧：

public class CardService : ICardService
{
    private readonly IMapper _mapper;
    private readonly ICardRepository _cardRepository;

    /// <summary>
    /// 建構式
    /// </summary>
    public CardService()
    {
        var config = new MapperConfiguration(cfg =>
			cfg.AddProfile<ServiceMappings>());

        this._mapper = config.CreateMapper();
        this._cardRepository = new CardRepository();
    }
    
    // 其他實作部分
}

接著就化身為無情的串接機器，把各個實作接起來。

例如說查詢列表 GetList，標準流程就是轉換參數 DTO、呼叫目標方法、轉換回傳 DTO：

/// <summary>
/// 查詢卡片列表
/// </summary>
/// <param name="info"></param>
/// <returns></returns>
public IEnumerable<CardResultModel> GetList(CardSearchInfo info)
{
    var condition = this._mapper.Map<CardSearchInfo, CardSearchCondition>(info);
    var data = this._cardRepository.GetList(condition);

    var result = this._mapper.Map<
        IEnumerable<CardDataModel>, 
    	IEnumerable<CardResultModel>>(data);

    return result;
}

當然實際上還會根據需求，在這邊做一些商業邏輯的處理，例如說呼叫多個 Repository 方法、參數內容換成內部商業邏輯定義好的代號等等。

叮嚀一下：如果感覺公開方法裡面做的事情太多的話，還請考慮是不是職責太複雜、並嘗試適當地拆出私有方法或其他類別呦。

那麼這邊就直接補上剩下的方法，貼上整個 CardService 吧：

/// <summary>
/// 卡片管理
/// </summary>
/// <seealso cref="ProjectN.Service.Interface.ICardService" />
public class CardService : ICardService
{
    private readonly IMapper _mapper;
    private readonly ICardRepository _cardRepository;

    /// <summary>
    /// 建構式
    /// </summary>
    public CardService()
    {
        this._cardRepository = new CardRepository();

        var config = new MapperConfiguration(cfg => 
			cfg.AddProfile<ServiceMappings>());

        this._mapper = config.CreateMapper();
    }

    /// <summary>
    /// 查詢卡片列表
    /// </summary>
    /// <param name="info"></param>
    /// <returns></returns>
    public IEnumerable<CardResultModel> GetList(CardSearchInfo info)
    {
        var condition = this._mapper.Map<CardSearchInfo, CardSearchCondition>(info);
        var cards = this._cardRepository.GetList(condition);

        var result = this._mapper.Map<
            IEnumerable<CardDataModel>, 
        	IEnumerable<CardResultModel>>(cards);

        return result;
    }

    /// <summary>
    /// 查詢卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <returns></returns>
    public CardResultModel Get(int id)
    {
        var card = this._cardRepository.Get(id);
        var result = this._mapper.Map<CardDataModel, CardResultModel>(card);
        return result;
    }

    /// <summary>
    /// 新增卡片
    /// </summary>
    /// <param name="info"></param>
    /// <returns></returns>
    public bool Insert(CardInfo info)
    {
        var condition = this._mapper.Map<CardInfo, CardCondition>(info);
        var result = this._cardRepository.Insert(condition);
        return result;
    }

    /// <summary>
    /// 更新卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <param name="info"></param>
    /// <returns></returns>
    public bool Update(int id, CardInfo info)
    {
        var condition = this._mapper.Map<CardInfo, CardCondition>(info);
        var result = this._cardRepository.Update(id, condition);
        return result;
    }

    /// <summary>
    /// 刪除卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <returns></returns>
    public bool Delete(int id)
    {
        var result = this._cardRepository.Delete(id);
        return result;
    }
}

實作 Controller

最後就是讓我們的 Controller 來接上 Service 的介面，把方法公開出去啦！

同樣的也先放一下 Mappings：

public class ControllerMappings : Profile
{
    public ControllerMappings()
    {
        // Parameter -> Info
        this.CreateMap<CardParameter, CardInfo>();
        this.CreateMap<CardSearchParameter, CardSearchInfo>();

        // ResultModel -> ViewModel
        this.CreateMap<CardResultModel, CardViewModel>();
    }
}

最後一樣把 Controller 的各方法補上：

/// <summary>
/// 卡片管理
/// </summary>
/// <seealso cref="Microsoft.AspNetCore.Mvc.ControllerBase" />
[ApiController]
[Route("[controller]")]
public class CardController : ControllerBase
{
    private readonly IMapper _mapper;
    private readonly ICardService _cardService;

    /// <summary>
    /// 建構式
    /// </summary>
    public CardController()
    {
        var config = new MapperConfiguration(cfg =>
        	cfg.AddProfile<ControllerMappings>());

        this._mapper = config.CreateMapper();
        this._cardService = new CardService();
    }

    /// <summary>
    /// 查詢卡片列表
    /// </summary>
    /// <returns></returns>
    [HttpGet]
    [Produces("application/json")]
    public IEnumerable<CardViewModel> GetList(
        [FromQuery] CardSearchParameter parameter)
    {
        var info = this._mapper.Map<
            CardSearchParameter, 
        	CardSearchInfo>(parameter);

        var cards = this._cardService.GetList(info);

        var result = this._mapper.Map<
            IEnumerable<CardResultModel>,
        	IEnumerable<CardViewModel>>(cards);

        return result;
    }

    /// <summary>
    /// 查詢卡片
    /// </summary>
    /// <remarks>我是附加說明</remarks>
    /// <param name="id">卡片編號</param>
    /// <returns></returns>
    /// <response code="200">回傳對應的卡片</response>
    /// <response code="404">找不到該編號的卡片</response>          
    [HttpGet]
    [Produces("application/json")]
    [ProducesResponseType(typeof(CardViewModel), 200)]
    [Route("{id}")]
    public CardViewModel Get(
        [FromRoute] int id)
    {
        var card = this._cardService.Get(id);

        var result = this._mapper.Map<
            CardResultModel,
        	CardViewModel>(card);

        return result;
    }

    /// <summary>
    /// 新增卡片
    /// </summary>
    /// <param name="parameter">卡片參數</param>
    /// <returns></returns>
    [HttpPost]
    public IActionResult Insert(
        [FromBody] CardParameter parameter)
    {
        var info = this._mapper.Map<
            CardParameter,
        	CardInfo>(parameter);

        var isInsertSuccess = this._cardService.Insert(info);
        if (isInsertSuccess)
        {
            return Ok();
        }
        return StatusCode(500);
    }

    /// <summary>
    /// 更新卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <param name="parameter">卡片參數</param>
    /// <returns></returns>
    [HttpPut]
    [Route("{id}")]
    public IActionResult Update(
        [FromRoute] int id,
        [FromBody] CardParameter parameter)
    {
        var targetCard = this._cardService.Get(id);
        if (targetCard is null)
        {
            return NotFound();
        }

        var info = this._mapper.Map<
            CardParameter,
        	CardInfo>(parameter);

        var isUpdateSuccess = this._cardService.Update(id, info);
        if (isUpdateSuccess)
        {
            return Ok();
        }
        return StatusCode(500);
    }

    /// <summary>
    /// 刪除卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <returns></returns>
    [HttpDelete]
    [Route("{id}")]
    public IActionResult Delete(
        [FromRoute] int id)
    {
        this._cardService.Delete(id);
        return Ok();
    }
}

測試一下有沒有接上去

打完收工！

自問自答心得篇

實作結束之後，這邊就留個版面放一些上面沒提到／塞不進去／老人碎碎念的部份。

感謝 Sian 提供的建議和示範，這邊補上一些關於我個人分層上遇到的一些問題和想法，整理成Ｑ＆Ａ的方式。

關於重複建立 DTO 的問題

Q: 資料處理給商業邏輯要開一個 DataModel，商業邏輯出去又要開一個 ResultModel……每次都要開一堆重複的 DTO 很麻煩！一定要這樣做嗎？

A: 不一定。

我這邊也遇過一些系統，由於場景相對單純，存取上基本只有增修查改，商業邏輯也多是驗證和內容資料的處理，因此就採用一個 Dto 貫穿三層的方式進行。例如說跟訂單有關的就只使用一個 OrderDto、跟產品有關的就只用一個 ProductDto 這樣，整體用起來會比較像是一個實體對應一個 Dto 的感覺。

我個人認為「要不要把各層之間溝通用的 DTO 都獨立出來」，基本上就是在問這個系統：

會不會有「你對資料表比較熟悉，負責資料存取層；我對外制定規格，負責展示層」等等，這種需要針對分層去分工的時候？
每一層之間傳遞的 Model 是否會在各層進一步加工，每一層需要傳遞的資料會不會有所不同？
每一層之間呼叫方法的參數是否會不同，有沒有需要把參數封裝成一個物件？

例如說：

資料存取層將資料表的資料查詢出來，但該功能展示給使用者的時候並不需要這麼多欄位
商業邏輯層需要針對這個內容去和別的資料進行組裝、運算
- 例如說需求不只是單純的客戶查詢，而是客戶平均消費排行榜之類的
展示層需要進行一些給使用者介面顯示時的調整
- 浮點數顯示的時候只到小數後兩位之類的

像這種分工明確的情況下，就很容易會遇到每一層之間傳遞的 Dto 內容必須不同的情況。

以上的狀況如果都共用同一個 DTO 反而綁手綁腳的，把各層之間盡責地拆分開來，更可以降低彼此間的耦合，讓修改的範圍變小、並盡量只在符合該職責的地方修改，整體會比較靈活。

回到問題上來說，要不要確實地把每一層的 DTO 做拆分？或是想採用一個 DTO 代表該資料來貫穿整個系統？我個人覺得都還是蠻彈性的，可以根據系統的複雜度去嘗試。

如果你可能會根據分層去指派分工，又或者是有些地方會頻繁地修改、每一層之間傳遞的資訊常常會有所差異，甚至是收到的需求常常挺客製化的時候，拆分開來在往後的修改就可能可以迴避一些耦合上的問題。但相對的，因為 Model 終究還是變多了，有時候也會遇到重複且多餘的修改。

反過來說如果系統的工作單一，場景相對單純，例如說是針對某個職責去架設的、提供給其他系統使用的小型服務。那麼先採用 DTO 對映資料內容並共用的做法，在開發上反而比較迅速。

就再請各位使用時細細品味吧。~~我都是前輩怎麼開我就怎麼寫啦~~

三層式架構跟 MVC 一樣嗎？

這個吼，不太一樣啦（抓頭）

雖然兩者的目標都算是「區分職責＋解除耦合」的感覺，但並不是一樣的東西。

MVC 是一種框架，主要分為 View, Controller, Model，特別強調此三者並不能直接類比到三層式架構的三層。我們從兩邊的角度來比對一下：

以 MVC 的角度出發，對應三層式中的商業邏輯和資料存取都是塞到 Model 中處理的（當然也會遇到全部塞在 Controller 的朋友囧），這時候最大的差別就是有沒有區分出商業邏輯。畢竟三層式就是為了要能重複使用而分層的嘛。

反過來從三層式架構的角度出發的話，MVC 也只是用在展示層的一種模式而已。例如說展示層使用 MVC 的架構，往下接到商業邏輯等等。實際上使用分層的話，最終不管展示層是 MVC 框架、WebForm、Web Api 等等，對底下的商業邏輯層等等都不會有任何影響。

因此兩者是可以並存的不同層級下的不同拆分方式，並不能簡單地一概而論。

這個問題也可以參考以下文章，分享給大家：

Service 可以依賴 Service 嗎？

可以。~~既然人家都寫好了不用白不用~~

基本上來說在兩個 Service 之間就是一般物件和物件的關係，如果需要對方的公開方法，當然可以依賴對方。

不過為了避免循環參考，和同事經過了一些討論，還是有一些地方可以注意：

如果只是純粹的流程控制，可以把工作還給流程控制的 Controller，讓該功能的 Controller 依序呼叫 Service 處理
如果是多個商業邏輯的整合，可以用一個高階的 Service 去整合負責較小職責的 Service，避免循環參考或則是依賴關係混亂

另外在使用上也要注意呼叫對象是否有經過一些複雜的商業處理，如果那正是你要的，例如說你就是要訂單計算之後的結果，那當然沒有問題；倘若只是需要乾淨的資料，也可以乾脆往下去依賴 Repository 就可以，避免商業邏輯間意料之外的耦合。

所以請不要被從上到下這個方向束縛了，Service 也可以是厚厚的一層。

小結

本篇記錄了為什麼要分層，以及我個人平常開新專案的分層步驟。

最後針對分層架構，總結一下幾個筆記重點：

分層是為了分離關注點。讓每一層的職責明確、專注在各自的工作
分層帶來的好處：
- 修改時能更快鎖定目標、縮小範圍
- 適合多人合作，提升開發效率
- 增加程式碼的複用性
- 必要的時候可以抽換掉某一層
分層的前提：
- 物件的設計要遵守 SOLID 原則
- 使用依賴注入來解除層與層之間的依賴
- 額外的開發成本
常見的三層式架構：
- 展示層：負責和外部使用者互動
- 商業邏輯層：負責處理商業規則和相關的邏輯處理
- 資料存取層：負責存取資料的相關操作
- 共用層：負責擴充方法等不屬於任何一層的共用模組
資料傳輸物件（DTO）
- 層與層之間需要資料的傳遞，因此我們會建立只有欄位沒有方法的 DTO 來傳輸資料
- DTO 的轉換挺麻煩的，這時候就可以考慮使用 AutoMapper 這類工具
分層本身是分工的概念
- 要分成幾層、每一層負責什麼工作，這些都是需要決策的
- 綜上所述，請根據專案需求和團隊慣例作調整

大概這樣。

實作的部份也因為分層這個題目太廣了，其實有點不太知道要怎麼寫比較好，放置了一段時間。

最後決定就接續先前文章的進度，用平常習慣的方式調整一下來跑完一輪。當然內容還有許多地方是需要調整的：例如我們下一篇要加入的依賴注入，或是將方法改寫為非同步等等。

內文的範例也延續了單純的 CRUD，並沒有完整展現商業邏輯分工出來的魅力，算是一些小遺憾。最後補充一些本篇的參考資料。如果有想要補充或討論的朋友，也歡迎分享您的看法，感謝感謝。

那麼，我們下篇再見囉～

本系列下一篇：菜雞新訓記 (6): 使用依賴注入 (Dependency Injection) 來解除強耦合吧

參考資料

本系列文章

菜雞抓蟲: 使用 FromUri 的複雜型別在有傳遞 QueryString 的情況下會先建立再賦值

Igouist (Igouist) — Thu, 19 Aug 2021 22:20:00 +0800

事發緣由

在 .Net Framework 4.6.2 MVC 的 ApiController 中，某個查詢資料列表的方法除了提供查詢條件的參數以外，還有提供選擇性的分頁參數。也就是像這樣子：

[HttpGet]
public IEnumerable<Boo> GetBoos(
    [FromUri] SearchBooParameter parameter,
    [FromUri] PagingParameter paging = null)
{
    // 呼叫 Service 查資料...
}

由於需要調整該功能的預設排序，改為由大到小，又不想背負更改大量共用的 PagingParameter 去影響到其他使用到的地方，決定在 Controller 這裡簡單用預測值加上判斷處理一下就好

相信著「若使用者沒有傳遞 paging 相關的參數，應該就會是給定的預設值 null 吧！」的我，用了 if (paging is null) 進行判斷：若是 null 的情況就將其中用來標示排序方向的成員 isDesc 設定為 true，開開心心交差。

[HttpGet]
public IEnumerable<Boo> GetBoos(
    [FromUri] SearchBooParameter parameter,
    [FromUri] PagingParameter paging = null)
{
    if (paging is null)
    {
        paging = new PagingParameter();
        paging.isDesc = true; // 預設由大到小
    }
    // 呼叫 Service 查資料...
}

但實際使用之後發現：即使只有傳入查詢條件參數、未傳遞 paging 時，資料仍然由小到大顯示，且 paging.isDesc 竟然是 false，並未被更改到。也就是說，即使未傳遞 paging，它也並不是 null！

實測之後發現：若在呼叫該 API 的時候，給定一個完全無關的參數，例如 ?a=1，則 paging 還是會被建立一個實體出來，並無視 = null 這個預設值。因此就導致了非預期（＝跟我想的不一樣啊！）的行為。

這邊直接先講結論：如果有傳遞 QueryString 的任何參數時，不管這些參數跟指定的類別有沒有關係，放在 [FromUri] 的複雜型別都會先建立出實體，再嘗試和 QueryString 的內容進行比對與設值。

設定在 [FromUri] 的複雜型別身上的預設值，像是 [FromUri] PagingParameter paging = null 只有完全沒給任何 QueryString 的時候才會吃到。（不過因為預設值只能是常數的關係，基本上就是指 defualt 的 null）

因此如果遇到要給定預設值的場合，還是得乖乖地針對型別中的成員做設定比較保險，例如 bool isDesc { get; set; } = true。另外，因為完全沒給 QueryString 的時候還是會是 null，故該有的參數檢查仍然不能漏了。

測試案例

.Net Framework 4.7.2 Web Api - FromUri

[RoutePrefix("api")]
public class ValuesController : ApiController
{
    [HttpGet, Route("Test")]
    public string Test([FromUri] SimplyParameter parameter = null)
    {
        return parameter?.IsSuccess.ToString() ?? "It's NULL!"; // False
    }
    
    public class SimplyParameter
    {
        public bool IsSuccess { get; set; }
        public string Message { get; set; }
    }
}

/api/test => It’s NULL!

/api/test?a=2 => False

若改為必須參數，而不是選擇性參數呢：

[HttpGet, Route("Test")]
public string Test([FromUri] SimplyParameter parameter)
{
    return parameter?.IsSuccess.ToString() ?? "It's NULL!"; // False
}

/api/test => It’s NULL!

/api/test?a=2 => False

看起來最大的差異點在於有沒有給 QueryString。

現在讓我們對 Model 給定預設值，並加入建構式並觀察執行順序：

[RoutePrefix("api")]
public class ValuesController : ApiController
{
    [HttpGet, Route("Test")]
    public string Test([FromUri] SimplyParameter parameter = null)
    {
        return parameter?.IsSuccess.ToString() ?? "It's NULL!"; // False
    }

    public class SimplyParameter
    {
        public SimplyParameter()
        {
            Console.WriteLine("I'm Creating!");
        }
        
        public bool IsSuccess { get; set; } = true;
        public string Message { get; set; } = "It's me!";
    }
}

/api/test?a=2 => True

並且在 “It’s me!” 下中斷點，可以觀察到在進入 Test 前，的確建立了 SimplyParameter 並給予預設值

/api/test?IsSuccess=true

中斷點的執行順序為：

建立 SimplyParameter
執行 public bool IsSuccess = true; 給予初始值
執行 public string Message = "It's me!" 給予初始值
呼叫 SimplyParameter() 建構式，觸發 "I'm Creating!"
呼叫 IsSuccess 的 set，將 QueryString 傳遞的值塞進去
對於 QueryString 未提供的 Message，則未呼叫其 set，保持預設值
回到 string Test() 方法，SimplyParameter 已建立，無視 parameter = null

看起來當有傳遞 QueryString 的時候，就會先建立需要的 Model 再逐一嘗試設值。

接著讓我們試試看，當 [FromUri] 的複雜型別不只一個的時候會怎麼運作呢：

[RoutePrefix("api")]
public class ValuesController : ApiController
{
    [HttpGet, Route("Test")]
    public string Test(
        [FromUri] SimplyParameter parameter = null,
        [FromUri] AnotherSimplyParameter parameterAnother = null)
    {
        return parameter?.IsSuccess.ToString() ?? "It's NULL!"; // False
    }

    public class SimplyParameter
    {
        public SimplyParameter()
        {
            Console.WriteLine("I'm Creating!");
        }

        public bool IsSuccess { get; set; } = true;
        public string Message { get; set; } = "It's me!";
    }

    public class AnotherSimplyParameter
    {
        public AnotherSimplyParameter()
        {
            Console.WriteLine("I, Another me, are Creating!");
        }

        public int Idx { get; set; } = 999;
        public string Name { get; set; } = "WOW";
    }
}

/api/test?a=2

SimplyParameter 和 AnotherSimplyParameter 會依照 Test() 中傳入的順序，各自經歷一次上述的流程，故兩者都不會是 Null

/api/test?IsSuccess=true

即使傳入的參數只有其中一個 Model 具有符合的欄位，但由於上述的順序是「先建立，再比對」，故仍然會按上述流程分別建立兩者，仍然不會是 Null

/api/test?parameter.IsSuccess=true

即使已經具名指定了 SimplyParameter，但動作和 IsSuccess=true 仍然一樣

最後，我們加入一個簡單型別試試看，也就是改為如下：

public string Test(
    [FromUri] SimplyParameter parameter = null,
    [FromUri] AnotherSimplyParameter parameterAnother = null,
    [FromUri] string hello = "world!")

/api/test => hello = “world!”;

/api/test?a=2 => hello = “world!”;

簡單型別的預設值在運作上非常直覺，沒有什麼太大的問題。

[HttpGet, Route("Test")]
public string Test(
    [FromUri] string hello,
    [FromUri] SimplyParameter parameter = null,
    [FromUri] AnotherSimplyParameter parameterAnother = null)

/api/test?hello=A

即使我們已經給了作為必要參數的簡單型別值，但由於同樣是從 Uri 來的，並不會在把值丟給簡單型別後就停止，兩個可選的複雜型別仍然會被建立

小結

在指定複雜型別為 [FromUri] 的場合，有以下注意事項
- 有傳遞 QueryString 的參數時，放在 [FromUri] 的複雜型別會先建立出實體，再嘗試和 QueryString 的內容進行比對與設值。
  - 也因為會先建立實體，故選擇性參數的預設值，例如 parameter = null 或是 parameter = default 並沒有效果，而是以該類型中各成員的預設值為主
  - 因此如果遇到要針對各參數給定初始值的場合，請不要直接設定在 [FromUri] 的複雜型別身上再偷雞手動給值，而是乖乖地針對型別中的成員做設定
- parameter = default 當且僅當沒有傳遞任何 QueryString 的時候才有效（不過原本都沒給就會是 Default ，也就是 null，所以有沒有效我肉眼也分不太出來）
然後關於一開始的問題，最後認命地請使用端傳參數解決了，耶嘿

同場加映

.Net Core 3.1 Web Api - FromQuery

[ApiController]
[Route("[controller]")]
public class TestController : ControllerBase
{
    [HttpGet]
    public string Get([FromQuery] SimplyParameter parameter = null)
    {
        return parameter?.IsSuccess.ToString() ?? "It's NULL!"; // False
    }
}

public class SimplyParameter
{
    public bool IsSuccess { get; set; }
    public string Message { get; set; }
}

/test => False

不愧是 Core，直接就建實體了，畢竟都說是 FromQuery 了嘛。既然都直接說會從 Query 來了，就沒在跟你五四三看有沒有 QueryString 的啦 XD

參考資料

菜雞抓蟲: Url 變得怪怪的？你可能是零寬空格（ZWSP）的受害者！

Igouist (Igouist) — Sat, 26 Jun 2021 21:53:00 +0800

這週遇到個想不到的坑，特別來記錄一下。故事是這樣的－－

在需要呼叫其他 API 服務時，發生了以下怪事：

打某支查詢 API，突然查不到任何東西，或是跳出參數錯誤
有些需要用參數組成 URL 的 API 跑出 Not Found
- 第一組資料呼叫成功，第二組突然路徑錯誤
寫入的時候，資料莫名其妙多了個 ?
- 例如原先的資料是 ABC，不知怎地變成了 ABC?

由於這些操作都涉及到同一個參數，直覺上就是我們這邊給的參數出了點問題，馬上進入找犯人的環節。直接中斷點標記下去，反覆觀察該字串，但它就是一個普通的字串 "ABC"，完全看不出什麼端倪。

正要覺得參數沒有問題的時候，赫然發現組出來的 Url 相當不對勁：在該參數的後方，多出了 %E2%80%8B 這串神秘東西！

當下我驚呆了，我們傳出去的 Url 裡，並不是預想的 /api/product/ABC，而是 /api/product/ABC%e2%80%8b！真是赤裸裸的背叛！這串鬼東西到底是什麼來頭？！

一查下去，原來這東西叫做 零寬空格（Zero-width space, ZWSP）

顧名思義，就是完全沒有寬度的空白字元。這東西在 Unicode 叫做 U+200B，我們比較常見到的是編碼之後的樣子 %e2%80%8b 或 \xe2\x80\x8b。他還有另外兩個兄弟 U+200C、U+200D，平常在泰文、高棉文之類的地方工作，這東西的特色就是：肉眼不可見、殺人於無形。

它有多可怕，讓我們直接用 Linqpad 來試看看吧。

現在我們有選手 A 和選手 B，其中選手 A 偷偷嗑了禁藥 ZWSP：

var a = "ABC" + '\u200B';
var b = "ABC";

讓我們打印出來看看：

$"a:{a}".Dump();
$"b:{b}".Dump();

看起來完全一模一樣，連反白都分辨不出來！

a.Length.Dump(); // 4
b.Length.Dump(); // 3

看來其中一個傢伙明顯比較長。

(a == b).Dump();      // False
(a.Equals(b)).Dump(); // False

看來這兩個傢伙完全不一樣！

目前看來，從長度和比較運算等方面都會發現它們並不一樣，但是肉眼卻分不出來。

這樣就會產生一些看起來像是 ("ABC" == "ABC") // False 的神奇場景，除了揉眼睛然後哭喊「明明就一樣」以外無從下手。更可怕的是當我們拿去組 Url，問題就出來啦：

HttpUtility.UrlEncode(a).Dump(); // ABC%e2%80%8b
HttpUtility.UrlEncode(b).Dump(); // ABC

真是完蛋。

同時在查資料的時候，也發現 NET Framework 3.5 之後的 Trim() 並不把這個零寬空格當成空白，因此單純用 Trim() 是不會把這鬼東西砍掉的。

所以如果你有以下情況，你可能是零寬空格的受害者！

存到資料庫的資料莫名多一個 ?（有看不見或編碼錯誤的字元）
呼叫 API 服務的時候，不是參數錯誤，就是直接報錯找不到（檢查組完的 URL）

這邊也順便記一下怎麼解決的，雖然是用相當暴力的方式：

(a.Replace("\u200B", "") == b).Dump(); // true

沒錯，我直接 Replace 掉它了囧，勉強度過了這次危機。

備註：如果有更好的處理方式，也歡迎提供給我呦，感謝～

雖然我更疑惑的是，資料裡面到底為啥會出現這種東西啦囧……

最後感謝一下這次讓我得到幫助的網路文章。每次 Debug 都要感謝前人們的禮物，謝謝。

C#: BenchmarkDotnet —— 效能測試好簡單

Igouist (Igouist) — Sun, 13 Jun 2021 22:25:00 +0800

「你寫那什麼鬼東西？這個ＯＯＯ寫法比較好啦！」
『聽你在屁！明明是這個ＸＸＸ寫法快= =』

哇喔！等等！想戰效能嗎？那你一定需要這款 BenchmarkDotnet！

介紹與安裝

我們在 Coding 的時候，或多或少都會有「不知道這兩個寫法哪個比較好？」、「聽說Ａ寫法比Ｂ寫法快，真的嗎？」這類關於效能的疑問。

在遠古時期，當我們需要驗證這種想法，可能就要用記錄秒數的方式，或是搭配迴圈、然後再印在畫面上等等這類土法煉鋼的方式。

然而這種單純計秒數的 Print 流測試，可能比較到了時間成本，卻忽略了吃掉的記憶體這些空間成本；又或是每次都要插一堆列印文字的語句，因為麻煩就萌生退意等等…

這時候就是 BenchmarkDotnet 出場的時候啦！

BenchmarkDotnet 是一款簡單好用的效能比較工具，可以幫助我們比對多組程式碼，並告訴我們平均的執行時間、耗用的記憶體等等。

只要使用 BenchmarkDotnet 這個神奇妙妙幫手，它就能幫我們搞定這些麻煩的事情，讓我們可以專注在要測試的程式碼內容囉。

接下來要記錄的部份有：

這邊讓我們來實際上跑過一次基本用法並記錄吧！

首先讓我們先到 Nuget 安裝 BenchmarkDotnet，因為依賴套件蠻多的，可能需要等待一下。

補充：本篇的專案範本是「主控台應用程式」，不過平常都是直接使用簡單好用的 Linqpad 快速測一下比較多。

不過反正 BenchmarkDotnet 已經夠太簡潔方便了，各位朋友用順手的方式試試看就好囉。

安裝完畢之後，就可以開始準備一下參賽選手的擂台啦～

使用 Benchmark 來指定參賽選手

既然都說要比較效能了，今天就挑個前陣子同事提到過的主題來比較吧：

「在需要回傳空串列的場合，使用 Enumerable.Empty 會比 new List<> 更好一些」

針對這個問題，附上補充資訊：Is it better to use Enumerable.Empty() as opposed to new List() to initialize an IEnumerable? - Stackoverflow

現在讓我們用這個主題來測試吧，假定：

紅方選手：用 Enumerable.Empty 來建立空串列
藍方選手：用 new List<> 來建立空串列

因為我們是要測試兩者做出空串列的差異，至少也要有個類別：

/// <summary>
/// 協力單位，用來當成串列的填充物
/// </summary>
public class Foo
{
    public Guid Id { get; set; }
    public string Bar1 { get; set; }
    public string Bar2 { get; set; }
    public string Bar3 { get; set; }
    public string Bar4 { get; set; }
    public string Bar5 { get; set; }
}

然後讓我們開始正式的佈置，先讓我們開一個 Class 來當作擂台：

/// <summary>
/// 測試用擂台
/// </summary>
public class EmptyVSNewList
{

}

然後請紅方選手上擂台：

// 紅方選手
[Benchmark]
public void Empty()
{
    Enumerable.Empty<Foo>();
}

以及我們的藍方選手：

// 藍方選手
[Benchmark]
public void NewList()
{
    new List<Foo>();
}

補充：要直接 Empty() => Enumerable.Empty<Foo>(); 也是可以的。

我個人習慣都用同一個準備好的 BenchmarkDotnet 擂台，複製改改裡面的內容就拿來測試了，所以乖乖寫出整個 Function 改起來比較方便 XD

但為了閱讀方便，本篇後續會整理成比較簡單的 lambda 寫法，請不要太在意。

選手們就定位之後，替他們加上 [Benchmark] 的屬性，作為參賽的證明。現在擂台上應該是長這樣的：

/// <summary>
/// 測試用擂台
/// </summary>
public class EmptyVSNewList
{
    // 紅方選手
    [Benchmark]
    public void Empty()
    {
        Enumerable.Empty<Foo>();
    }

    // 藍方選手
    [Benchmark]
    public void NewList()
    {
        new List<Foo>();
    }
}

接著，讓我們回到 Main 方法（或任何你要進行比試的地方），加上：

var summary = BenchmarkRunner.Run<EmptyVSNewList>();

讓 BenchmarkRunner 去抓泛型裡面有 [Benchmark] 的選手進行測試。

以我們這次示範的主控台應用程式來說，可能就會像這樣：

namespace BenchmarkDotnetTest
{
    class Program
    {
        static void Main(string[] args)
        {
            var summary = BenchmarkRunner.Run<EmptyVSNewList>();
        }
    }

    /// <summary>
    /// 測試用擂台
    /// </summary>
    public class EmptyVSNewList
    {
        // 紅方選手
        [Benchmark]
        public void Empty()
        {
            Enumerable.Empty<Foo>();
        }

        // 藍方選手
        [Benchmark]
        public void NewList()
        {
            new List<Foo>();
        }
    }

    /// <summary>
    /// 協力單位，用來當成串列的填充物
    /// </summary>
    public class Foo
    {
        public Guid Id { get; set; }
        public string Bar1 { get; set; }
        public string Bar2 { get; set; }
        public string Bar3 { get; set; }
        public string Bar4 { get; set; }
        public string Bar5 { get; set; }
    }
}

這樣就安排妥當啦！（其實也就加個測試用的 Class 和讓兩個測試方法而已囧）

BenchmarkDotnet 必須在 release 環境下啟動，先讓我們切換一下組態：

小提示：如果跟我一樣，喜歡使用 Linqpad 的朋友，右下角切換成 /o+ 才是 Release 組態呦。還有記得要用系統管理員開啟嘿。

現在雙方站定，讓我們開始比試吧！

開始執行之後，會先列一下這次測試的環境資訊，接著就會看到很多輪的比試階段（對，你不用自己寫迴圈來重複測試）：

最後就會有測試結果出爐啦：

// * Summary *

BenchmarkDotNet=v0.13.0, OS=Windows 10.0.18363.1556 (1909/November2019Update/19H2)
Intel Core i7-7700 CPU 3.60GHz (Kaby Lake), 1 CPU, 8 logical and 4 physical cores
.NET SDK=5.0.300
  [Host]     : .NET Core 3.1.15 (CoreCLR 4.700.21.21202, CoreFX 4.700.21.21402), X64 RyuJIT  [AttachedDebugger]
  DefaultJob : .NET Core 3.1.15 (CoreCLR 4.700.21.21202, CoreFX 4.700.21.21402), X64 RyuJIT


|  Method |      Mean |     Error |    StdDev |    Median |
|-------- |----------:|----------:|----------:|----------:|
|   Empty | 0.0016 ns | 0.0067 ns | 0.0062 ns | 0.0000 ns |
| NewList | 3.6262 ns | 0.0554 ns | 0.0491 ns | 3.6267 ns |

這邊可以看到當年統計課熟悉的那些平均值、標準差等等（不過平常戰效能的時候都直接看平均時間比較多啦）

補充：可以在擂台的類別上（在這個例子中就是 EmptyVSNewList）加上
[MinColumn, MaxColumn] 的 Attribute，就會多出最大值和最小值的資訊囉。例如：
|  Method |      Mean |     Error |    StdDev |    Median |       Min |       Max |
|-------- |----------:|----------:|----------:|----------:|----------:|----------:|
|   Empty | 0.0005 ns | 0.0015 ns | 0.0014 ns | 0.0000 ns | 0.0000 ns | 0.0054 ns |
| NewList | 3.7158 ns | 0.0490 ns | 0.0459 ns | 3.7072 ns | 3.6365 ns | 3.8187 ns |

現在第一階段的結果出爐啦：Enumerable.Empty 比 new List<> 快了好幾倍呢！

使用 MemoryDiagnoser 加上記憶體的比較

就像我們前面提到的：效能比較的時候，除了時間以外，也不能忘了空間！也就是說，我們還必須考量到記憶體的用量才可以。

我們在前一段知道了 Enumerable.Empty 比 new List<> 快，但是記憶體的使用呢？現在就讓我們來確認一下吧。

想要加上記憶體的測試，我們只需要在擂台的類別上，加上 [MemoryDiagnoser] 就行啦：

/// <summary>
/// 測試用擂台
/// </summary>
[MemoryDiagnoser]
public class EmptyVSNewList
{
    [Benchmark] public void Empty() => Enumerable.Empty<Foo>();
    [Benchmark] public void NewList() => new List<Foo>();
}

接著讓我們看看結果：

// * Summary *

BenchmarkDotNet=v0.13.0, OS=Windows 10.0.18363.1556 (1909/November2019Update/19H2)
Intel Core i7-7700 CPU 3.60GHz (Kaby Lake), 1 CPU, 8 logical and 4 physical cores
.NET SDK=5.0.300
  [Host]     : .NET Core 3.1.15 (CoreCLR 4.700.21.21202, CoreFX 4.700.21.21402), X64 RyuJIT  [AttachedDebugger]
  DefaultJob : .NET Core 3.1.15 (CoreCLR 4.700.21.21202, CoreFX 4.700.21.21402), X64 RyuJIT


|  Method |      Mean |     Error |    StdDev |    Median |  Gen 0 | Gen 1 | Gen 2 | Allocated |
|-------- |----------:|----------:|----------:|----------:|-------:|------:|------:|----------:|
|   Empty | 0.0028 ns | 0.0048 ns | 0.0040 ns | 0.0000 ns |      - |     - |     - |         - |
| NewList | 3.8114 ns | 0.0877 ns | 0.1077 ns | 3.8019 ns | 0.0077 |     - |     - |      32 B |

可以注意到，Empty 根本沒有動用到記憶體，反而是 new List<> 占了一些空間，還觸發了 GC。

由於 Enumerable.Empty 在時間和空間都拿下了分數，因此這邊宣布：「在需要回傳空串列的場合，使用 Enumerable.Empty 會比 new List<> 更好一些」－－正確！

這邊補一下前面提到的 StackOverflow 回答：
“Even if you use an empty array or empty list, those are objects and they are stored in memory. The Garbage Collector has to take care of them.”
“Enumerable.Empty does not create an object per call thus putting less load on the GC.”

因此如果當你的查詢有需要返回空串列的時候（例如說搜尋條件沒有結果），試試看用 Enumerable.Empty 吧！

使用 Jobs 來指定測試環境

現在我們已經考量了執行時間和記憶體，接下來要問的就是：那在不同的啟動環境之下會有差別嗎？

例如說同樣的比較，在 .NET Core 跟 .NET framework 都成立嗎？不需要開好幾個專案來測，在 BenchmarkDotnet，我們可以用 Jobs 來搞定。

現在讓我們試試看在擂台上掛上對應 .NET Core 的 [SimpleJob(RuntimeMoniker.NetCoreApp30)] 和 .NET Framework 4.7.2 的 [SimpleJob(RuntimeMoniker.Net472)] 來試試吧：

/// <summary>
/// 測試用擂台
/// </summary>
[MemoryDiagnoser]
[SimpleJob(RuntimeMoniker.Net472)]
[SimpleJob(RuntimeMoniker.NetCoreApp30)]
public class EmptyVSNewList
{
    [Benchmark] public void Empty() => Enumerable.Empty<Foo>();
    [Benchmark] public void NewList() => new List<Foo>();
}

接著我們要編輯專案檔，用多目標的方式把指定的框架加上去，否則直接執行的話會跑出 N/A。

<TargetFrameworks>netcoreapp3.0;net472</TargetFrameworks>
<PlatformTarget>AnyCPU</PlatformTarget>

小提示：專案檔就是 .csproj，除了直接開啟編輯外，也可以從 方案總管 -> (對專案右鍵) -> 編輯專案檔 來開啟呦。

此外，多目標的說明和加入方式，也可以參照 Gelis 技術隨筆的這篇使用多目標 TargetFrameworks 來讓 net72 可參考 .netstandard2.1 通過編譯並可使用

以示範專案為例，加入後的 csproj 檔案的 <PropertyGroup> 可能會長得這樣：

<PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFrameworks>netcoreapp3.0;net472</TargetFrameworks>
    <PlatformTarget>AnyCPU</PlatformTarget>
</PropertyGroup>

小提示：更改版本之後，如果編譯有發生遺失資源檔的錯誤，可以先卸載專案再重新載入試試呦。

現在讓我們來執行一次試試吧：

// * Summary *

BenchmarkDotNet=v0.13.0, OS=Windows 10.0.18363.1556 (1909/November2019Update/19H2)
Intel Core i7-7700 CPU 3.60GHz (Kaby Lake), 1 CPU, 8 logical and 4 physical cores
.NET SDK=5.0.300
  [Host]               : .NET Core 3.1.15 (CoreCLR 4.700.21.21202, CoreFX 4.700.21.21402), X64 RyuJIT  [AttachedDebugger]
  .NET Core 3.0        : .NET Core 3.1.15 (CoreCLR 4.700.21.21202, CoreFX 4.700.21.21402), X64 RyuJIT
  .NET Framework 4.7.2 : .NET Framework 4.8 (4.8.4341.0), X64 RyuJIT


|  Method |                  Job |              Runtime |      Mean |     Error |    StdDev |    Median |  Gen 0 | Gen 1 | Gen 2 | Allocated |
|-------- |--------------------- |--------------------- |----------:|----------:|----------:|----------:|-------:|------:|------:|----------:|
|   Empty |        .NET Core 3.0 |        .NET Core 3.0 | 0.0563 ns | 0.0310 ns | 0.0583 ns | 0.0370 ns |      - |     - |     - |         - |
| NewList |        .NET Core 3.0 |        .NET Core 3.0 | 3.7849 ns | 0.0734 ns | 0.0686 ns | 3.7755 ns | 0.0077 |     - |     - |      32 B |
|   Empty | .NET Framework 4.7.2 | .NET Framework 4.7.2 | 2.4641 ns | 0.0754 ns | 0.0806 ns | 2.4815 ns |      - |     - |     - |         - |
| NewList | .NET Framework 4.7.2 | .NET Framework 4.7.2 | 7.9914 ns | 0.1877 ns | 0.5139 ns | 7.8857 ns | 0.0096 |     - |     - |      40 B |

可以看到測試結果變成了兩組：在 .NET Core 3.0 和 .NET Framework 4.7.2 都進行了測試！

現在我們知道不管是在 Core 還是 Framework，用 Enumerable.Empty 來建立空串列都比 new List<> 快、也更省資源了。

使用 Exporters 來產生報表

現在確定哪一組寫法效能比較好了。想要說服大大改用新寫法，怎麼辦呢？當然是 ~~自己偷偷改~~ 要拿出證據說服大大啦！

剛好，BenchmarkDotnet 也提供了產出報表的功能，並且可以輸出成 HTML、Markdown 等格式，只需要加上對應的屬性就可以囉，例如 [HtmlExporter]、[CsvExporter]，現在讓我們一股腦都丟上去看看：

/// <summary>
/// 測試用擂台
/// </summary>
[HtmlExporter]
[AsciiDocExporter]
[CsvExporter]
[CsvMeasurementsExporter]
[PlainExporter]
[RPlotExporter]

[MemoryDiagnoser]
[SimpleJob(RuntimeMoniker.Net472)]
[SimpleJob(RuntimeMoniker.NetCoreApp30)]
public class EmptyVSNewList
{
    [Benchmark] public void Empty() => Enumerable.Empty<Foo>();
    [Benchmark] public void NewList() => new List<Foo>();
}

當我們執行的時候，會存一份 Log 在 .\BenchmarkDotNet.Artifacts 裡面

而當我們有指定輸出報表，當執行完畢之後，報表就會產生在 Log 的 result，也就是 .\BenchmarkDotNet.Artifacts\results 裡面。

以我的環境為例，就會產生在專案裡的 \bin\Release\netcoreapp3.0\BenchmarkDotNet.Artifacts\results：

其中每個格式的樣子會不太一樣（有點廢話），例如 HTML 的是長這樣：

而看起來最厲害的應該是用Ｒ的，不過因為我沒有安裝Ｒ，這邊就請大家看一下官網的圖過過癮唄：

至於報表的詳細操作，大家可以官方介紹的 Exporters 頁面。

不過我是覺得大多數的場合，光是能拿出執行時間和記憶體用量的比較就已經很有說服力了啦 XD

用 Params 來指定數值

最後補充一下：有時候我們測試的對象，可能也會受到內容物的影響。

例如一些純計算的方法，可能就會受到數值大小的影響，這時候我們就可以使用 Params 的屬性來指定數值，並觀察不同狀況下的表現。例如：

public class ParamsTest
{
    [Params(10, 10000)]
    public int A { get; set; }

    [Params(2, 20000)]
    public int B { get; set; }

    [Benchmark] public int Cul() => A * B;
}

這樣跑出來的結果就會按照指定的數值分組囉：

| Method |     A |     B |      Mean |     Error |    StdDev | Median |
|------- |------ |------ |----------:|----------:|----------:|-------:|
|    Cul |    10 |     2 | 0.0000 ns | 0.0000 ns | 0.0000 ns | 0.0 ns |
|    Cul |    10 | 20000 | 0.0000 ns | 0.0000 ns | 0.0000 ns | 0.0 ns |
|    Cul | 10000 |     2 | 0.0071 ns | 0.0146 ns | 0.0200 ns | 0.0 ns |
|    Cul | 10000 | 20000 | 0.0008 ns | 0.0015 ns | 0.0023 ns | 0.0 ns |

如果想要把指定的數值另外拉出來做成串列，比較好維護和測試的話，也可以用 ParamsSource 來指定數值的來源。

例如上面的例子，也可以改寫成：

public class ParamsTest
{
    public IEnumerable<int> SourceA => new [] { 10, 10000 };
    public IEnumerable<int> SourceB => new [] {  2, 20000 };

    [ParamsSource(nameof(SourceA))]
    public int A { get; set; }

    [ParamsSource(nameof(SourceB))]
    public int B { get; set; }

    [Benchmark] public int Cul() => A * B;
}

效果會是一樣的，而且也比較好管理。

結語與參考資料

我們的 Enumerable.Empty vs new List<> 對決也告一段落了。

當然，BenchmarkDotNet 能做到的事還有很多，例如用 Filter 來篩選指定的測試案例、把某個測試案例作為基準案例等等進階用法，還有更多的統計資訊。但目前還沒有接觸到，這邊就先不提了，有需要的朋友再翻一下參考資料唄。

這篇文章主要參考自同事提供的範例說明，以及網路大大們的介紹文。特此感謝：

還有相當完善的官方文件：

Getting started - benchmarkdotnet.org

最後，每當你想要問「甘安捏」的時候：

用 BenchmarkDotnet 跑一遍就對啦！ 都給我戰起來！

菜雞新訓記 (4): 使用 Swagger 來自動產生可互動的 API 文件吧

Igouist (Igouist) — Sun, 16 May 2021 22:42:00 +0800

這是俺整理公司新訓內容的第四篇文章，目標是簡單地使用 Swagger 工具來自動產生可互動的 API 文件。

提醒：還不太認識 API 的朋友，可以先閱讀：菜雞新訓記 (2): 認識 Api & 使用 .net Core 來建立簡單的 Web Api 服務吧呦

章節目錄

從 API 規格文件開始

我們介紹 API 的時候有提過：API 是為了讓兩個服務之間可以溝通、互動所產生的接口。而所有的溝通要有效，都一定要先有共識，隨著溝通的人數越來越多，或是內容的理解要越來越細，就會用文件或契約的方式來達成共識。

回到我們的 API 服務開發來說，就是你除了把服務生出來了，可以跑了以外，還有一個重要的點是：必須讓所有的使用者（包含幾個月後的你自己）知道怎麼使用這組 API 服務。

也就來說，就是要寫 API 規格文件 啦！

為了能讓服務對接順利，以及省下大部份口沫橫飛解釋的時間，甚至是讓自己和使用者好幾個月之後能夠順利回想起來，我們在開發 API 的時候一定會列出 API 接口的規格和用法。

通常一份 API 文件的內容包括但不限於：用途、路由、參數、回傳值，像是參數要放在 Route, QueryString 還是 Body？哪些參數是必填的？回傳的 JSON 範例…等等，都是 API 文件會整理的內容。例如：

## GET /card/{id}
**查詢指定編號的卡片**

### Parameter

- Route
    - `id (int, required)` 卡片編號

example: https://exampleProjN.com/api/card/1

### Response

200: 回傳對應的卡片
{
  "id": 0,
  "name": "string",
  "description": "string",
  "attack": 0,
  "health": 0,
  "cost": 0
}

404: 找不到

這邊已經把例子簡化很多了，實際上的 API 文件格式會隨著各地的團隊習慣而改變，用表格、PDF 甚至 Word 之類的狀況也很常見。

對 API 規格都長怎樣有興趣的朋友，也可以直接在網路上找找一些公開的文件：

不過寫文件畢竟是能登上靠北榜的工作內容之一（靠北榜還包括其他人不寫文件、寫註解、其他人不寫註解等），同時，每次 API 有變動還要一直去維護文件真的很麻煩，所以…

我們工程師的美德，就是懶惰！ API 文件什麼的，當然是要用自動產生的啦～

今天要介紹的 Swagger 工具就是幫助我們來自動產生 API 規格文件的好幫手，接下來就先讓我們稍微認識一下 Swagger 吧！

什麼是 Swagger？

先上結論：Swagger 是一套 API 文件產生器，可以幫我們從 API 產生規格文件，更可以建出一個讓使用者能直接呼叫 API 的網頁。

原本我們說 Swagger 的時候，可能是指 API 文件格式的規範，也有可能是指自動把程式碼轉換成 API 文件的工具。不過 Swagger 在 2015 捐贈給 OpenAPI 之後，一般都用 OpenAPI 來稱呼 API 文件規範了。而 Swagger 更多時候是指 API 文件產生器和相關的生態系，例如像是把 API 文件轉成可互動網頁的 Swagger UI。

想知道用 Swagger 工具產生的 API 文件長怎樣的朋友，可以到這些地方逛逛按按：

操作上挺直覺的，而且我們前面提到的「用途、路由、參數、回傳」等等 API 資訊都清楚明瞭的顯示，甚至還可以戳一戳，直接呼叫 API 來動手試試。更重要的是：這些都是自動產生的！所以說，Swagger，好！

也因為 Swagger 是一種工具，所以大多主流語言都會有支援 Swagger 的工具包，例如 Golang 的 swag 和 go-swagger。

在 Dotnet 陣營裡面，作為代表的則是 Swashbuckle 和 NSwag。由於工作團隊採用前者，故本篇將會以 Swashbuckle 來逐步實作。

對 NSwag 有興趣，或是工作要求採用的朋友。可以參閱以下資料：

使用Swagger自動建立清晰明瞭的REST API文件 - 我與 ASP.NET Core 的 30天

微軟文件的 NSwag 與 ASP.NET Core 使用者入門

安裝 Swashbuckle 及啟用 Swagger UI

現在讓我們把鏡頭回到我們在上一篇裡使用 .net Core 預設的 Web API 範本建立的簡易 CRUD 服務。

首先，直奔 Nuget、搜尋 Swashbuckle，應該可以看到一整排：

我們這個示範專案的環境是 .net Core，所以我們選擇 Swashbuckle.AspNetCore，安裝了懶人包，就等於裝好了 Swashbuckle 家的 OpenAPI 三劍客 Swagger、SwaggerGen、SwaggerUI，之後的文件產生和進階操作也就不用煩惱了。

環境不是 .net Core 的 Asp.net Web API 朋友，請安裝 Swashbuckle，不過整體操作和顯示上並不會相差太多。

此外，在安裝和操作上也可以參照 mrkt 大大的 Swagger 相關文章：

ASP.NET Web API 文件產生器 - 使用 Swagger - mrkt 的程式學習筆記

Swashbuckle - Swagger for Web Api 顯示內容的調整 - mrkt 的程式學習筆記

安裝完成之後，就讓我們來註冊 Swagger 服務吧！

首先讓我們到 Startup.cs 的 ConfigureServices，加上 services.AddSwaggerGen(); 把 Swagger 的服務掛上去：

// This method gets called by the runtime.
// Use this method to add services to the container.
public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();

    services.AddSwaggerGen(); // 註冊 Swagger
}

接著往下看，到 Configure 把 Swagger 服務打開，我們需要加上 UseSwagger 讓它能夠用 middleware 產生 API 文件的 JSON，並用 UseSwaggerUI 指定 JSON 檔案來產生 API 文件的 UI 頁面。

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
});

這樣就啟用了 Swagger 的服務了。

現在讓我們執行偵錯，並且到專案目錄底下的 /swagger 路徑（以我為例就是 localhost:44304/swagger），應該就能看到 Swagger 工具的介面啦！

並且在上面可以注意到我們自動生成的 API JSON 文件，也就是前面註冊時看過的 /swagger/v1/swagger.json（以我為例就是 localhost:44304/swagger/v1/swagger.json）

這邊大致上就可以了解到，Swagger 工具就是藉由去掃我們的 ApiController，產生出對應的 API 規格的 JSON 檔案，再讀取這個 JSON 檔案來產生出 Swagger 的 UI 頁面。

補充：這邊也可以對 Swagger 的 UI 路徑進行設定，不一定要在 /swagger 底下。只需要在 UseSwaggerUI 中使用 RoutePrefix 就可以指定 Swagger UI 的 Route。

例如說我想要一進來我們服務的網址，就直接顯示 Swagger 畫面，像是 myapi.com 就顯示 Swagger UI 而非 myapi.com/swagger 的時候，就可以這樣設定：
app.UseSwaggerUI(c =>
{
   c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");
   c.RoutePrefix = string.Empty; // 指定路徑為 ""
});
這樣就會直接在指定的路徑顯示 Swagger UI 囉！

補充：如果有在 Properties/launchSettings.json 設定偵錯時的起始頁面的朋友，也可以試試把起始頁面 launchUrl 設定成 Swagger UI 的路徑，例如 "launchUrl": "swagger"，平常測試的時候會順手很多，推薦給大家

接著讓我們用 Swagger UI 來測試一下 API 吧，首先讓我們新增一張卡片，選擇新增卡片的 API 並試試 Try it out，可以看到範例和輸入 Body 的區塊：

執行之後下方就會告訴我們執行結果和回傳：

接著試試用 Swagger UI 來 GET 看看是不是真的有新增成功：

確認 Swagger UI 的確和我們的 CardController 銜接在一起了，啟用服務成功！

使用 SwaggerDoc 增加專案描述

不過現在只是一個可以互動的操作介面而已，離可以取代文件還有一段距離，接著就讓我們一步一步來增加資訊到這個 UI 介面吧。

首先讓我們回到 ConfigureServices，修改一下 AddSwaggerGen，讓我們可以丟東西進去，這邊就直接用微軟文件的範例來稍作修改：

services.AddSwaggerGen(c =>
{
    // API 服務簡介
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "菜雞 API",
        Description = "菜雞新訓記的範例 API",
        TermsOfService = new Uri("https://igouist.github.io/"),
        Contact = new OpenApiContact
        {
            Name = "Igouist",
            Email = string.Empty,
            Url = new Uri("https://igouist.github.io/about/"),
        },
        License = new OpenApiLicense
        {
            Name = "TEST",
            Url = new Uri("https://igouist.github.io/about/"),
        }
    });
});

這邊可以填入版本、API 名稱和說明、聯絡方式等資訊，這些資訊會顯示在 Swagger UI 的開頭：

替自己的服務加上說明是絕對必要的，不過平時會比較常用的也是 Title、Description 這些基本欄位，各位再按照自己的服務調整吧。

使用 XML 文件和 IncludeXmlComments 從註解產生 API 說明

我們有了整個服務的說明之後，當然也要替每一支 API 補上說明啦！

這邊我們可以採用產生 XML 檔案的方式來讓 Swagger 取得每支 API 在 Function 上的註解，這樣就能自動產生 API 的說明了。

首先就是要打開 XML 文件，先讓我們從 方案總管 對我們的專案 右鍵，選擇 屬性：

進入屬性頁之後，到 建置，找到 XML 文件檔案 並勾選起來，通常會自動幫你填入路徑：

補充：並非使用 Visual Studio 開發的朋友，也可以參考微軟文件的開啟方式：打開 .csproj 檔案，並找到 PropertyGroup 加上 GenerateDocumentationFile ，並設為 true，例如：
<PropertyGroup>
 <GenerateDocumentationFile>true</GenerateDocumentationFile>
</PropertyGroup>

補充：如果開啟 XML 文件檔案的選項後，建置或偵錯時跳出找不到 XML 檔案的錯誤，可能是生成失敗，可以嘗試改用系統管理員開啟 Visual Studio 再重新建置。

完成並儲存之後，讓我們回到 ConfigureServices 的 AddSwaggerGen 部分，把讀取 XML 的命令也加進去：

var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
c.IncludeXmlComments(xmlPath);

如果在上一個步驟有加入專案描述，現在的 AddSwaggerGen 可能會長這樣：

services.AddSwaggerGen(c =>
{
    // API 服務簡介
    c.SwaggerDoc("v1", new OpenApiInfo
    {
        Version = "v1",
        Title = "菜雞 API",
        Description = "菜雞新訓記的範例 API",
        TermsOfService = new Uri("https://igouist.github.io/"),
        Contact = new OpenApiContact
        {
            Name = "Igouist",
            Email = string.Empty,
            Url = new Uri("https://igouist.github.io/about/"),
        }
    });

    // 讀取 XML 檔案產生 API 說明
    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    c.IncludeXmlComments(xmlPath);
});

小提示：這邊的 xmlFile 路徑是對照前面步驟專案屬性中的 XML 產生路徑，並用反射的方式去符合自動產生路徑的規則拿到 XML 檔案。

如果在前面的步驟有自己指定 XML 檔案產生路徑的朋友，這邊的 xmlFile 也要記得和 XML 檔案路徑對應上呦。

最後也是最重要的一步：確保你的 ApiController 底下的各 API 有乖乖加上註解：

小提示：搭配 GhostDoc 自動產生註解，又快又香！用過就回不去了。

相關的說明可以參見：使用 GhostDoc 自動產出符合語意的註解 - 搞搞就懂

確定 對專案開啟產生 XML、讓 Swagger 讀取 XML、乖乖寫註解 三個步驟都有完成之後，就可以開啟 Swagger UI 來看看啦！

可以看到每支 API 都有顯示註解的名稱了，讓我們跟沒有的時候比對一下：

是不是貼心多了呢？

並且如果對參數、傳入和傳出的 Model 都有確實加上註解的話，在 API 的內容頁面就可以直接看到 QueryString 的參數，並且對 Model 點選 Schema 也會顯示 Model 的說明：

如此一來參數和回傳，從名稱、說明、型別和範例都有了，這樣才有 API 文件的感覺嘛！

除了基本的 summary 用來標示 API 的用途、param 用來標記參數名稱之外，比較特別的就是可以加上 remarks 來替 API 做更詳細的說明，例如：

這樣就會顯示在 Swagger UI 上該 API 點開的內文中：

很適合用來進行更詳細的說明和備註。

通常我們做到這裡就差不多了已經具備 API 文件該有的部分了，不過資訊當然是多多益善嘛，接著就讓我們來補充一些小東西上去吧～

使用 Produces 屬性和 response 註解補充回傳資訊

我們在 API 的介紹有提到：API 的回傳有許多格式，例如最常見的 JSON、XML，或者是純文字和檔案等等。

同時，我們也提過 API 可能會根據不同狀況，也會有不同的 HTTP Status 回應，例如 404: 找不到。但讓我們確認一下我們現在的文件…

看起來預設的 Media type 並沒有作用，並且也只有 200 成功時的狀況。現在就讓我們來補充一下吧！

在目標的 Api 方法上加上 [Produces("application/json")] 就可以標示該方法的回傳格式為 application/json，例如：

這樣在 Swagger UI 上該 API 的 Responses 就會標記為指定的格式：

接著，讓我們用 ProducesResponseType 來指定回傳時的型別，以及在註解中使用 <response> 標籤來替回傳時的 HTTP Status 加上說明吧：

/// <summary>
/// 查詢卡片
/// </summary>
/// <remarks>我是附加說明</remarks>
/// <param name="id">卡片編號</param>
/// <returns></returns>
/// <response code="200">回傳對應的卡片</response>
/// <response code="404">找不到該編號的卡片</response>          
[HttpGet]
[Produces("application/json")]
[ProducesResponseType(typeof(Card), 200)]
[Route("{id}")]
public Card Get([FromRoute] int id)
{
    var result = this._cardRepository.Get(id);
    if (result is null)
    {
        Response.StatusCode = 404;
        return null;
    }
    return result;
}

這樣做的 Swagger UI 就會多出這些 HTTP Status 對應的資訊囉：

到這邊我們就提供了各種情況對應的回傳啦，隔壁同事如果問你說「為啥我打是回 400 啊？」就可以對他說「RTFW！」

2021.07.03 補充：

我們可以在方法上加上 [Obsolete] 的已過時屬性，這樣 Swagger 也會用刪除線或反灰的方式告訴使用者該方法已經要被淘汰囉。

在敝司這次的專案重構，進行 API 接口的翻新和淘汰時，就使用了 [Obsolete] 來進行標記那些被淘汰的方法和可改用的新方法，挺方便的。

關於 [Obsolete]，可以參見 m@rcus 學習筆記的這篇：設定方法 (Method) 已過時 - Obsolete

小結

這篇記錄了 Swagger 自動產生 API 規格文件的作法，從 API 的路由、說明、參數、Model 跟回傳值全方位說明，還可以試打 API，可以說是完美提供健全的 API 環境啦。

阿彌陀佛阿彌陀佛，所謂寫一篇文件勝造七級浮屠，這個 Swagger 開下去，還不飛昇當神去了。正是：API 文件寫得好，同事溝通沒煩惱；Swagger 用得好，生文件只要一秒。

那麼今天就記錄到這邊，最後就快速整理一下：

－關於 Swagger －

為了提升溝通的效率、確保將來能記得用法，因此我們要寫 API 規格文件
為了提升寫文件的效率（和懶惰），因此我們會自動產生 API 規格文件
Swagger 是一套 API 互動文件產生器，是幫助我們來自動產生 API 規格文件和測試的好幫手
- 在 Dotnet 陣營裡以 Swashbuckle 和 NSwag 最常見

－關於 Swashbuckle －

在 NuGet 安裝 Swashbuckle.Core
在 Startup.cs 的 ConfigureServices 加上 services.AddSwaggerGen(); 註冊服務
在 Startup.cs 的 Configure 加上 UseSwagger 產生 API 文件的 JSON
在 Startup.cs 的 Configure 加上 UseSwaggerUI 來使用 JSON 產生 API 文件的 UI 頁面
在 AddSwaggerGen 中，使用 SwaggerDoc 和 OpenApiInfo 加上服務描述
在 AddSwaggerGen 中，使用 IncludeXmlComments 讀取 XML 註解並產生 API 描述（需要先對專案開啟產生 XML 檔案）
- 在 ApiController 的各個 API 接口加上 XML 註解，最常見的有
  - summary 用來標示 API 描述
  - param 用來標示參數描述
  - remarks 用來標示 API 服務的說明
  - response 用來標示回傳的狀態碼說明
- 在 API 接口上加上 [Obsolete] 標示已過時
在 ApiController 的各個 API 接口加上 [Produces] 來標記回傳格式
在 ApiController 的各個 API 接口加上 [ProducesResponseType] 來標記回傳狀態對應的型別

今天的紀錄就到這邊，之後如果還有發現什麼小技巧再回來補充，也歡迎幫忙告訴我還能怎麼使用。

那麼，我們下次見～

本系列下一篇：菜雞新訓記 (5): 使用三層式架構來切分服務的關注點和職責吧

在 Swagger UI 加上驗證按鈕，讓 Request Header 傳遞 Authorize Token

參考資料

本系列文章

菜雞新訓記 (3): 使用 Dapper 來連線到資料庫 CRUD 吧

Igouist (Igouist) — Sun, 09 May 2021 11:15:00 +0800

這是俺整理公司新訓內容的第三篇文章，目標是在 .NET Core 簡單地使用 Dapper 連線到資料庫並完成 CRUD 的功能。

接續上一篇的進度，我們接著要來連線到資料庫中完成我們的 Web Api 的 CRUD 範例。因為從新訓時期到現在工作團隊作業上主要都是使用 Dapper 來做連線資料庫的工作，這邊就直接用 Dapper 來推進吧！

Dapper 有多好用呢？它輕量、它簡單、它快速。總之先把大神們的介紹文直接拿來鎮樓：

那麼按照慣例，我們先來 ~~吹捧今天的主角~~ 說明一點簡單的前因後果吧。想直接實作的朋友，可以跳到正式開工的小節呦。

章節目錄

前言、基本觀念

弱型別與強型別

在很久很久以前，從資料庫裏面撈資料庫會使用 DataTable、DataSet 的做法去取，但有一個小小的問題，就是這些做法並不是強型別的。當我們在從 Rows[0]["ID"] 取值的時候，其實我們不知道 Key 對不對，也不知道取不取得到值，更不知道取出來的值是哪個型別。

當強型別的語法寫慣了之後，再回到上面的這種弱型別環境，就常常會遇到一些令人抓狂的狀況。像是編譯的時候沒出錯，執行的時候才炸掉；因為沒有指定型別，也就無法進行某些操作，必須額外再轉型；轉了型也不知道跑起來是不是和想的一樣等等……內心充滿了不安感。戰戰慄慄，汗不敢出。

當然，強型別與弱型別各有優缺點，會按照語言環境、個人喜好等等有適用的場合。這邊就不再贅述，對這部分有興趣的朋友可以參照：

何謂「強型別」(Strong Type) - The Will Will Web

你不可不知的 JavaScript 二三事#Day3：資料型態的夢魘——動態型別加弱型別

至於我們上面提到的，像使用 DataTable 會掉的坑，可以參考 coreychen71 的這篇強型別與弱型別的範例，有使用過（踩過）的朋友可能會比較眼熟。

說到底，想要編譯時期就發現錯誤？或是不想耗費心力在轉型過程？本來就會有相對應的代價。

不過就我個人認為，既然都在 C# 這個環境了，又是嘗試向已知的資料表取值，取出來的值通常都還會進行進一步的操作，最後還是要指定型別做轉型囧…

既然你遲早要用強型別的，為什麼不一開始就用強型別呢？還能少一堆坑。

順便感謝微軟拔拔讓我有 var 可以用，自動幫我檢查型別又讓我可以爽寫，還不耗效能，讚啦。

物件關係對映（ORM）

因為前述的型別問題，大多數人就投向了 ORM 的懷抱。

ORM 的全名是物件關係對映（Object Relational Mapping），核心理念是將資料庫的資料映射到物件裡，這樣就可以在我們的程式語言中像直接操作物件一樣地去操作資料。

例如說在之前的這篇 Asp.net MVC: Entity Framework 連線資料庫，就利用了 Entity Framework 這個工具去把資料表和類別對接起來，進而直接在程式碼中對資料進行操作。

關於 ORM 的更多介紹，例如優點和缺點等等，可以參照這兩篇：

資料庫設計概念 - ORM - johnliutw

ORM 实例教程 - 阮一峰

雖然 ORM 帶來了很多方便的好處，例如說：

可以自動產生 SQL 語法不用自己寫
包裝之後的語法讓可讀性變好了，操作也變方便了
資料操作放在專案裡容易維護
通常都已經做了一些必要的處理，例如用參數的方式幫忙擋了 SQL Injection 啦，使用交易、避免更新衝突等等。

但畢竟自動產生語法是有極限的，因此 ORM 同時也有著一些問題：

肥大、前置作業太多
當語句複雜時轉換成 SQL 的效能可能會變差
對於較特別或客製化的場景可能會較難處理

最常被提到的坑就是前面提到的「複雜場景產生的 SQL 效能可能會變差」這點；而較難處理的部分，最常見的就是遇到翻寫古老 SQL 程式時，難以將原本的 T-SQL 語法順利轉換成 ORM 語法的狀況，又或者是原本的資料表設計並沒有好好弄好關聯和正規化、早已變得一團亂，導致對已經運行一段時間的專案引入 ORM 就會變得相當困難。

因此，在使用上需要根據狀況，再決定是否要用 ORM 來進行開發。像是如果對資料表的操作語句單純（例如經典傳統百年不變的 CRUD），或是不需要對 SQL 有太深的認識也要能夠開發，那使用 ORM 就是上上之選。

關於各個狀況的比較，這邊推薦黑大的閒聊：用 LINQ 還是自己寫 SQL？，整理了在 Dotnet 執行 SQL 邏輯的策略和優缺點，建議可以先看過會比較有概念。

另外，關於一些 ORM 的問題點，除了上面 ORM 介紹文章中提到的缺點以外，也可以閱讀這篇你不需要 ORM 有實際的程式碼例子可能會比較有感覺。

Dapper

那既然這樣，我們能不能在上面兩者之間取得一個平衡呢？

讓一個工具來協助我們處理和資料庫的溝通，幫忙我們把資料表對應到類別，把資料轉換成物件，讓我們可以使用強型別去開發；同時我們又可以保留大部分的彈性，像是讓我們自己撰寫 SQL 語法或一些細微的設定，讓我們可以主動去調整效能？

如果又比起 ORM 更輕量，又能快速方便好用就好了。

這種工具真的存在嗎？

有，就是今天的主角－－ Dapper！

Dapper 是一個輕量的 ORM 工具，效能好，使用簡單，自由度高。

它的特色就是快速、輕便、效能好，使用方式也相當簡單，因為它只幫你處理資料轉物件的部份，剩下的像是 SQL 語法和連線，你還是要自己負責。

不過，我們有讚讚的物件就行了唄，畢竟是物件導向嘛，能當成物件使用最重要了。而且換個方向想，至少我們奪回了 SQL 語法的自主權（？）

補充一下：如果你用了 Dapper 但還是很不想寫 SQL，場景又是簡單的 CRUD。呃，~~為什麼不去用隔壁棚的 EF~~，你可以試試加裝 DapperExtensions 或 Dapper.Contrib

當我們有了 Dapper 之後…

把 Dapper 交給那些認真到會去 SSMS 跑一次 SQL 語法看執行效能的那些朋友，你們可以盡量發揮你們的 SQL 能力取得更好的效能。

把 Dapper 交給那些覺得 Entity Framework 效能地雷太多（或只是像我一樣不太熟）的朋友，神秘的事故發生率會少很多。

把 Dapper 交給那些覺得還要先建一堆東西做一堆事才能拿資料很麻煩的朋友，快速簡單 Model 開下去 SQL 砸下去就可以爽拿 DB 資料。

把 Dapper 交給那些翻寫古老屎山的朋友，移植又臭又長 SQL 語法到新框架的時候，終於可以整個拉過來先跑，再步步為營去重構。

所以說，Dapper 好！Dapper 妙！Dapper 嚇嚇叫！

正式開工

環境準備（建立資料表、安裝 Dapper）

到這邊已經用了兩千字來吹捧 Dapper 了，差不多讓我們把鏡頭轉回到 Web Api 服務上，邊推進邊說明一些簡單的用法吧！

接續我們上一篇的進度，在上一篇裡，我們對外開了一組簡單 CRUD 的 API，用來查增修刪我們的卡片資訊。

但當時只是開了簡單的服務，資料也是暫存的而已。所以這篇的目標是將我們的 API 服務連到資料庫，真正實現對卡片資料的操作。

先讓我們說明一下本篇的示範環境，假設在 Local 的 SQL Server 裡，有著一個 Newbie 資料庫，其中有一張 Card 的資料表。其結構如下：

CREATE TABLE [dbo].[Card](
	[Id] [int] IDENTITY(1,1) NOT NULL,
	[Name] [nvarchar](50) NULL,
	[Description] [nvarchar](50) NULL,
	[Attack] [int] NOT NULL,
	[Health] [int] NOT NULL,
	[Cost] [int] NOT NULL
) ON [PRIMARY]
GO

該表用來存放基本的卡牌資訊，包含該卡牌的 ID（主鍵）、卡牌名稱、卡牌描述、攻擊力、血量、花費值。

小提示：使用其他結構的資料表，例如用自己建立的資料表，或是經典的北風資料表，甚至是公司內的資料表來練習開發的朋友，要記得後續的處理都要改成你使用的資料表的內容呦！

現在我們有了一張資料表，鏡頭轉回到我們的 .net Core Web API 服務。

既然今天的主角是 Dapper，當然要先打開 NuGet 把 Dapper 給安裝下來。

恭喜你，你已經完成本篇文章實作的一半了。

建立對應資料表的類別

使用 Dapper 的時候，我們要先準備好把資料從拉回來時，用來轉換成物件的類別。

我們在上次已經有在 Models 資料夾裡建立好 Card.cs，現在我們就來修改它。（不是從上一期開始跟的朋友，請製作一個和資料表欄位相對應的 Class）

/// <summary>
/// 卡片
/// </summary>
public class Card
{
    /// <summary>
    /// 卡片編號
    /// </summary>
    public int Id { get; set; }

    /// <summary>
    /// 卡片名稱
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// 卡片描述
    /// </summary>
    public string Description { get; set; }

    /// <summary>
    /// 攻擊力
    /// </summary>
    public int Attack { get; set; }

    /// <summary>
    /// 血量
    /// </summary>
    public int Health { get; set; }

    /// <summary>
    /// 花費
    /// </summary>
    public int Cost { get; set; }
}

小提示：如果資料表的欄位數量很多很龐大，手刻會刻到死的朋友，可以試試用 Linqpad 去產生對應的類別。請參閱 mrkt 的這篇 Dapper - 使用 LINQPad 快速產生相對映 SQL Command 查詢結果的類別。

用 Linqpad 直接從資料表產生類別，和 Dapper 搭配起來，開發上那可真是一個快啊！這邊推薦給大家。

補充：如果建立類別的時候，對於把 SQL Server 裡面的型別對應到 C# 裡有困難的話，可以參閱 SQL Server 資料類型對應（感謝 Sian 的補充）。至於其他家的 DB，呃，還請大家自己查一下囉。

建立類別的時候要注意，這個類別是用來接收你最後拉回來的資料的。要是你最後打算 Join 兩張表然後各取兩個欄位，這裡的類別就是那兩個欄位；要是你查詢之後只打算返回其中的幾個欄位，這裡的類別就是那幾個欄位。

在工作上就見識過同事在查詢一張數百欄位的大型表時，針對該表建立了少數欄位、一半欄位、全部欄位三種情況的類別，搭配了泛型和 Dapper 的轉換來接收不同數量的值，藉此控制不同查詢場景時的傳輸成本。因此，建立類別的時候還是要依照你想要拿到哪些資料下去調整比較好。

刻好要用來接資料的類別之後，接著就讓我們來實作 CRUD 的銜接部分吧！

使用 Dapper 實作 CRUD

小提示：你可能需要對 SQL 有基本的認識，至少需要知道對應 CRUD 的 SELECT, INSERT, UPDATE 和 DELETE。不太熟悉的朋友可以參考 SQL語法教學

小提示：這個章節會實際操作 Dapper 去資料表取得資料，如果過程中對 Dapper 的各個 Function 使用上有疑惑的話，可以參閱尼克人生的這篇輕量級ORM - Dapper 使用，對各方法都有範例，相當好懂，推薦給大家。

在這個步驟，我打算在方案中新增一個 Repository 資料夾，並在裡面新增 CardRepository.cs 檔案，用來放我們接下來對資料表的操作。

這邊的資料夾和檔案命名是因為在公司分層習慣了，所以原本使用 MVC 的朋友，可以把檔案或是以下實作的部分新增在代表資料處理的 Models 裡就好了，例如加到 Models/Card.cs，或是放在任何你用來放資料庫連線處理的位置即可，位置並不是本篇記錄的重點。

現在我們應該會有個空的 Class：

/// <summary>
/// 卡片資料操作
/// </summary>
public class CardRepository
{

}

然後讓我們加上連線字串，我的範例直接使用 Localhost 的 DB，所以如果你也有按照步驟來測試的話，這邊請改成你的連線字串。

連線字串放好之後，回到我們的 CardRepository，加上放置連線字串的私有常數和建構式：

/// <summary>
/// 連線字串
/// </summary>
private readonly string _connectString = @"Server=(LocalDB)\MSSQLLocalDB;Database=Newbie;Trusted_Connection=True;";

這邊採用直接放私有成員的做法，如果你有多個類別需要用到資料庫連線，可以考慮集中管理連線字串到 appsettings.json 或是 web.config 之類的地方。這邊之所以直接放到私有成員裡寫死，是因為這邊的範例情景相對簡單，先不打算挪出去而模糊焦點 ~~，而且我之後要改成依賴注入的時候也比較好改。~~

接著就讓我們從查詢全部卡片的方法開始加入吧！我們應該要有一個回傳卡片串列的方法（我這邊習慣使用 IEnumerable，比較不熟的朋友用 List 也沒關係）

準備好了嗎？深呼吸！我們要對資料表進行查詢囉：

/// <summary>
/// 查詢卡片列表
/// </summary>
/// <returns></returns>
public IEnumerable<Card> GetList()
{
    using (var conn = new SqlConnection(_connectString))
    {
        var result = conn.Query<Card>("SELECT * FROM Card");
        return result;
    }
}

就是這麼簡單！

Dapper 會替實作 IDbConnection 的類別們，也就是我們平常用的連線小幫手們加上擴充方法，讓我們可以方便簡單地使用。

小提示：過程中看到紅線請不要慌，如果有需要 using 的就請順手 using 一下，例如 Card 的類別、等等會用到的 Dapper 等等。或是像 SqlConnection 沒抓到套件，就 Alt Enter 安裝一下即可。

補充：因為 Dapper 對每個資料庫系統所產生的語法會不一樣，所以假如你是使用 MySql 的朋友，這邊的連線請改成使用 MySqlConnection

如果你的 C# 版本大於 8.0 ，using 語句甚至不需要大括弧，如果又不像我喜歡把每一小段都宣告成變數來加減表達意圖的話，整體就更簡潔了：

/// <summary>
/// 查詢卡片列表
/// </summary>
/// <returns></returns>
public IEnumerable<Card> GetList()
{
    using (var conn = new SqlConnection(_connectString))
    return conn.Query<Card>("SELECT * FROM Card");
}

這邊也能看到 Dapper 最常見的使用方式：當我們查詢的時候，可以使用 Query<T> 方法，並將我們要接收資料的類別放入泛型，再將我們的 SQL 語法做為參數傳入。Dapper 會執行 SQL 並嘗試把查詢結果轉換成我們指定的類別。

補充：Dapper 會去對照資料表的欄位名稱和類別中的欄位名稱，名稱一樣且型別能對應的就會把資料放進去。

如果遇到兩者有不一樣的，例如資料表欄位開成 card_name 但是類別中的欄位是 Name 這種時候，比較簡單暴力的做法是在 SELECT 的時候用 AS 替欄位命名，或是告訴 Dapper 指定的欄位對照，有這個需求的朋友請參照軟體主廚的這篇料理佳餚 - Dapper 自定義欄位對應的三種方式

補充：如果有好奇的朋友也可以嘗試不給 Query<T> 指定型別，這樣回來的就會是 dynamic，但是不太建議這樣用啦，畢竟我們就是打算要享受強型別的好處才這樣做的嘛！何必又回到方法不能用、執行才報錯的時代呢？乖乖建立類別還比較實在。這部分請參見每個查詢的結果都要定義並對映一個類別嗎？（使用 dynamic）

事不宜遲，我們接著建立查詢單筆的方法吧：

/// <summary>
/// 查詢卡片
/// </summary>
/// <returns></returns>
public Card Get(int id)
{
    using (var conn = new SqlConnection(_connectString))
    {
        var result = conn.QueryFirstOrDefault<Card>(
            "SELECT TOP 1 * FROM Card Where Id = @id",
            new 
            { 
                Id = id,
            });
        return result;
    }
}

從這段我們可以知道兩件事情：

除了 Query 之外，Dapper 還準備了一些針對不同查詢的 Query 方法給大家使用，例如：

QueryFirst 只取第一筆，如果找不到就報錯
QueryFirstOrDefault 只取第一筆，如果找不到就丟回預設值
QuerySingle，只取一筆，如果找不到或是找到多筆符合的就報錯
QuerySingleOrDefault 只取一筆，如果找不到就丟回預設值，找到多筆符合的就報錯

除此之外，如果你的架構已經大量使用非同步，Dapper 也都有提供非同步版本的方法使用，例如 QueryAsync，這邊的示範專案還在黑暗時代，就不贅述。

至於 Query 系列裡面比較特別的應該就是 QueryMultiple 了，它能允許同時執行多段 SQL，例如 SELECT * FROM Card; SELECT TOP 1 * FROM Card; 之類的，並取回一串結果。

取得之後再逐一用 Read<T>() 的方式來把結果轉換成物件，但由於平常開 Function 會需要考慮單一職責原則的關係，很少接觸到有需要在同個方法執行兩段 SQL 並回傳兩個甚至多個不同物件的狀況，這邊就留給有需要的朋友自己嘗試囉。

回到我們剛剛開好的查詢卡片方法，第二件事就是我們知道了 Query<T> 系列可以傳入第二個參數，用來告訴 Dapper 這次 SQL 語法會用到的變數。

只要丟個物件進去，就算是匿名物件，Dapper 也會幫忙做成 SQL 的參數。有些朋友可能會問：為什麼不直接用 + 的方式或是直接字串插值組到 SQL 裡面就好了呢？

如果真的有這個問題的話，呃，SQL Injection 先了解一下。

給那些想瞭解又懶得跳出去查的朋友：

網站安全🔒 一次看懂 SQL Injection 的攻擊原理 — 「雍正繼位之謎」

攻擊行為－SQL 資料隱碼攻擊 SQL injection

簡單來說，為了防範不良分子在 SQL 上「自由發揮」，通常都不會允許直接把傳進來的參數等等直接丟到 SQL 裡面去串起來。

所以現在比較常見也被認為是最有效的作法是，把參數另外宣告成 SQL 提供的變數，例如 Sql Server 的變數。

如此一來，資料庫就會先解析完 SQL 語法，才嘗試把變數「作為字串」塞進去指定的位置。藉此來防範 SQL Injection 的問題。

同樣是 SELECT * FROM Card WHERE id = {id};，然後傳入一樣是 1; DROP TABLE Card;

直接銜接：SELECT * FROM Card WHERE id = 1; DROP TABLE Card;
作為字串：SELECT * FROM Card WHERE id = "1; DROP TABLE Card";

這樣子的差異應該就能理解為什麼參數化查詢能夠防範 SQL Injection 了，因為通通給你包起來。除此之外，參數化查詢還有能夠重複使用執行計畫提升效能、好維護等等好處，真的是屌打字串拼接黨。

回到我們剛剛開好的查詢卡片方法，在這邊我們必須用卡片 ID 來查詢卡片，所以必須將 ID 丟進去。那就可以看到我們的 SQL 條件有加上 Where Id = @Id，告訴 SQL 我們有一個 @Id 變數，接著我們再把 ID 包成物件丟給 Dapper 請他幫忙處理一下。

不過我個人比較不喜歡把東西都集中一坨在方法的呼叫上，所以我會把 SQL 和參數都拆分出來，並使用 DynamicParameters 來建立參數，如下：

/// <summary>
/// 查詢卡片
/// </summary>
/// <returns></returns>
public Card Get(int id)
{
    var sql =
    @"
        SELECT * 
        FROM Card 
        Where Id = @id
    ";

    var parameters = new DynamicParameters();
    parameters.Add("Id", id);

    using (var conn = new SqlConnection(_connectString))
    {
        var result = conn.QueryFirstOrDefault<Card>(sql, parameters);
        return result;
    }
}

這樣切出來做成變數也比較整潔美觀好清理，如果有需要按照狀況增加 SQL 語法或參數的時候，也比較方便。例如：

// 假設查詢卡片列表的時候，為了知道這回合能用的卡片有哪些
// 需要指定卡片的「花費值」必須低於多少，所以多了一個參數 int? cost 的場合：
if (cost != null && cost > 0)
{
    sql += " And Cost <= @Cost "
    parameters.Add("Cost", cost);
}

當然上面這段只是示範，實務上在附加條件和參數的時候也會遇到…

因為不想判斷前面有沒有 WHERE 語句，所以把所有條件先放到陣列中，最後再用 String.Join 以 AND 連接起來的
同上，但比較古老的時代會使用 WHERE 1 = 1 然後再接 AND 串條件
由於參數太多，因為效能上的考量，所以不用 += 來連接 SQL 語句，而是使用 StringBuilder 的
把 SQL 語法內共用的部分拆出去做成 Private 以提高程式碼共用程度，減少重複贅詞的
直接把整個 SQL 語法拆出去放別的地方的

等等各種因應狀況所採取的手段，各位在處理這部分的時候，如果不是自己新建的專案，還請觀察一下團隊的用法再自行調整。

除此之外，這邊還有一個小細節需要補充：當我們在使用 DynamicParameters，把變數丟進去時，Dapper 會自動幫我們做型別上的轉換。

BUT！就是這個 BUT！對於一些 int 啦、bool 的是不會有什麼問題，但一些比較難對應得到的型別，Dapper 就會嘗試用比較穩的打法，例如 String 就會變成 nvarchar(4000) 之類的。

但是，型別不同對 SQL 的執行計畫也會造成影響，甚至會造成效能變差。針對這個問題，我們可以在加入參數的時候，一併告訴 Dapper 我們指定的型別。

例如前述的 parameters.Add("Id", id)，可以給第三個參數告訴它 DBType，變成 parameters.Add("Id", id, System.Data.DbType.Int32);

關於這個型別調整的部分，有興趣的朋友可以閱讀軟體主廚的這篇：Dapper 用起來很友善，但是預設的參數型別對執行計劃不太友善

裡面針對型別影響執行計畫有進行測試，並且提供了針對 DbString 更方便使用的 String 擴充方法，我們團隊也有將其應用在專案上，推薦大家可以瞭解一下。

現在我們已經解決了查詢，接著讓我們來處理一下新增卡片和修改卡片的部分吧！

首先先讓我們回到上篇的 CardParameter，把這次多的欄位也給補上。如果是這篇才加入的朋友，請自己捏一個 CardParameter.cs 出來，我們在新增和修改的時候會拿來當作參數使用。

/// <summary>
/// 卡片參數
/// </summary>
public class CardParameter
{
    /// <summary>
    /// 卡片名稱
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// 卡片描述
    /// </summary>
    public string Description { get; set; }

    /// <summary>
    /// 攻擊力
    /// </summary>
    public int Attack { get; set; }

    /// <summary>
    /// 血量
    /// </summary>
    public int Health { get; set; }

    /// <summary>
    /// 花費
    /// </summary>
    public int Cost { get; set; }
}

如果在業務上有些需求導致新增和修改的參數不一樣的朋友（例如有些欄位不開放修改），也可以考慮拆分成兩個 Parameter 去面對不同的場景。

補上之後讓我們回到 CardRepository，利用 SQL 的 INSERT 和 UPDATE 語法來把 Parameter 的內容給塞進去吧：

/// <summary>
/// 新增卡片
/// </summary>
/// <param name="parameter">參數</param>
/// <returns></returns>
public int Create(CardParameter parameter)
{
    var sql =
    @"
        INSERT INTO Card 
        (
            [Name]
           ,[Description]
           ,[Attack]
           ,[Health]
           ,[Cost]
        ) 
        VALUES 
        (
            @Name
           ,@Description
           ,@Attack
           ,@Health
           ,@Cost
        );
        
        SELECT @@IDENTITY;
    ";

    using (var conn = new SqlConnection(_connectString))
    {
        var result = conn.QueryFirstOrDefault<int>(sql, parameter);
        return result;
    }
}

/// <summary>
/// 修改卡片
/// </summary>
/// <param name="id">卡片編號</param>
/// <param name="parameter">參數</param>
/// <returns></returns>
public bool Update(int id, CardParameter parameter)
{
    var sql =
    @"
        UPDATE Card
        SET 
             [Name] = @Name
            ,[Description] = @Description
            ,[Attack] = @Attack
            ,[Health] = @Health
            ,[Cost] = @Cost
        WHERE 
            Id = @id
    ";

    var parameters = new DynamicParameters(parameter);
    parameters.Add("Id", id, System.Data.DbType.Int32);

    using (var conn = new SqlConnection(_connectString))
    {
        var result = conn.Execute(sql, parameters);
        return result > 0;
    }
}

這邊可以注意到，除了查詢用的 Query 以外，Dapper 也提供了執行指令用的 Execute。在一些不需要回傳東西的時候，例如更新和刪除，又或是單純呼叫預存程序（SP, Stored Procedure）的時候相當方便，而且當然也有提供非同步的版本可以使用。

而最強大的地方是，Dapper 支援多筆新增和更新。例如前面我們的新增卡片 Create(CardParameter parameter) 裡面：

如果我們是直接改成丟一整串的新卡片進來，也就是 Create(IEnumerable<CardParameter> parameters) 然後呼叫 Dapper 來跑 conn.Execute(sql, parameters) 是可以新增多筆卡片的，更新也是同樣的道理。

同時也因為可以執行多個 SQL 語句、新增多筆資料，Dapper 也提供了交易（Transaction），只需要 using(var transaction = conn.BeginTransaction())，完成後 transaction.Commit() 就可以囉。不過這些部份我們暫時不會用到，有興趣的朋友可以再自己嘗試看看。

補充：由於我個人習慣新增資料之後，用 @@IDENTITY 或 LAST_INSERT_ID() 這類語法把該筆資料的 ID 拉回來方便後續檢查和使用，所以在 Create() 是使用 Query<int> 的方式來取得 ID。沒有這類需求的朋友，也可以像 Update() 的部分一樣用 Execute 就可以了。

到這邊大家應該已經大致了解 Dapper 的使用方式了，讓我們把最後的刪除卡片補上去吧：

/// <summary>
/// 刪除卡片
/// </summary>
/// <param name="id">卡片編號</param>
/// <returns></returns>
public void Delete(int id)
{
    var sql =
    @"
        DELETE FROM Card
        WHERE Id = @Id
    ";

    var parameters = new DynamicParameters();
    parameters.Add("Id", id, System.Data.DbType.Int32);

    using (var conn = new SqlConnection(_connectString))
    {
        var result = conn.Execute(sql, parameters);
    }
}

到這邊我們就做完 CRUD 一套囉！現在的 CardRepository 應該會長得像這樣：

public class CardRepository
{
    /// <summary>
    /// 連線字串
    /// </summary>
    private readonly string _connectString = 
    @"Server=(LocalDB)\MSSQLLocalDB;Database=Newbie;Trusted_Connection=True;";

    /// <summary>
    /// 查詢卡片列表
    /// </summary>
    /// <returns></returns>
    public IEnumerable<Card> GetList()
    {
        var sql = "SELECT * FROM Card";

        using (var conn = new SqlConnection(_connectString))
        {
            var result = conn.Query<Card>(sql);
            return result;
        }
    }

    /// <summary>
    /// 查詢卡片
    /// </summary>
    /// <returns></returns>
    public Card Get(int id)
    {
        var sql =
        @"
            SELECT * 
            FROM Card 
            Where Id = @id
        ";

        var parameters = new DynamicParameters();
        parameters.Add("Id", id, System.Data.DbType.Int32);

        using (var conn = new SqlConnection(_connectString))
        {
            var result = conn.QueryFirstOrDefault<Card>(sql, parameters);
            return result;
        }
    }

    /// <summary>
    /// 新增卡片
    /// </summary>
    /// <param name="parameter">參數</param>
    /// <returns></returns>
    public int Create(CardParameter parameter)
    {
        var sql =
        @"
            INSERT INTO Card 
            (
               [Name]
              ,[Description]
              ,[Attack]
              ,[Health]
              ,[Cost]
            ) 
            VALUES 
            (
                 @Name
                ,@Description
                ,@Attack
                ,@Health
                ,@Cost
            );
            
            SELECT @@IDENTITY;
        ";

        using (var conn = new SqlConnection(_connectString))
        {
            var result = conn.QueryFirstOrDefault<int>(sql, parameter);
            return result;
        }
    }

    /// <summary>
    /// 修改卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <param name="parameter">參數</param>
    /// <returns></returns>
    public bool Update(int id, CardParameter parameter)
    {
        var sql =
        @"
            UPDATE Card
            SET 
                 [Name] = @Name
                ,[Description] = @Description
                ,[Attack] = @Attack
                ,[Health] = @Health
                ,[Cost] = @Cost
            WHERE 
                Id = @id
        ";

        var parameters = new DynamicParameters(parameter);
        parameters.Add("Id", id, System.Data.DbType.Int32);

        using (var conn = new SqlConnection(_connectString))
        {
            var result = conn.Execute(sql, parameters);
            return result > 0;
        }
    }

    /// <summary>
    /// 刪除卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <returns></returns>
    public void Delete(int id)
    {
        var sql =
        @"
            DELETE FROM Card
            WHERE Id = @Id
        ";

        var parameters = new DynamicParameters();
        parameters.Add("Id", id, System.Data.DbType.Int32);

        using (var conn = new SqlConnection(_connectString))
        {
            var result = conn.Execute(sql, parameters);
        }
    }
}

對接與測試

接著就讓我們回到 CardController 把這邊的操作和 API 對外的開口給銜接起來。

首先先把 CardRepository 宣告成私有成員，取代掉我們原本用來暫存卡片資料的 private static List<Card> _cards。並且在建構式進行賦值（~~一樣是打算讓之後改成注入的時候比較好改XD~~）

/// <summary>
/// 卡片資料操作
/// </summary>
private readonly CardRepository _cardRepository;

/// <summary>
/// 建構式
/// </summary>
public CardController()
{
    this._cardRepository = new CardRepository();
}

後續其實就是把 _cards 給砍掉後，並且把各個操作改成呼叫 CardRepository 對應的方法，如果是這篇才加入的朋友，也就直接建立各個方法去對接 CardRepository 即可。

過程就不再贅述。修改後應該會長這個樣子：

[ApiController]
[Route("[controller]")]
public class CardController : ControllerBase
{
    /// <summary>
    /// 卡片資料操作
    /// </summary>
    private readonly CardRepository _cardRepository;

    /// <summary>
    /// 建構式
    /// </summary>
    public CardController()
    {
        this._cardRepository = new CardRepository();
    }

    /// <summary>
    /// 查詢卡片列表
    /// </summary>
    /// <returns></returns>
    [HttpGet]
    public IEnumerable<Card> GetList()
    {
        return this._cardRepository.GetList();
    }

    /// <summary>
    /// 查詢卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <returns></returns>
    [HttpGet]
    [Route("{id}")]
    public Card Get([FromRoute] int id)
    {
        var result = this._cardRepository.Get(id);
        if (result is null)
        {
            Response.StatusCode = 404;
            return null;
        }
        return result;
    }

    /// <summary>
    /// 新增卡片
    /// </summary>
    /// <param name="parameter">卡片參數</param>
    /// <returns></returns>
    [HttpPost]
    public IActionResult Insert([FromBody] CardParameter parameter)
    {
        var result = this._cardRepository.Create(parameter);
        if (result > 0)
        {
            return Ok();
        }
        return StatusCode(500);
    }

    /// <summary>
    /// 更新卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <param name="parameter">卡片參數</param>
    /// <returns></returns>
    [HttpPut]
    [Route("{id}")]
    public IActionResult Update(
        [FromRoute] int id,
        [FromBody] CardParameter parameter)
    {
        var targetCard = this._cardRepository.Get(id);
        if (targetCard is null)
        {
            return NotFound();
        }

        var isUpdateSuccess = this._cardRepository.Update(id, parameter);
        if (isUpdateSuccess)
        {
            return Ok();
        }
        return StatusCode(500);
    }

    /// <summary>
    /// 刪除卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <returns></returns>
    [HttpDelete]
    [Route("{id}")]
    public IActionResult Delete([FromRoute] int id)
    {
        this._cardRepository.Delete(id);
        return Ok();
    }
}

接著就和上一篇一樣，讓我們按照新增 → 查詢列表 → 修改 → 查詢單筆 → 刪除的順序來跑一次看看吧！

備註：因為這邊還沒說明到 Postman 等測試軟體，所以直接使用 Powershell 呼叫 API 進行示範。已經有慣用軟體的朋友，請用自己方便順手的測試方法去呼叫就好囉。

首先讓我們新增一張卡片（記得 URL 和 Port 要改成你啟動的版本呦）：

Invoke-RestMethod https://localhost:44304/card `
 -Method 'POST' `
 -Headers @{ "Content-Type" = "application/json"; } `
 -Body "{`"name`": `"mycard`",`"description`": `"sample card`", `"attack`": 3, `"health`": 4, `"cost`": 2 }"

然後讓我們在 SSMS（SQL Server Management Studio）確認一下：

接著讓我們試試查詢：

Invoke-RestMethod https://localhost:44304/card | ConvertTo-Json

既然查詢成功了，就針對這筆來試試看修改：

Invoke-RestMethod https://localhost:44304/card/1 `
 -Method 'PUT' `
 -Headers @{ "Content-Type" = "application/json"; } `
 -Body "{`"name`": `"ourcard`",`"description`": `"sample card`", `"attack`": 4, `"health`": 5, `"cost`": 3}"

一樣在 SSMS 確認一下：

看來我們有成功更新到，讓我們針對這筆來查詢看看：

Invoke-RestMethod https://localhost:44304/card/1 | ConvertTo-Json

查詢出來的也的確是變動過的結果了。最後，讓我們把這張卡片刪除，回歸乾淨吧！

Invoke-RestMethod https://localhost:44304/card/1 `
 -Method 'DELETE'

確認資料表的卡片已經消失：

到這邊我們就宣告完工啦！

小結

我們把前篇的 Web API 服務利用 Dapper 連接到 SQL Server，並成功完成了基本的 CRUD 功能。

這邊總結一下這篇的一些小要點：

DataTable 等弱型別在使用上會有偵錯困難、必須額外轉型等問題；而直接對映的 ORM 又常有過於肥大、自動產生的語法效能可能不佳的問題
Dapper 是一款輕量級的 ORM，它具有以下特色：
- 簡單：能幫我們將資料表欄位對應到類別欄位，讓我們查詢的資料能簡單直接地轉換成物件，享受強型別的好處
- 輕便：比起其他 ORM，相當輕便，引入套件後就能快速開始使用，效能也相當不錯
- 彈性：可以自己撰寫 SQL 語法，自己進行效能的優化與調整，相對 ORM 提升了自由度和彈性，但也要自己對語法負責
使用 Query 系列的方法來進行資料的查詢
- 提供了 QueryFirstOrDefault 等方法來進一步調整查詢方式（參閱）
- 提供了 Async 結尾的非同步方法
- 在 Query<T> 中指定對應資料表欄位的類別來讓 Dapper 進行轉換
- 建立對應資料表欄位的類別時，可以用 Linqpad 來節省時間（參閱）
使用 Execute 系列的方法來進行語法的執行
- 同樣提供了 Async 結尾的非同步方法
使用 DynamicParameters 來建立參數集合
- 藉由參數化查詢迴避 SQL Injection 攻擊
- 預設的型別轉換可能會有效能問題，在使用 DBString 等難以對應的型別時，可以自訂型別轉換來提升效能（參閱）
- 允許傳遞多組參數來執行同一段 SQL 語法，藉此可以做到多筆新增、多筆更新的效果
提供了 BeginTransaction 來開啟一段 SQL Transaction
針對不同的查詢場景、邏輯的複雜程度等等，我們應該評估後再決定使用傳統 ORM 或是 Dapper 或其他方式來操作資料庫（參閱）

今天就到這邊告一段落。現在這組 Web API 已經是常見的「連接到資料庫進行基本操作」的範本了，接下來我們會針對這組 Web API 服務進行各式各樣的擺弄改造。

那麼，我們下次見～

本系列下一篇：菜雞新訓記 (4): 使用 Swagger 來自動產生簡單好看可測試的 API 文件吧

本系列文章

菜雞新訓記 (2): 認識 Api & 使用 .net Core 來建立簡單的 Web Api 服務吧

Igouist (Igouist) — Sun, 02 May 2021 12:39:00 +0800

這是俺整理公司新訓內容的第二篇文章，目標是對 Api, Restful Api, HTTP 等相關的知識點做個筆記，並用 .net Core 建立一個簡易的 Web Api 專案。

章節目錄

前言、基本觀念

我們在上一篇記錄了新訓第一天的 Git 操作筆記。接著在這篇，我們終於要進入 .net Core 啦！

目前的規劃是先從建立一個可以使用的、最簡單版本的 Web Api 服務開始，再將各個工具擴增進來。所以後續的文章應該都會以這篇的簡易 API 為基底繼續延伸下去（如果順利的話啦）

這篇文章的前半段會用來記錄一些使用或開發 API 常用到的相關知識，如果對 HTTP 的部分已經有點頭緒，或是迫不及待想直接動手用 .net Core 開 Api 服務的朋友們，可以直接跳到正式開工的部份。那麼，我們開始吧～

什麼是 API

我們在物件導向的介面時有稍微聊過所謂介面（Interface）的概念：「在兩個系統，或是兩個分層之間要介接的時候，只需要提供我這個功能的接口／介面給對方，就能讓對方知道如何使用」

API（Application Programming Interface）也是同樣的道理：

在不同的應用程式或服務（Application）之間，使用程式碼（Programming）的方式提供一組介面（Interface），讓提供方和使用方可以藉由這組介面銜接起來。

API 最貼切的比喻就是我們在封裝篇也用過的販賣機：販賣機會提供不同飲料的按鈕，當我們選擇了其中一個按鈕按下、投了錢之後，對應的飲料就會掉下來。

對應回來就是：我們到了某個服務（販賣機），去拿我們想要的資料（飲料），所以呼叫了該服務的某支 API（按鈕）並且提供了一些該 API 要求的資料（投錢），最後 API 就會把我們想要的資料交給我們（飲料）

再用更實際的例子來說就像是：假設我們想要做一款可以查詢台北市的公車動態的 APP，於是我們到了提供公車動態的運輸資料服務 TDX (Transport Data eXchange) 去找我們想要的 API，過程中我們可能需要告訴服務我們要查的是台北市，最後服務就會將公車動態的資料交給我們。

關於 API 的部份，推薦可以先閱讀過 Huli 大大的這兩篇，將基本觀念說明的相當好懂且透徹：

另外，也推一下我在 CodingBar 看到的這篇 API 到底是什麼？用白話文帶你認識和它所引用的影片：

什麼是 Restful API

都提到 API 了，當然不能不提 Restful 了。Restful 說起來比較像是 API 界的一種流派，大概就像「飛天御劍流」之於「劍道」的關係一樣。只不過因為 Restful 太 Restful（？），所以幾乎已經成為主流了。

那麼 Restful 到底是什麼呢？

前一段我們有提過，API 的一個重點是：提供我這個功能需要的接口／介面給對方，就能讓對方知道如何使用。

如果有點進去看 Huli 大大的文章，尤其是傳紙條那一篇的話，應該會察覺到在資料交換的過程中，最重要的一環就是建立共識，或者說是建立原則以降低溝通成本。

Restful 想做的也是同一件事：只要大家都有一個制定路由的共識，就可以降低閱讀和維護成本。

原先的 API 在路由的制定上並沒有什麼原則，幾乎就是看提供者爽怎麼訂就怎麼訂：

/api/create-order
/api/getProduct?id=1
/api/productDetailByProductId

但這樣就會造成額外的溝通成本。

為了消除這些溝通成本，Restful 就出現了！Restful 提倡使用「符合 HTTP 語意」和「以資源為主」的方式來處理 API 的路由。

我們用白話一點的方式來理解：大多數時候，我們發出的請求都是「對『什麼東西』做『什麼動作』」，也就是通常會有一個「動詞」和一個「目標」，Restful 就是從這兩個部份下手來達成共識。

那我們從「動作」的部分開始，也就是建立「符合 HTTP 語意」的共識：我們可以利用 HTTP 定義的請求方法（HTTP Method，也被稱為 HTTP 動作）來表達我們的要求。

上面推薦過的 Huli 大大這篇傳紙條文章中有提到，因為能做的事情太多了，光是一個訂便當相關的動作，既可以訂購便當，也要能查有哪些便當可以訂，或是訂好了卻要換成別的便當等等。因此為了將動作做個統一，就在紙條的 Header 加了欄位，用來標示這次動作是哪種類型，這就是所謂的 HTTP 方法。

常見的 HTTP Method

我們比較常見的 HTTP 方法有這幾個：

GET
- 用來查詢、取得資源。例如說「Get 最新的一筆訂單」
POST
- 用來建立新資源。例如說「Post 一筆新訂單」
- 也可以用來當萬用動詞，就是不太確定歸類在哪一個、使用其他動詞遇到障礙的時候使用
PUT
- 通常用來更新現有的資源。例如說「Put 一號訂單的新訂單內容」
- 如果服務有額外處理的話，有時候也會做成沒有這筆資源就新增一筆
PATCH
- 更新資源的時候做「部分更新」。例如說「Patch 一號訂單的出貨狀況」
DELETE
- 用來刪除資源，例如說「Delete 一號訂單」

其中有幾個部分可能會讓人有點疑惑，這邊稍微整理一下，也歡迎大家補充：

PUT vs PATCH 都是更新？

兩者的更新方式不太一樣。通常 PUT 會指整批更新、PATCH 是指部分更新。

以產品舉例的話：

PUT 比較像是把整個產品資料丟上去，然後整團更新掉
PATCH 則是只更新一部份，像是只丟產品名稱上去，然後就只更新名稱

POST 的「萬用動詞」是什麼意思？

我們有時還是會遇到不太確定要歸類到哪個動詞，或是其他動詞處理不來的情況，預設就使用 POST 處理
例如說，以 GET 查詢的時候，參數的規劃有些問題導致於 QueryString 放不太下，就可以考慮改用 POST，並將參數放入 Body

安全（Safe）、冪等（idempotent）

在查詢 HTTP 動作的時候（例如維基百科的請求方法），總是會看到「安全（Safe）」、「冪等（idempotent）」這些用詞，是什麼意思？

安全（Safe）的方法是指沒有對資料進行變更的操作。例如：
- 當我 GET 的時候，我單純只是查詢資料
  不會對資料進行任何變動，所以是安全的
- 反過來說像是 PUT, DELETE 這些會對資料進行變更的方法就是不安全的
- 使用不安全的方法的時候，就得要考慮用特殊的方式告訴系統的使用者該操作可能的變更。例如前端呼叫前會跳出視窗警告：「確認是否刪除」等等
冪等（idempotent）則是指該方法在同樣的條件下，不管重複作幾次，對資源的結果都相同。例如：
- 我一直 GET，不管我 GET 幾次，資料還是同樣那一份不會變動
- 我一直 PUT，不管我 PUT 同樣的參數幾次，資料的結果還是會長一樣
- 我一直 DELETE，不管我 DELETE 幾次，那一份資料都一樣不在了
- 我一直 POST ，就會一直長出新資料（！注意，不是 idempotent ！）
- PATCH 的部份比較特殊一點：
  - 因為我們要求更新這個資源的某一些部份的時候，並不能確定其他地方會不會變動
  - 例如說，我們更新了產品描述這個欄位，結果其實還有一個欄位是版本號，然後服務偵測到每次更新都會自動增加。
    這樣我們就算重複 PATCH 結果也有可能不一樣，因此 PATCH 並不能算是 idempotent 的

當我們知道一支 API 是不是安全的、是不是冪等的，也就可以幫助我們知道這支 API 能不能重試，當遇到某些問題時能不能大膽地再打一次請求過去。

例如說連續查詢兩次並不會對資料進行任何變動，就可以原地重查一次；但面對扣款這種危險狀況，我們當然就不會想再扣一次錢。當我們確實按照安全和冪等這些特性來運用 HTTP 動詞，就可以讓使用端得到這些資訊。

小小結與推薦閱讀

那麼補充就先到這裡。除了上面只列出了我個人平常比較常接觸的 HTTP 方法之外，其他還有 HEAD、TRACE 等等，有興趣的朋友可以再逛逛 MDN 的 HTTP 請求方法。

現在我們大概知道了有這些 HTTP 方法可以使用，也因此已經將動作抽離出來了。接著就輪到我們要進行這些動作的「目標」了，這部份則要求：我們在制定路由的時候，應該從「資源」的角度下去考慮。

這相當直覺，例如「新增訂單」、「查詢產品」這樣，我們動作後面接續的應該要是一個資源。從這個方式下去定的話，上面的範例應該就會變成：

POST /api/order
GET /api/product/1

很明確就能夠看出意圖。這邊就讓我們來看看微軟的 Web Api 設計文中的範例表格：

Resource	POST	GET	PUT	DELETE
/customers	建立新客戶	擷取所有客戶	大量更新客戶	移除所有客戶
/customers/1	錯誤	擷取客戶 1 的詳細資料	更新客戶 1 的詳細資料 (若有的話)	移除客戶 1
/customers/1/orders	為客戶 1 建立新訂單	擷取客戶 1 的所有訂單	大量更新客戶 1 的訂單	移除客戶 1 的所有訂單

這邊大致上有個感覺就行了，畢竟 Restful 是一種風格，並沒有強烈的規定，只要符合共識和約束，就可以算是 Restful 了。

在微軟把拔的 RESTful Web API 設計中，援引了 Leonard Richardson 的 API 成熟度模型：

等級 0：定義一個 URI，而所有的作業對此 URI 都是 POST 要求
等級 1：針對個別資源建立不同的 URI
等級 2：使用 HTTP 方法來定義資源上的作業
等級 3：使用超媒體 (HATEOAS)

目前就內文所述，大多數的已發行 API 約略是等級 2 附近，也就是這次介紹的：使用 HTTP 動詞 + 從資源出發的設計方針。只要掌握這個方向，基本上就沒什麼問題了。

同樣的，這個訂立的原則，也就得仰賴多去看人家的 Api 怎麼設計來培養了。但只要把握幾個重點：建立共識、提高可讀性，還有設計的時候好好和來介接的夥伴喬一下，基本上就不會有什麼差錯啦，畢竟這東西很彈性的。

當然，本篇只是稍微說明而已，非常鼓勵各位朋友再進一步搜尋了解。最後推一下這兩篇 Restful API 相關的文章：

休息(REST)式架構? 寧靜式(RESTful)的Web API是現在的潮流？
- 我個人覺得寫得很清楚明瞭，並且範例也相當好懂，咱們當初新訓的時候也是看這篇來了解概念的
簡明 RESTful API 設計要點
- 針對一些要點有說明，有興趣的朋友可以稍微看過一遍。內文提到的 HTTP Status 我們等等也會進行說明

什麼是 HTTP Request 和 Response

現在讓我們運用動詞（HTTP 動詞）和名詞（Restful 風格的路由），就可以組出像是 GET product/1 這樣子的 Api 路徑。用寄送信封的方式來說的話，現在我們就等於已經掌握了寄送的地址。

我們有了地址之後，才能寄信到這個地址給對方，並且等待對方的回信（話說這年頭大家都用網路通訊了，會不會過幾年沒人看得懂這組經典比喻啊？）。

而我們有了 Api 的地址（URL）之後，就可以對這個地址上的服務送出一個 Request（請求），服務接受到請求之後，就會給予我們一個 Response（回應）。

這個送出請求、取得回應的動作，就是網路運作的原理。例如當你打開瀏覽器到某個網站，就是對該網站發出一個取得網站內容的請求，網站再給你網站內容的回應。

補充一下，聰明的朋友可能發現了，我們前面介紹的 Api 也就是這組動作：當我們呼叫某個服務，例如 Google Map 的 Api，也就是對目標的 Api 發出了一個想要使用服務的請求，服務再針對請求給予回應。因此，要想了解 Api 的各個知識點，接觸 HTTP 是必不可免的。

但 HTTP 這水挺深的哪，所以我們這篇的紀錄先以「打 Api 服務的時候不至於都看不懂」為目標進行，稍微介紹一下 Request 和 Response 的內容吧。來日方長嘛。

Request 和 Response 的內容，有興趣的朋友可以直接在瀏覽器進入開發人員工具就能看到了，以 Edge 和 Chrome 為例：首先按下 F12 ，並找到網路（Network）的部分，就可以看到進入網頁的各個請求和回應，隨便點開一個就會有 Request 和 Response 的內容囉：

或者是可以直接參考 NotFalse 技術客的這篇 HTTP/1.1 — 訊息格式 (Message Format)，裡面對 HTTP 請求格式的各個部分上色並逐步講解的方式讓我蠻喜歡的，相當清楚。

接著就讓我們來看一下訊息的格式，通常會分成三個比較主要的區塊：Start Line、Header、Body：

HTTP/1.1 200 OK // Start Line

// Header
Content-Type: application/json; charset=utf-8
Date: Mon, 26 Apr 2021 14:00:31 GMT

// Body
{
  "name": "nike",
  "category": "shoes"
}

首先讓我們看看 Start Line：

HTTP/1.1 200 OK // Start Line

Start Line 在 Request 的時候又叫做 Request-line，會標明 HTTP Method、URL、HTTP 版本。

例如 GET /product/1 HTTP/1.1。我們上一節學的 HTTP 動作（GET、POST…）和路由地址（/product/1）就是用在這裡。

而 Start Line 在 Response 的時候又叫做 Status-line，會標明 HTTP 版本、HTTP 狀態碼（Status Code）和描述。

例如 HTTP/1.1 200 OK，這個狀態碼就是 Response 中的主要回應，我們在下一節會介紹一些常看到的 Status Code，現在先知道這裡就是服務用來告訴你「好呀」跟「不要」的地方即可。

Start Line 會放在整個訊息的第一行，之後會用個空行做分隔，後面再接著 Header。

讓我們順著來看看 Header：

// Header
Content-Type: application/json; charset=utf-8
Date: Mon, 26 Apr 2021 14:00:31 GMT

Header 又叫作標頭、表頭等，主要是用來放這次訊息相關的參數和資訊。

例如說用 Content-Type 來說明這次訊息傳輸的格式，可能是表示 HTML 的 text/html，或者是表示 JSON 的 application/json 等等；也有可能用 cookie 來表示瀏覽器當前紀錄的資訊等等。

Header 可以放的資訊有挺多種的，有興趣的朋友可以看看這篇 HTTP 前後端傳輸流程，列出了常見的 HTTP Header 欄位；如果好奇上面提到的 Content-Type 有那些常用的種類，也可以參照這篇 Postman 常見的 Content-type，這邊就先按下不表。

補充：除了規範的 Header 欄位以外，我們有時也會在 Header 裡放一些自訂的欄位。以前的慣例是用 X- 開頭來標示，例如 X-Custom-Header，但 RFC 6648 建議停止繼續用 X-，而是直接用好讀好懂的名稱來定 Header 就好了。

Header 結束之後，按照訊息的種類和內容，可以再加上 Body，兩者之間會空一行隔開：

// Body
{
  "name": "nike",
  "category": "shoes"
}

Body 又叫做回應主體，是非必須、選填的，通常我們會用來存放本次訊息需要的資料。

以寄信來舉例的話，Header 就像是外面的寄信人、收件人等資訊，而 Body 則是裡面的信件內文。但要注意，一個訊息並不一定要有 Body，就像我們也可以只寄送明信片一樣。很常聽到的一個比喻就是：GET 就像明信片、POST 就像是包裹，中間就是需不需要附加 Body 的差別。

當 GET 的時候，我們通常並不會用到 Body，如果有需要附上參數的話，GET 我們會放到 QueryString（就是接續在往指後面，常常見到的 ?a=1&b=2 那串）。

例如說取得產品列表，我們需要向 /product 發出 GET 請求，同時我們又只想要類別是鞋子、關鍵字為 Nike 的產品，那我們組出來的整個 URL 和 QueryString 可能就是這樣的：

GET /product?category=shoes&keyword=nike

/* 這邊會有一些 Header */

其他的場景，例如 POST 時，如果有需要附上資料，我們通常會用到 Json 或 XML 之類的格式放到 Body 中。例如我們現在要新增一筆新的產品，是叫做 Nike 的鞋子，那可能就會附上：

POST /product

/* 這邊會有一些 Header */

{
  "name": "nike",
  "category": "shoes"
}

如果是 XML 的話，可能就會是這樣表示：

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <name>nike</name>
  <category>shoes</category>
</root>

當然也有可能是用其他的格式，只要服務願意接受，兩邊能夠通訊其實也就沒什麼關係，說到底網頁最基本的部分也還是一個回傳 HTML 格式的 Response。所以各位如果遇見了沒看過的格式也不用驚慌，因為放在這裡都一樣是用來表示資料的格式，只是表達的方式不一樣而已。

不過我平常開發和使用 API 都是用 JSON 的場合居多（個人覺得體感上 JSON 已經快一統 API 的天下了），強烈建議至少還是要能看懂 JSON。

備註：關於 JSON 如果不太了解的朋友，可以參閱 JSON精要讀書紀錄

最後再複習一次，當我們呼叫一個 API 的時候，我們可能會送出一個 HTTP Request（請求）

GET /product/1 HTTP/1.1 // Start Line

// Header
user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) //...其他一堆標頭

然後服務就會回給我們一個 HTTP Response（回應）

HTTP/1.1 200 OK // Start Line

// Header
Content-Type: application/json; charset=utf-8
Date: Mon, 26 Apr 2021 14:00:31 GMT

// Body
{
  "name": "nike",
  "category": "shoes"
}

這樣我們就成功交換資料啦！

……當然，所謂天有不測風雲，API 有 500 Internal Server ERROR，沒有每次打 API 都一定是 OK 的啦，其他什麼 404, 500 動不動就會跑出來。

就像我們去網路購物的時候，按下購買把購物車清空後，網頁就會告訴我們「訂單成立」或是「結帳失敗」等等，當 API 的使用者將這個要求發送給 API 服務，服務就會告訴使用者針對這個要求的回應。這就是我們之前提到的 HTTP 狀態碼（Status Code）出場的時候了。

什麼是 HTTP Status Code

在上個小節中我們有提到，Response 的 Start Line 會帶著一組 HTTP 狀態碼（Status Code）和描述，用來告訴你這次請求的回應。

大概就像是告白之後的好呀、謝謝你、你是個好人等等，回應也有分成很多種，這邊就稍微紀錄一下平常遇到的幾種狀態。

1xx: 參考資訊

大多是在正式回應之前先暫時給使用者一些資訊。就像是「先讓我考慮一下…」

2xx: 成功

200: 要求成功。就像是「好呀」
201: 已建立。要求新增資源的時候會用到，就像是「OK，那我掛穩交囉」
204: 無內容。雖然點頭了，可是什麼話也沒說

3xx: 重新導向

301: 永久轉址。就像是傳了簡訊之後得到「她換手機了，我是她爸」
303: 臨時轉址，原本存在但是換了位置，就像是打電話過去結果「她出門了，我是她爸」
304: 沒有變動，可以直接去快取拿就好。就像是「說啥呢，我們都結婚五十年了= =」

4xx: 用戶端錯誤

400: 要求錯誤，大多數使用者造成無法處理的問題都會丟到這，可能是
參數沒給、這個網域不存在等等。就像是『她』說「其實我是 ♂ 的呦，沒關係嗎？」
401: 拒絕存取，可能是沒有登入、授權失敗等等。
就像是「你是誰？！我根本不認識你啊？！」
403: 禁止使用，可能是沒有權限、沒有憑證、被拒絕等等。
就像是「抱歉，你的長相實在…抱歉。」
404: 找不到，這個應該是最常見的用戶端錯誤了。
就像是「你認錯人了吧…？」
418: 我是個茶壺，啊人家就只是個茶壺…

5xx: 伺服器錯誤

500: 內部伺服器錯誤，大多數問題都會被丟到這一類，我們開發人員頭痛的時候就到了…
501: 未實作，通常對一個只提供 GET 的 URL 打 POST 就會看到了。
就像是「我已經結婚囉，謝謝你呢 ^^」
502: 無效回應。就像是「我也喜歡哆啦Ａ夢呢」
503: 伺服器維護或過載。追求者太多了，根本沒空回你。
504: 閘道逾時。（已讀不回）。

對還有哪些 HTTP Status 或是想對每個 HTTP Status 發生的狀況了解得更詳細的朋友，可以參閱以下兩篇：

常見與不常見的 HTTP Status Code - Noob’s Space
- 除了列出常見的 HTTP 狀態，還收錄了一些非官方和惡搞的
- 看了這篇知道更多 HTTP Status Code 之後，本網站正考慮支持 HTTP Status 735
網頁開發人員應了解的 HTTP 狀態碼 - The Will Will Web
- 針對每個狀態有更詳細的說明，並列出了更細的 IIS 擴充狀態，例如 401.1 - 登入失敗等等
- 強力推薦 Dotnet 相關的開發人員看個一遍有個印象

什麼是 Stateless

2021.05.04: 發文之後發現忘記提到無狀態了，所以這邊回來補充一下。

接續前面提到的 Restful 風格，在 API 的制定上，Restful 還有另一個要求，就是必須是 無狀態的（Stateless）。

無狀態是指：伺服器不會儲存使用者的狀態，當使用者呼叫 API 的時候，應該給予所有 API 需要的內容。

用比較的方式來說：原本的 API 設計可能會保存使用者的動作狀態，然後留到下一次呼叫的時候再接著使用，那這樣的 API 設計的時候就像是制定食譜，必須要求使用者照順序才可以正常運作。

例如必須先打Ａ，再打Ｂ，最後打Ｃ，沒有照順序打的話就會因為狀態不對而壞掉。但這樣的做法其實就是所謂的時序耦合，不僅造成測試和使用上的困擾，也相當的不直覺、相當的有「味道」。

而我們在 Restful 的時候，是用資源的方式下去考慮，所以應該把重點放在資源的操作，而不是狀態的管理和流程，否則就會很奇怪。例如說你去買雞蛋，然後老闆突然跟你說：不行喔，因為你還沒買過牛奶。哇，整個就莫名其妙。

所以在 Restful 的設計上，每一次呼叫都應該要是獨立的呼叫，設計的時候就是以資源為主體，再利用這些資源互相搭配來完成功能。

例如說「登入之後跳出使用者待結帳的訂單，並且 Show 出訂單中的產品」這種情況，我們就不該要求使用者一定要照順序打，然後伺服器再來記住登入的資訊、使用者的編號、訂單的編號等等，除了記錄一堆多餘的資訊，更把 API 的使用場景給卡死了，相當不 OK。

這邊用資源的角度出發的話，應該讓「登入」、「查詢訂單（使用者呼叫時提供使用者編號）」、「查詢產品（使用者呼叫時提供訂單編號）」組合起來，從「將這些資源的操作組合在一起完成功能」的角度出發，那在別的流程就可以重複使用這些 API 來組成功能，同時也能分別對各個功能進行開發跟測試。

如此一來，就能提升彈性、自由度。同時，因為伺服器不用紀錄狀態，讓每一次呼叫都是獨立的呼叫，不只可以重複使用，聚焦在資源上也能讓操作變得簡潔。進一步來說，因為狀態不會被綁死在特定的機器上，那就可以開始搞擴大加機器做分散式啦。

補充一下：當然，要做到完全沒有狀態是很難的，但我們可以做到讓伺服器不要綁死、每個呼叫都是盡量獨立的，來盡可能使得服務乾淨、有彈性、可分散處理。

同時也因為這樣，為了讓使用者的狀態不會遺失（例如登入狀態），就得做到使用者的每個呼叫都要能夠證明自己的身份，所以才有了壓成 Token、把身分驗證的伺服器分離等等的驗證做法，這個部份我們有空再來填坑吧。

正式開工

現在，我們已經大概了解 API 以及 Restful API 的一些相關知識了，接著就讓我們來實際建立一個簡單的 API 服務吧！

新建 .net Core Web API 專案

首先打開我們的 Visual Studio，建立新的專案。

我們這次用 .net Core 來進行示範，並且用官方內建的 Web API 框架直接開場，所以這邊選擇 Asp.net Core Web API。

註：這些建立專案的畫面和選項隨著版本可能會有點不一樣，例如說可能會先選擇 .net Core 的 Web 服務之後，後續再勾選 API 的選項等等。例如之前的 Asp.net MVC 文章中，就需要在選擇範本的時候選擇是 MVC 或 Web API 的範本。就麻煩各位再稍微見機行事一下。

接著輸入專案名稱和選擇專案路徑，我在這邊採用 Newbie/Noob 的 N（而且 Project N 感覺很潮？），各位嘗試的時候可以自由取名，但要注意後續用到 ProjectN 這個名字的部分必須和你取的名字一致呦。

這是紀錄採用的版本為長期支援的 .net Core 3.1（如果這個步驟有選擇其他版本的朋友，後續安裝套件的時候可能要注意一下版本相容性的問題）

建立之後我們的專案結構應該會長這樣：

恭喜各位，到這一步的時候，Web API 服務已經建好了！

~~直接用範本就是這麼爽，謝謝微軟把拔。~~

我們先來稍微認識一下環境設定相關的成員：

Properties/launchSettings.json

用來放我們偵錯專案時套用的環境設定，例如說我們偵錯的時候預設要打開哪個頁面（launchUrl）就是在這邊設定
可以參見 launchSettings.json 的 commandName 是做什麼用的？

appsettings.json

用來放組態資料，像是連線字串、Log 的紀錄層級等等就會丟在這
以前用過 web.config 的朋友可能會比較熟。但在 .net Core 已經將不同職責的設定區塊拆分出去給
appsettings.json、.csproj 等等，並且可以繫結強型別，所以更乾淨了。（感謝 Mike 和 Sian 的說明）
關於兩者的差異和讀取 appsettings.json 的方法，可以參照余小章大大的這篇如何讀取 AppSettings.json 組態設定檔

Startup.cs

設定服務的行為、註冊依賴注入相關的東西就丟在這，像之前註冊 AutoMapper 服務的時候就是在這裡設定
我們後續還會常常過來找 Startup 玩

Program.cs

整個應用程式的進入點
關於服務啟動之後的順序和 Program.cs, Startup.cs 的內容，
可以參照 ASP.NET Core 2 系列 - 程式生命週期 (Application Lifetime) - John Wu’s Blog

現在這個時間點，我們還不會對設定的部分動什麼手腳，只要對這些東西有個瞭解就好了。

我們把鏡頭轉到剛剛沒提到的其他檔案，可以看到還有 WeatherForecast.cs 和 Controllers 及裡面的 WeatherForecastController.cs。

補充一下，如果之前已經對 MVC 架構有點熟悉度的朋友，應該對 Controller 這個詞不陌生了。

Web API 的範本其實也是同樣的概念，只是 View 的部分已經交給呼叫 Api 服務的使用者去處理了，而這邊的 WeatherForecast.cs 打開可以發現只是純粹的天氣資料，也就是個 Model 或 ViewModel 之類的東西。

至於 Controller 的職責仍然沒有什麼變化，就是個第一線的交通警察。所以先前做過 MVC 的朋友大概會覺得比較親近一些吧。大概。

這邊可以看到 WeatherForecast.cs 只是個用在 WeatherForecastController 的天氣資料類別。所以我們直接打開 WeatherForecastController 來觀察一下：

[ApiController]
[Route("[controller]")]
public class WeatherForecastController : ControllerBase
{
    private static readonly string[] Summaries = new[]
    {
        "Freezing", "Bracing", "Chilly", "Cool", "Mild",
        "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
    };

    private readonly ILogger<WeatherForecastController> _logger;

    public WeatherForecastController(ILogger<WeatherForecastController> logger)
    {
        _logger = logger;
    }

    [HttpGet]
    public IEnumerable<WeatherForecast> Get()
    {
        var rng = new Random();
        return Enumerable.Range(1, 5).Select(index => new WeatherForecast
        {
            Date = DateTime.Now.AddDays(index),
            TemperatureC = rng.Next(-20, 55),
            Summary = Summaries[rng.Next(Summaries.Length)]
        })
        .ToArray();
    }
}

首先在整個類別開始的地方加上了兩個屬性（Attribute）：[ApiController] 很明顯告訴我們這是個 Api Controller，而接著的 [Route("[controller]")] 用來決定我們這個 controller 的路由。

這邊要特別注意 Route 這個屬性，我們會在 Controller 和 Function 上用這個屬性來制定我們的 Api 的 URL，也就是我們前面 Restful 小節提過的「用資源制定路由」要處理的部分。

現在可以看到 Route 的內容是 [controller]，所以會直接採用 controller 的名稱，在這邊也就會是 /WeatherForecast/。

如果有需要額外客製化路由的話，只要修改 Route 標籤就可以了，例如：改成 Route("hello") 的話，就會變成 /hello/；那如果我們接著在 Function 上掛上 Route("world") 的話，該方法的路由就會變成 /hello/world/，以此類推。

接著我們繼續往下看，可以看到放了一列不同的天氣 string[] Summaries，還有一些屬性與使用依賴注入的建構子範例 WeatherForecastController()，這個部份我們在後續的章節會再說明。

在建構式之後，我們會看到 Get() 方法，方法名稱並沒有什麼太大的關係，這邊要注意的重點在於：上面也掛了 HttpGet 的屬性，這個部份用來制定我們該方法所對應的 HTTP Method，也就是我們前面 Restful 小節提過的「符合 HTTP 語意」所要處理的部分，例如 GET, POST 等等，就可以用 [HttpGet], [HttpPost] 等屬性來標示。

最後這個 Get() 方法會隨機丟回天氣跟氣溫。現在就讓我們實際來呼叫看看吧！

備註：由於本系列還沒教到使用 Postman 或 Thunder client 這類直接呼叫 API 的方便小工具，所以呼叫的部分會使用瀏覽器或命令列進行示範，已經會使用這類工具的朋友可以用自己順手的工具嘗試就好囉。

現在讓我們直接執行看看：

由於 Properties/launchSettings.json 裡有設定了 launchUrl 就是 weatherforecast，所以我們應該會直接看到它幫忙打開瀏覽器，並取得（GET）了 https://localhost:{yourIISPort}/weatherforecast 的結果：

小提示：如果瀏覽器打開沒有自動排版而是一整陀的朋友，可以先去裝個 JsonView 來保護眼睛。安裝前後差異可以參見 Json View —— 用 Chrome 打開 Json 的正確方式

那如果是要用 Powershell 呼叫 API 的朋友，可以使用 Invoke-RestMethod 來進行呼叫，再用 ConvertTo-Json 轉換成比較好讀的格式，例如：Invoke-RestMethod https://localhost:{yourIISPort}/weatherforecast | ConvertTo-Json。注意 yourIISPort 這兒是你啟動後的 port 號，像是 https://localhost:44304/weatherforecast。

備註：Linux 的朋友就直接使用 Curl 來打就行了唄。另外，上面的 Powershell 語法特別感謝這篇使用 PowerShell 呼叫 Web API 請求

到這邊我們就做完了簡單的認識，也確認我們新建的專案確實好好活著囉。

動手實作 CRUD

既然我們前面已經去逛過預設的 WeatherForecastController 了，現在就讓我們來自己建一個吧。

沒有脈絡就做不了事，先讓我們來訂一個情境：這是一個卡片對戰遊戲的卡片管理功能，一張卡片包含：卡片編號（ID）、卡片名稱和卡片敘述三個欄位。

因為我這個人喜歡整理、愛好整潔（？）這邊就先讓我們新增一個 Models 資料夾，用來存放卡片的類別

建立 Models 資料夾之後，在 Models 裡面新增 Card.cs：

現在應該會是這個樣子：

接著讓我們打開 Card.cs，加上卡片的各個欄位：

/// <summary>
/// 卡片
/// </summary>
public class Card
{
    /// <summary>
    /// 卡片編號
    /// </summary>
    public int Id { get; set; }

    /// <summary>
    /// 卡片名稱
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// 卡片描述
    /// </summary>
    public string Description { get; set; }
}

完成卡片類別的建立之後，讓我們前往 Controller，新建一個 CardController.cs：

我們打開 CardController.cs。這個類別裡面現在應該是空空如也：

public class CardController
{
    // 啥也沒有
}

接著我們就開始逐步施工吧（這邊的步驟可以去隔壁抄 WeatherForecastController.cs 也 OK 啦）

首先，我們要先繼承 ControllerBase 取得控制器該有的方法和成員。接著，我們要加上 [ApiController] 的屬性給這個類別，讓他知道他現在負責搞 API 了。

如果過程中跑出紅線的話，就按一下燈泡或用 Alt + Enter 把該 using 的東西給 using 進來。現在應該會像這樣：

[ApiController]
public class CardController : ControllerBase
{
    // 啥也沒有
}

接著讓我們加上 Route，因為我們按照資源下去設計的話，Route 多半也是 /card 這樣子的路徑，因此我們繼續使用 [Route("[controller]")] 就可以了。如果各位要做的 API 資源在這邊需要客製化，再自己改成想要的字串即可。

[ApiController]
[Route("[controller]")]
public class CardController : ControllerBase
{
    // 啥也沒有
}

這邊就讓我們先建立一個 static 並且為空的 IEnumerable<Card> 的私有成員，用來驗證我們後續開的功能是否可以正常運作

備註：我們會在下一個章節把這部分更改為連線資料庫去變更真正的資料，這邊就先用私有成員假裝一下唄。

[ApiController]
[Route("[controller]")]
public class CardController : ControllerBase
{
    /// <summary>
    /// 測試用的資料集合
    /// </summary>
    private static List<Card> _cards = new List<Card>();
}

這樣事前工作已經準備完畢了，讓我們來加上操作方法吧！

首先先來一個查詢所有卡片的 Function，同樣用 [HttpGet] 來標明這是個 GET 方法，並且因為我們沒有特別指定路由，所以目前就是接著類別 CardController 的 /card，也就是 GET /card。

/// <summary>
/// 查詢卡片列表
/// </summary>
/// <returns></returns>
[HttpGet]
public List<Card> GetList()
{
    return _cards;
}

然後讓我們加上一個單獨查詢單張卡片的方法：

/// <summary>
/// 查詢卡片
/// </summary>
/// <param name="id">卡片編號</param>
/// <returns></returns>
[HttpGet]
[Route("{id}")]
public Card Get([FromRoute] int id)
{
    return _cards.FirstOrDefault(card => card.Id == id);
}

可以注意到我們用 Route 來指定了這個方法的 URL，並且用 {id} 的方式告訴 API 說這一格是參數 int id 所在的位置。

這樣的話這個方法的 Route 就會變成 GET /card/1（查詢 ID 為 1 的卡片）這種感覺。實際使用的時候我們會很經常用 {參數} 這種方法來把參數加入到 Route 並制定 Function 對應的 URL，以此達到符合 Restful 的感覺。

另一個可以注意到的地方是我們在 Function 的參數上加上了 [FromRoute] 的屬性來告訴 API 說 int id 這個參數是來自於 Route 上的。

除了 FromRoute 以外，還有 GET 時很常用到的 [FromQuery] 或舊版本的 [FromUri]（指這個參數從 QueryString 也就是 ?a=1&b=2 那串裡面接收）、POST 和其他狀況常用到的 [FromBody]（指這個參數要從 Body 接收）等等，可以讓我們標明參數的來源。

補充說明一下，雖然也有簡單型別預設從 Uri，複雜型別預設從 Body 等等貼心的設定，但個人認為還是盡量都標明出來，對自己和後續維護的人都會比較好一點…。

接著讓我們加入新增卡片，還有編輯卡片的方法吧，在這之前我們先建立一個 Parameter 資料夾，用來放一些傳入的參數，並且新增一個 CardParameter 來當作我們新增和修改卡片的參數類別：

/// <summary>
/// 卡片參數
/// </summary>
public class CardParameter
{
    /// <summary>
    /// 卡片名稱
    /// </summary>
    public string Name { get; set; }

    /// <summary>
    /// 卡片描述
    /// </summary>
    public string Description { get; set; }
}

補充：雖然也有建立一個對應的類別，接著就只使用這個類別的作法，像是先前的 Asp.net MVC，我們就只使用一個對應資料表欄位的類別來完成 CRUD 全部的操作。放到這裡來說的話，也就是只用 Card 類別，查詢也是用這個類別顯示，更新也是用這個類別當作參數。

但有些情況的時候，我們會希望傳進來新增或修改的參數跟類別並不一致，例如當我們新增 Card 的時候，並不需要 Id 這個欄位；又或是有些資料表中有 CreateTime、UpdateTime 這類程式自動填入、顯示的時候才有意義的欄位，就不會在新增或更新的時候對外開放；又或者是分層架構這類每一層要求的欄位並不一樣的情況等等。這些時候，我們就會採取將參數，也就是 Parameter 切分成一個單獨的類別進行管控。

基本上就像即使是同一張表，我們也會根據顯示的狀況來製作成不同的 ViewModel 一樣，我們也會根據傳入的狀況來決定 Parameter 的範圍。這個部份我們會在分層架構的時候再介紹一次，現在只要大致有可以把「顯示用類別」和「參數用類別」拆成不同的類別來進行出入口管制的概念就可以。

建立完參數之後，我們就可以回到 CardController 來加上新增和更新的方法：

/// <summary>
/// 新增卡片
/// </summary>
/// <param name="parameter">卡片參數</param>
/// <returns></returns>
[HttpPost]
public IActionResult Insert([FromBody] CardParameter parameter)
{
    _cards.Add(new Card
    {
        Id = _cards.Any() 
          ? _cards.Max(card => card.Id) + 1
          : 0, // 臨時防呆，如果沒東西就從 0 開始
        Name = parameter.Name,
        Description = parameter.Description
    });

    return Ok();
}

/// <summary>
/// 更新卡片
/// </summary>
/// <param name="id">卡片編號</param>
/// <param name="parameter">卡片參數</param>
/// <returns></returns>
[HttpPut]
[Route("{id}")]
public IActionResult Update(
    [FromRoute] int id,
    [FromBody] CardParameter parameter)
{
    var targetCard = _cards.FirstOrDefault(card => card.Id == id);
    if (targetCard is null)
    {
        return NotFound();
    }

    targetCard.Name = parameter.Name;
    targetCard.Description = parameter.Description;

    return Ok();
}

這邊的 [HttpPost]、[HttpPut] 以及 [FromRpute]、[FromBody] 我們在前面都已經掌握了。但在這裡我們還是可以看到 return Ok() 和 return NotFound() 這兩個新朋友。

聰明的朋友看 return 的方法名稱應該已經猜到了，這就是我們前面提過的 HTTP Status。當然前面查詢成功的時候和這邊的 Ok() 一樣是 200 的狀態，此外還有代表 400 的 BadRequest()、代表 404 的 NotFound() 等等。

除此之外，我們也不是每次都會回傳 IActionResult，可能也會是自訂的錯誤型別等等，所以也看過使用 Response.StatusCode 來直接設定 Http Status Code 的做法，例如 Response.StatusCode = 200; 之後再進行回傳的做法，各位再視情況使用吧。

現在 CRUD 四大天王，我們已經只剩下 D 了，現在就來把刪除卡片的方法補上吧：

/// <summary>
/// 刪除卡片
/// </summary>
/// <param name="id">卡片編號</param>
/// <returns></returns>
[HttpDelete]
[Route("{id}")]
public IActionResult Delete([FromRoute] int id)
{
    _cards.RemoveAll(card => card.Id == id);
    return Ok();
}

這樣四大天王（包含查詢列表通常是五個）就到齊了，現在的 CardController 應該是長這樣的：

[ApiController]
[Route("[controller]")]
public class CardController : ControllerBase
{
    /// <summary>
    /// 測試用的資料集合
    /// </summary>
    private static List<Card> _cards = new List<Card>();

    /// <summary>
    /// 查詢卡片列表
    /// </summary>
    /// <returns></returns>
    [HttpGet]
    public List<Card> GetList()
    {
        return _cards;
    }

    /// <summary>
    /// 查詢卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <returns></returns>
    [HttpGet]
    [Route("{id}")]
    public Card Get([FromRoute] int id)
    {
        return _cards.FirstOrDefault(card => card.Id == id);
    }

    /// <summary>
    /// 新增卡片
    /// </summary>
    /// <param name="parameter">卡片參數</param>
    /// <returns></returns>
    [HttpPost]
    public IActionResult Insert([FromBody] CardParameter parameter)
    {
        _cards.Add(new Card
        {
            Id = _cards.Any() 
                ? _cards.Max(card => card.Id) + 1
                : 0, // 臨時防呆，如果沒東西就從 0 開始
            Name = parameter.Name,
            Description = parameter.Description
        });

        return Ok();
    }

    /// <summary>
    /// 更新卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <param name="parameter">卡片參數</param>
    /// <returns></returns>
    [HttpPut]
    [Route("{id}")]
    public IActionResult Update(
        [FromRoute] int id,
        [FromBody] CardParameter parameter)
    {
        var targetCard = _cards.FirstOrDefault(card => card.Id == id);
        if (targetCard is null)
        {
            return NotFound();
        }

        targetCard.Name = parameter.Name;
        targetCard.Description = parameter.Description;

        return Ok();
    }

    /// <summary>
    /// 刪除卡片
    /// </summary>
    /// <param name="id">卡片編號</param>
    /// <returns></returns>
    [HttpDelete]
    [Route("{id}")]
    public IActionResult Delete([FromRoute] int id)
    {
        _cards.RemoveAll(card => card.Id == id);
        return Ok();
    }
}

最後讓我們啟動來測試一下吧！

備註：和上面同樣地，因為這邊還沒說明到 Postman 等測試軟體，所以直接使用 Powershell 進行示範，已經有慣用軟體，或是直接寫一個腳本出來接的朋友，請用自己方便順手的測試方法去呼叫就好囉。

讓我們打開 Powershell，繼續使用 Invoke-RestMethod 來呼叫 API 試試看，別忘了 Port 要換成你啟動專案時 IIS 掛上去的 Port

首先讓我們新增一張卡片：

Invoke-RestMethod https://localhost:44304/card `
 -Method 'POST' `
 -Headers @{ "Content-Type" = "application/json"; } `
 -Body "{`"name`": `"mycard`",`"description`": `"sample card`"}"

接著讓我們查詢看看所有卡片，看看新增的卡片在不在：

Invoke-RestMethod https://localhost:44304/card | ConvertTo-Json

既然卡片已經存在了，讓我們試試看編輯，把「我的卡片」改成「我們的卡片」，~~打倒富農份子~~：

Invoke-RestMethod https://localhost:44304/card/0 `
 -Method 'PUT' `
 -Headers @{ "Content-Type" = "application/json"; } `
 -Body "{`"name`": `"ourcard`",`"description`": `"sample card`"}"

並且用查詢單張卡片的方式來查詢卡片資料：

Invoke-RestMethod https://localhost:44304/card/0 | ConvertTo-Json

如果編輯的卡片不存在，會噴出 404：

最後讓我們來試試刪除：

Invoke-RestMethod https://localhost:44304/card/0 `
 -Method 'DELETE'

然後同樣使用查詢全部，應該要沒有任何卡片了：

Invoke-RestMethod https://localhost:44304/card | ConvertTo-Json

到這邊就確認我們的 API 服務（也就是基本的 CRUD）已經 ON 起來啦！

小結

這邊我們紀錄了一些會用到的 HTTP 基礎知識，並用 Asp.net Core 的 Web API 範本新建了一個 API 服務，也加入了自己設定的 CRUD。

但要特別注意，雖然我們對外的開口已經建起來了，但這時候的 Card 還只是個用 static 變數假裝的空殼，只要站台重啟就會消失了。

正所謂「沒有連到資料庫的 CRUD，就像是沒有加醬汁的料理！」，我們在下一集就要來把我們的 Api 服務連接到資料庫啦！

那麼，我們下次見～

2021.05.08 補充：

範本預設的 WeatherForecast.cs 和 WeatherForecastController 在將來的文章將不會再用到，繼續下一篇實作之前可以先刪除囉～

有刪除的朋友記得要去 launchSettings.json 把 launchUrl 改成 card，下次啟動才會直接到我們這次新加的 CardController 呦！

本系列下一篇：菜雞新訓記 (3): 使用 Dapper 來連線到資料庫 CRUD 吧

本系列文章

參考資料

Visual Studio: 在同一個檔案分割視窗

Igouist (Igouist) — Sun, 02 May 2021 10:00:00 +0800

當我們遇到比阿嬤的裹腳布還臭還長的類別時，常常會發生「需要一邊確認 Public 的 Function，但它用到的 Private Function 卻遠在天邊」，或是「SQL 字串／字串常數等等另外宣告在檔案最上端，導致瀏覽邏輯到一半的時候還要來回跳」的狀況。

在上一篇我們分享過用書籤的方式來記錄兩個地方來回飛躍，但如果是要互相比對或理解流程等等時候，就比不上分割視窗來的方便。

在 Visual Studio 用分割視窗的方式開啟不同的檔案，相信大家都已經駕輕就熟，尤其用過 Visual Studio 來進行 Merge 的朋友一定對這樣的排版不陌生。但是你知道就算對同一個檔案，也可以使用分割視窗來同時編輯兩個地方嗎？只需要動動滑鼠就可以囉！

我們只需要將滑鼠移到卷軸上…

就成功分割出來啦！

接著只要使用 F6 就可以在兩個視窗之間切換，同時編輯同個檔案的兩個地方囉！

這邊也分享給大家，下次遇到這些狀況就試試唄！

~~謝謝把連到資料表的 Function 裡的 SQL 語法丟到地球彼端的前輩，讓我必須找這種技巧來用~~

菜雞新訓記 (1): 使用 Git 來進行版本控制吧

Igouist (Igouist) — Mon, 05 Apr 2021 22:39:01 +0800

這是俺整理公司新訓內容的第一篇文章，目標是整理 Git 相關的筆記。

章節目錄

前言、推薦資源

說來慚愧，前陣子 PTT 和臉書社團都有討論到相關科系畢業卻不會 Git 會不會太誇張，我正是畢業之後才開始用 Git 的那類人囧，相信像我一樣的人並不少，因此這個系列就決定從「新訓時學到的 Git 的基本操作」開始記錄。

開始之前先感謝公司前輩和完善的新手教學，還有第一天就先學 Git 的優良傳統。另外，也感謝相當多優秀的 Git 學習資源，說明得也更為詳細深入，想好好了解 Git 的朋友也可以逛逛，這邊就先推薦一波：

為你自己學 Git
- 對新手非常友善。網站點進去後往下拉，可以看到大部分章節都能免費看，佛！
- 最有價值的是裡面的各種狀況題。畢竟當你用 Git 不只需要基本操作的時候，呃，祝你好運
連猴子都能懂的 Git 入門指南
- 從入門到進階篇跟過一次的話，基本操作就沒有問題了
- 圖解讓人很好理解，而且在教學的實作部分會提供儲存庫讓你下載實作
黑暗執行緒的 Git 分類文章
- 同場加映：黑暗執行緒的 Git 指令筆記
- 黑大出品，品質保證
Learn Git Branching
- 用遊戲通關的方式認識 Git，對於一些分支的概念會很有幫助
30 天精通 Git 版本控管
Pro Git

接下來我們就從認識 Git 開始吧！

什麼是 Git？

你發生過以下狀況嗎？

從沒做過版本控制，結果突然要改回前一版，不知所措
使用資料夾／壓縮檔板控
- 20201201.rar, 20201215_v2.rar, 20201215_首頁.rar……
- 空間越吃越兇，東西越來越雜，事情越想越不對勁，但是不敢刪除
- 其實不知道每一份實際上改了哪裡，要復原某一段的時候要找半天，不如直接重寫一段
團隊合作／分組報告，各自負責一個區域，結果複製來複製去組不起來，不只需要看眼科，修 BUG 還比寫的時間還多
看到一段程式碼
- 完全不知道為什麼要這樣寫
- 或是氣到要死，抓不到戰犯

那麼，你很有可能需要 Git！

Git 是一套分散式的版本控制，就像是打電動時的存檔。讓我們可以在面臨重要選擇的時候存檔、打王之前存檔、打贏的時候也存個檔。當然，像是那種有多劇情多結局的遊戲，也可以針對不同路線各自存檔。

同時它也支援雲端存檔，你可以在電腦上存個檔，然後有網路的時候就丟上去雲端備份一下。而這個雲端備份是共用的，所以你可以跟朋友一起玩同一款遊戲，各自攻略不同的 BOSS，再把存檔和朋友互相交流交流，合成一個有兩份戰利品的存檔。

這些功能在 Git 有著聽起來比較厲害的名字，例如認可（Commit）、分支（Branch）、分散式、合併（Merge）等等。我們後續再慢慢了解它們。

什麼是分散式版本控制？

現在我們已經有個大致上的印象了，但 Git 還有更多特色，例如：

免費！開源！
讀檔存檔的速度很快！
分散式！

前面兩項比較好理解，我們這邊說明一下什麼是「分散式」的版本控制：

以前的版本控制，例如 SVM，是採用「集中式」的版本控制：每次變更完要存個檔等等，都要連線到伺服器上進行處理，就像是好幾個人一起連線存取同一張資料表一樣。但是這樣遇到沒有網路的狀況就沒辦法讀檔存檔，或是變更的檔案很大就會等到天荒地老，這種對伺服器強依賴的狀況實在是有點兒不方便。

分散式版本控制呢，則是每個人都有各自的完整一份資料，你要存檔讀檔啥的都你自己電腦上弄就好了，只有必須和其他人交流的情況（例如想丟上去雲端存檔了，寫完了要合併了）才需要透過網路來處理，這樣子日常做事起來就快上不少。

也因為每個人都有一份，某台機器掛掉就導致整份程式碼不見的狀況少了很多，變更歷史也不容易竄改。同時更發展出強大的分支操作，和一些工作流程等等，是相當靈活的版本控制方式。

關於版本控制方式的比較也可以參考這兩則文章：

現在我們知道了 Git 是一個分散式的版本控制軟體，幫助我們做一些存檔讀檔同步的動作。接著就讓我們開始來操作看看吧！

先告訴 Git 我們是誰

小提示：你可能需要先安裝 Git。
安裝過程相當簡單，通常只需要下一步即可。

首先我們得先確認 Git 已經準備好了，打開我們的命令視窗（Powershell 或是 CMD 之類的），輸入 git --version，你應該能夠看見 Git 的版本資訊

另外，也可以輸入 git --help 來查詢可用的指令。或是加上想用的指令，例如 git --help clone 就會開啟該指令的文檔，臨時要確認指令和參數的時候相當有用。

Git 現在已經有相當多的 GUI 可以使用，真的很多。我個人在家的時候是使用 GitHub Desktop、在公司大多時候使用 Visual Studio 內建的 Git 工具。此外，也見過朋友和同事使用 GitKraken、Fork 等等。關於這些 Git 的 GUI，可以參考官方整理的 GUI Clients 頁面。

但由於我個人忘記指令的狀況頗為嚴重，而且也不是每個環境都有 GUI 可以用。因此這篇有關 Git 的部分將會以 CLI 指令為主進行紀錄。使用 GUI 介面的朋友也不用擔心，現在的介面都做得很精簡，~~而且這篇也寫得很淺，~~很簡單就能找到各指令對應的操作。

確認我們已經有 Git 之後，接著就必須先跟 Git 說我們是誰、信箱是什麼：

git config --global user.name "I am INEVITABL"
git config --global user.email "Thanos@Gemmai1.com"

這樣就會把設定好的名稱和信箱存到 config 裡面。如果要查看現在有的 config，可以輸入
git config --list

另外也還能指定編譯器、新增別名等等，可以參照其它方便的設定 - 為你自己學 Git

由於 Git 是用這組名稱和信箱進行辨別，因此在 Github 上就可以做一些很酷的事。例如假冒人家和防止人家假冒（？），有興趣的可以看看：用 Git 這麼久了，你知道 commit 是可以偽造的嗎

順便打個廣告：好奇我的 Powershell 長得跟你的「有點不一樣」的朋友，可以參考本部落格的另一篇：Powershell 美化作戰

建立一個新的儲存庫（Git Init）

現在讓我們從建立一個新的儲存庫開始。現在讓我們新增一個資料夾（在這邊我取名叫做 hello-git）當作這篇 Git 紀錄的遊樂場：

題外話：既然都打指令了，也可以試試來建立資料夾
Powershell 用 New-Item C:\hello-git -ItemType "directory"
隔壁棚 Linux 請用 mkdir 來試試。
不過基於懶惰，上面的示範是滑鼠右鍵建立的，耶嘿

接著讓我們先移動過去資料夾：

cd C:\hello-git

並且使用 git init 將 Git 初始化：

git init

如此一來，這個資料夾就成為了「工作區（Working directory）」，也就是「歸我 Git 管啦！」的意思

同時，我們也能在原本的 hello-git 資料夾中，發現多了一個 .git 的隱藏檔案：

這個 .git 就是用來幫我們處理一堆版本控制工作的地方，也叫做
「儲存庫（Repository）」。裡面會放一些設定值、已經確認變更的文件等等。

現在讓我們來確認一下這個工作區的狀況，git status 將會列出當前的狀態，這將會是我們很常使用的指令。

可以看到我們現在在 Master 分支，並且還沒有 Commit 任何東西。這兩個部分我們等等就會說明，現在就讓我們按照它的提示，來把檔案丟進去給 Git 試試吧。

把檔案加到 Git 的追蹤目標（Git Add）

我們先到 hello-git 資料夾裡，新增一個 A.txt

並且加入一些內容，例如「Hello!」

現在讓我們再次使用 git status 觀察一下

可以看到 Git 已經發現 A.txt 的存在了，但它也告訴我們，它還沒有把 A.txt 放在眼裡追蹤目標中

我們要用 git add 指令，Git 才會把這個變更納入這次的動作中：

git add A.txt

現在可以看到我們新增檔案這個動作已經被 Git 捕捉到了。

前面有提過，我們在 git init 之後，當下的資料夾就會變成「工作區」，而 .git 則會成為「儲存庫」。在這兩者之間，還會有一層「暫存區（Staging Area）」（有些朋友會叫做「索引區（index）」，對象是一樣的）。

這三者之間的工作流程就像是一條工廠輸送帶：

工作區（Working directory）→ 暫存區（Staging Area）→ 儲存庫（Repository）

而這個 add 加入檔案的過程，其實就是將我們 在工作區所做的變更，加入到暫存區（Staging Area）

所以我們新增檔案、變更內容等等，其實都要跟 Git 用 add 指令打聲招呼，說「我有動這個哦，幫我看著一下」，Git 才會把這些變更的對象放到暫存區裡，等待後續丟到儲存庫的動作。

那有些朋友可能就會問啦：我工作的時候處理的檔案一定很多個啊，每個都要 add 豈不是累死？

不用擔心，當有多個檔案要 add 的時候，我們可以加上參數 -A，也就是：

git add -A

或是

git add --all

這樣就會直接把所有變更抓進來囉。

當然，懶還要更懶，事實上現在的 GUI 工具，例如我接觸的 GitHub Desktop、Visual Studio 等等，其實都會自動幫忙 Add 了，真是貼心。

當我們把變更從工作區用 add 丟到暫存區之後，要怎麼再從暫存區丟進儲存庫呢？這時候就要使用 Commit 了！

提交變更（Git Commit）

完成了一項功能？　Commit！
解了一個ＢＵＧ？　Commit！
下班了？　Commit！
地震了？　Commit！

如果你有在使用 Git，Commit 絕對是你使用最多次的功能。當我們 Commit 之後，暫存區的變更就會寫入儲存庫，到這個步驟我們才真正地存檔成功。

現在讓我們來完成這次變更吧：

git commit -m "Add A.txt"

有看到 ~ file changed 就代表我們已經成功 Commit，把變更存進儲存庫囉！

Git Commit 的訊息該怎麼寫？

這邊要特別提的是 -m "Add A.txt" 這個部分。-m 就是 Message 的 m（好順口），是用來輸入本次 Commit 的訊息，雖然可以省略，但強烈建議 Commit 的時候都一定要加上訊息！

實際想想就能理解了，既然 Git 是可以讓你隨時存檔讀檔的工具，那麼假設你看到這一排存檔：

存檔
存檔
aaa
a

和這一排存檔：

結局選項前
結局選項１
結局選項２
決戰前

哪一組比較能快速知道要讀取哪個檔案呢？

Git Commit Message 也是一樣的道理。

好的訊息可以快速了解每個版本的變更和背後原因，甚至讓後續接手的人（通常也就是幾天或幾個月後的自己）能迅速地掌握狀況。因此現在大多數的 Git 工具都會要求必須輸入 Commit 訊息，畢竟「訊息一條勝造七級浮屠」，不可不慎哪。

因此，這邊強烈推薦這篇 Git Commit Message 這樣寫會更好，替專案引入規範與範例，內文用實際案例和 AngularJS 團隊的 Git Message 規範說明了好的 Message 該如何處理，相當清楚明瞭。

趁開始學習 Git 的時候就培養好的 Commit 習慣，將來一定都會派上用場。現在我也和同事一起嘗試著這套作法，畢竟通常救到的都是未來的自己嘛，哈哈。

關於 Commit Message 的部分，可以參照這幾篇呦：
。 Git Commit Message 這樣寫會更好，替專案引入規範與範例
。如何寫一個 Git Commit Message | louie_lu’s blog
。撰寫有效的 Git Commit Message
。 [學習筆記] 如何撰好的 Git Commit Message - Heidi’s Blog
看完之後也可以試著制定自己的格式，其實也蠻有趣的呢（當然還是要以方便順手為主啦～）

補充：如果不小心打錯 Commit Message 之類的怎麼辦？

像我這種錯字狂魔，幾乎兩三天就會打錯字就按下去。這時候我們就會需要 --amend！

可以參照：【狀況題】修改 Commit 紀錄 - 為你自己學 Git

Git Commit 的時機？

另外，除了 Commit Message 以外，Commit 的時機和頻率也是時常被討論的議題。

再度用存檔來比喻，大概就像你要讀檔的時候發現只有這兩個存檔：

新手村對話１
魔王城決戰

這下完蛋，如果什麼關鍵道具還是劇情沒有拿掉，要嘛放棄，要嘛認命從頭開始。所以，我們在 Commit 的時候要盡量迴避這個狀況。對此，我的建議是：

在所有你覺得「這是一個段落」的時候就 Commit。

就像這小節的開頭：完成了一個小功能？ Commit；重構了一個變數的命名？ Commit。在你所有想要 Commit 的時候 Commit，畢竟 Commit 不用錢，真的不用省。

寧可多 Commit 幾次，等熟練 Git 的時候，~~或是被靠夭洗版的時候~~，再考慮用 rebase 之類的技能來把多個零碎的 Commit 整理成一個；也不要臨時出了什麼事，結果 Git 一打開，只能回到一個月前，那真的是欲哭無淚。阿彌陀佛，保護自己，就從 Commit 開始。

如果你現在已經有整理 Commit 的需求，可以參照以下幾篇：
。【狀況題】修改 Commit 紀錄 - 為你自己學 Git
。送 PR 前，使用 Git rebase 來整理你的 commit 吧！ - 星巴哥技術專欄
。把多個 Commit 合併成一個 Commit - 為你自己學 Git

Git Commit 和 Add 的 Combo 技

讓我們延續一下 Add 章節的「懶還要更懶」，現在當我們完成一個變更，就要先 Add 到暫存區，再 Commit 到儲存庫。如果覺得這個兩步驟驗證很麻煩的話要怎麼辦呢？

其實可以使用 Combo 技，一次搞定 Add 和 Commit，那就是 -a，例如

git commit -a -m "Update A.txt"

但要注意這個招式只對已經在版本控制內的檔案有效，如果是新來的也還是要先去報到呦。

關於這段 工作區 -Add→ 暫存區 -Commit→ 儲存庫 的說明，也可以參見這篇為你自己學 Git 的工作區、暫存區與儲存庫，裡面用倉庫和廣場的比喻個人覺得很貼切。

加入 .gitignore 來忽略指定檔案

如果你跟我一樣，總是 add -a 無差別加入，或是 GUI 的一鍵 Commit 用太爽，很容易就會翻車。怎麼個翻車法呢？我在新訓的時候就有被問過：

「你把這推上來幹嘛？？？」

沒錯！有些東西我們是不需要加到版本控制中的，例如每次編譯都會產生的檔案（像是 .net 的 bin 資料夾之類的）、機密檔案、個人對編譯器的設定檔等等。

有些東西加入版本控制後，輕則讓你的 Git status 變得很雜亂、Commit 變得亂七八糟，重則影響到其他人的環境。因此我們要想辦法，讓這些東西不要加入版本控制裡。

這時候我們就可以加入 Git Igonre 來讓 Git 忽略這些東西。

現在讓我們來試試看，先新增一個 Ignoreme.txt 檔案，接著再新增一個 .gitignore：

然後在 .gitignore 中加上：

ignoreme.txt

接著，讓我們再次呼叫　git status 確認當前的狀態

可以發現居然只有剛剛新增的 .gitignore，Git 真的就裝作沒看到 Ignoreme.txt 了！

藉由 .gitignore 我們就能讓 Git 知道哪些檔案它不要亂插手，通常來說每個專案底下都會有一個共用的 .gitignore 檔案，避免某些人沒跟到就把不該推的東西給推上去了。

至於哪些東西不該推呢，東西這麼多怎麼列得完呢？感謝社群，github/gitignore 這兒都已經整理好了。就算裡面找不到的，只要 Google “你的語言或框架 + gitignore” 通常都會有結果，例如 dotnet-ignore，我們菜雞只要爽爽用，

最後別忘了讓我們也把 .gitigonre 也 Add 到我們的 Git 之中，並且 Commit 起來：

查詢 Commit 紀錄（Git Log）

現在我們已經可以成功存檔了，但有玩過遊戲的都知道，通常都會有個地方讓你看當前的存檔和紀錄等等。那麼在 Git 中要怎麼看我們的 Commit 記錄呢？這時候就要用到 log 指令。

由於只有存過一次也太寒酸了，現在讓我們把 A.txt 打開，將原本的 Hello! 改成 Hello world! 並且再 Commit 一次：

然後，讓我們試試 git log：

就可以看到我們前面的 Commit 內容囉！

小提示：如果 Log 太多頁的話，可以用空白鍵前往下一頁、按 q 離開。 Git 的操作使用的是 Less，關於常用的操作方式可以參考 Less (Unix) #Frequently used commands

每次的 Commit 資訊通常會包含：

作者
日期
Commit Messaage
Commit 用 SHA-1 計算出來的識別碼，可以當成是這個 Commit 的唯一 ID、身分證編號就行了
分支所在的 Commit
- HEAD 是指向我們當前所在的分支，而我們 HEAD 所在的 master 分支則是在 743d… 這個 Commit 上
- 關於 HEAD 我們會在 Git 的 head 是什麼繼續說明
- 關於分支我們會在 Git 的分支（branch）是什麼繼續說明

題外話：如果有朋友在 windows 上，例如 powershell 使用 git log 或 git 相關指令有出現中文亂碼的情形，可以參考以下的語法進行調整：
git config --global core.quotepath false         # 引用路徑的檔案名稱
git config --global gui.encoding utf-8           # GUI 編碼
git config --global i18n.commit.encoding utf-8   # Commit 編碼
git config --global i18n.logoutputencoding utf-8 # Log 編碼
$env:LESSCHARSET='utf-8'                         # Less 分頁的環境變數
其中環境變數需要直接前往 系統內容 > 進階 > 環境變數 並新增到系統變數上，否則每次重開 powershell 都要重打一次。

主要是因為一些歷史原因，Windows 在這塊並沒有全面支持 Utf-8，因此需要告訴 Git 我們要以 utf-8 作為編碼，並且也把 Git 用到的 Less 分頁等環境變數設定好。感謝 CSDN 的這篇 PowerShell | git log 中文亂碼問題解決和 Github 上的 Nightire 大大。

但是如果你是在 Windows 也要安裝 Ubuntu，我就是要 Bashhhhh 的朋友就當我沒說。

不過比起這樣的文字，我們比較常用的還是 Git 那相當有特色的線圖。現在讓我們試試
git log --oneline --graph：

可以看到 Log 變得相當精簡了。在我們後續會講到的分支情景下，線圖還會幫忙畫出不同分支路線（平常有使用 Git 的 GUI 工具的朋友們應該都很熟悉了）

這邊就借朋友的 Project 示範一下：

除了直接看線圖以外，git log 也提供了相當多的參數可以運用，例如說可以用 --committer 來找某個人的 Commit、用 -S 尋找主旨等等、用 -2 來限制只看兩筆等等，其他像是搜尋某個時間區段、某個特定檔案的變更紀錄也可以做到，甚至可以用 --pretty 來自訂 log 要顯示的格式，基本上該有的功能都有。

通常 git log 最常見的場景大概就像這樣：

「Ｘ！這鬼東西誰寫的？？？」
git log ShitCodeController.cs
「噢，是我啊…」

這部份有興趣的朋友可以參考以下兩篇的說明，尤其是為你自己學 Git 這篇裡面的狀況題相當實用，每天抓戰犯（？）的時候都會用到：

掌握 git log，每天都可以更刺激有趣！

查詢兩個 Commit 之間的差異（Git Diff）

有些朋友可能會問：「我知道每一次 Commit 了，但我還是不知道每個 Commit 到底動了哪些地方呀？」

或是更進一步的：「我知道可以用 git log -p 來看每次 Commit 的內容啦，也知道變動了哪些地方應該要直接能從 Commit Message 大致看出來啦。但 log 的雜訊太多了，我只想要確切知道兩個 Commit 間到底變動了哪些，該怎麼做？」

這時候我們就可以使用 git diff 來看兩個 Commit 之間的差異。

現在讓我們回到 git log 示範時的狀況：

可以看到我們有三個 Commit，分別是 a657, 6fbe, 2b33

小提示：在告訴 git 某個 Commit 的 SHA1 值的時候，並不需要完整打完，只要到可區分的程度就可以了，畢竟這東西真的超級難重複嘛。如果 Git 分不出來，就會請你再打一次，不用擔心。

接著讓我們輸入 git diff a657 6fbe （請根據你的 Commit SHA1 值輸入）

就可以看到這兩個 Commit 間差異的內容囉！像是從上面的圖中，我們就可以知道 A.txt 有被修改過，其中被移除了 Hello 這一行，同時新增了 Hello World! 這一行。

除了兩個 Commit 之間以外，git diff 也可以查看兩個分支間的差異。

我們前面有提到過每次 Commit 的流程是工作區＞暫存區＞儲存庫，那如果我們現在要看工作區和儲存庫之間的差異，也就是「我們現在變更了什麼」該怎麼做呢？

現在讓我們把 A.txt 的 Hello World! 的驚嘆號改成句號（可能我們不想那麼激動，想冷靜一點），但先不要 Commit：

接著讓我們用 git status 確認一下：

可以看到工作區已經有變更了，但我們尚未 add 到暫存區裡。

現在讓我們使用 git diff 指令來看工作區和儲存庫間的差異：

能看到 Hello World! 和 Hello World. 的差異有確實出現。平時就可以用 git diff 來看這次到底都改了些什麼。

現在我們試試看先用 git -add A.txt，把 A.txt 加入到暫存中，再呼叫 git diff 試試：

卻發現沒有找到任何差異了！這是因為 A.txt 已經被收入到暫存區中，不在工作區了。如果我們要確認暫存區和儲存庫之間的差異，要加上 --cached 參數，現在再用 git diff --cached 試試：

就可以看到暫存區和儲存庫之間的差異囉。

最後，示範完了就養成好習慣，順便 Commit 來結束這一小節吧：

git diff 的使用場景相當簡單，最常用來確認版本間的差異，或是檢查當前變更的內容。雖然 Diff 常常跑出來落落長一大串，不過現在的 GUI 都做得相當一目了然了：

如果手癢要自製 diff 介面的朋友也可以參考黑大的這篇 Git 筆記 - 產生程式異動對照表(Compare List)。

另外，如果一次 Commit 包含的檔案太多，也可以像 got log 一樣加上檔名來比較單一檔案的差異，或是使用 --stat 來檢視簡單的變動檔案列表等等。

diff 相關的文章也可以參照這幾篇，也是本節的主要參考資料：

但是每次 diff 的時候，我都還要查出兩個版本的 SHA1 碼，如果我只是要看這一版和前一版的差異，這麼簡單的場景卻要弄得那麼複雜，不是很麻煩嗎？這時候我們就可以借助 HEAD 的力量，讓語法變得更簡單！

Git 的 HEAD 是什麼？

從上面的許多操作中，例如顯示 Commit Log 時，都可以看到 HEAD 這個關鍵字，例如 (HEAD -> master)。

HEAD 基本上可以當作「目前位置」的概念，它是一個會指向當前分支的指標。

通常來說，HEAD 會指向目前所在的分支最新的一個 Commit（除非發生斷頭）。

但由於我們還沒有認識分支，當然也沒有針對分支進行任何操作，因此 HEAD 就會指向我們的預設分支 master（Github 現在改叫做 main 了），所以現在直接把 HEAD 當成目前所在位置就可以了。

同時，也可以用 HEAD 搭配 ^（上一個版本）、~（上幾個版本）來直接替代大多數需要給定 Commit SHA1 值的操作，例如說：

HEAD~5 = 目前位置往前五步
f74d^ = f74d 這個 Commit 的上一個 Commit

這樣會讓整個 Git 指令操作變得相當簡便，當我們在 git diff 的時候，明明只是要看跟上一版或者前面幾版的差異，實在很不想再查 SHA1 碼，就可以用 git diff HEAD HEAD^ 或是 git diff HEAD HEAD~2 的指令來加快查詢。

關於 HEAD 的延伸閱讀，可以參考這兩篇：

Git Revert：讓我們往回走一步

「以前我沒得選，現在我想做個好人。」

『好啊，去跟 Git 說，看他讓不讓你做好人』

既然我們已經學會存檔，也能看過去都存了哪些檔了，是時候該學學讀檔了吧！

大多數的遊戲都有「上一步」、「悔棋」、「恢復上一動！懷疑啊？」這類的動作，在 Git 中則是叫做 Revert。

不過比起「我這一步完全不算」，Revert 比較像是「我再把棋子移回去就是了」的概念。也就是說，雖然是悔棋，但是這個悔棋本身也算是一步的意思。

這個部份直接試看看會比較好了解，讓我們把 A.txt 打開，並且把內容改成

Hello world. HAHAHA.

緊接著直接 Commit -a -m "HAHA"，現在的 Git Log 應該會長得像這樣：

然後可能我們去吃個飯，越想越不對勁，回來決定不要這次 Commit 了。

現在讓我們試試 Revert：

git revert HEAD  --no-edit

接著再確認一次 Log：

可以看到又多了一個 Commit，這個 Commit 用來撤回前一個 Commit。

並且 A.txt 也變回沒有 HAHA 的版本囉。

補充：我們在前面 Revert 的時候，加上了 –no-edit 的參數，讓 Git 自動使用預設的 Revert 訊息去 Commit。

大多時候，Revert “XXX” 就很清楚表達要撤回這個 Commit 的意思了。但如果這次撤回有需要另外說明的部分，可以不加上 –no-edit 參數，會進入 Commit Message 的編輯頁面，包含這個 Commit 的變動內容，讓你輸入這次 Revert 的 Commit Message。輸入完之後就可以提交囉。

如果你是誤入 Vim 的朋友，呃，保佑你能順利 :wq。跟我一樣認命看為你自己學 Git 的超簡明 Vim 操作介紹吧，畢竟這是大多數人的必踩之坑…

如果突然又不想撤回了怎麼辦？你可以再 Revert 一次來 Revert 掉上個 Revert 藉此還原上個 Revert 所 Revert 掉的 Commit，夠直覺吧！

「我識破你的識破！」—— 某風聲（桌遊）玩家

那如果並不是要 Revert 這種後悔一步的作法，不想要背負 Revert 的 Commit，而是想要重新出發，該怎麼辦呢？

這時候就要用 Reset 了。

Git Reset：讓我們搭上時光機

「要是能重來，我要選李白。幾百年前寫的 Bug 沒那麼多人幹」

Reset 的意思是 把當前的位置 Reset 到新的位置，就像時光機一樣，直接前往目標 Commit。

用起來有點像 Git 界的 goto 的感覺，現在就讓我們直接試試吧。

首先掌握一下狀況，現在我們的 Log 是這個樣子：

然後 A.txt 裡面則是：

現在假設我們想要取消前面對 A.txt 中 Hello 的所有操作，也就是回到還沒有做 a657 fix: 修正 hello 為 hello world 這個 Commit 之前。

我們可以從 git log 中看見還沒做 a657 的前一個 Commit 是 6fbe Add gitignore，或是我們也可以直接用 a657^ 來直接指定 a657 的前一個 Commit。先讓我們用 diff 偷看一下目的地和當前的差異。

可以看到 A.txt 的在當時的內容是 Hello!，這就是我們要的。這時候我們就可以使用 reset

git reset --hard a657^

Git 跟我們說「你已經回到了 6fbe 這個 Commit 囉」接著讓我們確認看看 A.txt：

的確也變回去了，大功告成。

眼尖的朋友應該已經發現了，我們在 reset 的時候，加上了 --hard 的參數，這是什麼意思呢？其實 reset 有分為三種模式：

Mixed：保留工作區，不保留暫存區。沒有選模式的時候預設就是用 Mixed
Soft：保留工作區，也保留暫存區。感覺會像是只是把 HEAD 往前移而已
Hard：不保留工作區，也不保留索引區
- 也就是所有變更都直接捨棄，完整地回到當時

用現在這個例子來說，我們知道 A.txt 的舊版會是 Hello!，新版會是 Hello world.，那麼這三個模式下就會變成：

Mixed：A.txt 會是 Hello world. 但還沒有 Add 的狀態
Soft：A.txt 會是 Hello world. 並且已經 Add 等待 Commit 的狀態
Hard：A.txt 會是 Hello!

這三個模式可以用在不同的場景，例如說：

當我只是想要重新編輯 Commit Message，或是想要整理某些部分的 Code，就可以用 Mixed 或 Soft
當我發現一些東西不應該 Add 進去 Git 版控，就可以用 Mixed
當我打算把這整組 Commit 放生，什麼都不要了，只想著回到當時狀況，就可以用 hard

等等這種情景，再自己取捨一下要用哪種時空旅行方法囉。

關於 reset 和這三個模式，為你自己學 Git 的表格整理得很不錯。這邊加上延伸閱讀（其實就是為你自己學 Git 的 Revert, Reset 系列文）：

題外話：如果真的遇到要把目前的 Commit 整條捨棄回到某個時間點的狀況，建議還是用後面學到的分支，把不要的 Commit 先拉出一條分支留著一陣子。

經歷過一些已經宣告死刑的需求過陣子借屍還魂死灰復燃的神奇操作之後，真的會感謝 Git 救工程師於水火之中。阿彌陀佛。

補充：在 reset 的時候真的會強烈感覺到 Commit 的頻率和 Commit Message 的重要，想想前面 Commit 章節的那兩個例子：

如果只有「專案初始化」、「功能完成」兩個 Commit，那就算 reset 也無用武之地，如果 Commit 訊息一整排都是「Add」、「Add」、「Add」，那給你 reset 也不知道該往哪裡去。

所以切記切記，魔鬼藏在 Commit 裡！

Git 的分支（Branch）是什麼？

就算是超級英雄片也會有團隊合作各司其職的時候，程式開發上一定也會遇到多人合作的狀況，這時候我們就不能一路無腦 Commit 下去。

像是分組作業的時候，通常都會溝通好每個人負責的地方，最後再銜接起來；又或是要前往目的地的時候，可以大家各自約好用不同的方法前往，在目的地會合。在 Git 中，我們可以使用分支（Branch）的方式來達到一樣的效果。例如說，多個人的時候就會變成：

小明拉了Ａ分支負責開發甲功能
小華拉了Ｂ分支負責修復出問題的乙功能
小美拉了Ｃ分支負責開發另一個專案的丙功能

最後再進行合併。

就算是只有一個人開發，有時候也會遇到正在開發某一個功能的時候，發現其他功能的某個地方壞了，又不想混在一起做。這時候也可以用分支進行管理。

這個部份我推薦連猴子都能懂的 Git 指南中的什麼是分支？這頁的圖例，可以看到各自開發不同功能之後，合併在一起取得有全部變更的網頁。

分支在大多範例中會被形容像是樹枝的分枝，從主幹發散出去。但我個人覺得比較像是水流，從任何一處我們都可以岔分出另一條水流，這兩條水流各自經歷了不同的地方，可能第一條水流帶來了泥沙，第二條河流被汙染了核廢料，而我們又能將這兩條水流會合在一起，得到同時有泥沙和核廢料的水流。

而個人認為，分支最重要的概念就是進行環境的隔離，大家可以在自己的分支上進行作業，又不會互相影響。就算想修改看看，也可以在自己的分支上先行測試，沒問題了再合併上去，這樣就能在工作流程上貫徹封裝、降耦合和單一職責的精神。並且，也因為多條分支可以同時進行不同的工作，也能達到平行處理般的效率，重要的是戰犯更好找了，豈不妙哉。

那麼，我們現在就來記錄一下分支的基本操作吧。

新建分支（branch）與切換分支（checkout）

我們在預設狀況下，就會位於 Master（有些地方是 Main）分支上，首先讓我們從新建分支與切換分支開始嘗試。在 hello-git 中，新增兩個檔案：B.txt 和 C.txt，現在資料夾應該會是這個樣子：

接著將這兩個新檔案 Add 進來並且 Commit：

可以看到我們的 master 分支位於最新的 Commit 07672f4 上了，接著我們要從這裡
用 git branch 拉出一條新的分支：

git branch Branch-B

補充：分支拉出來的 Commit 點稱為 Base。由於任兩個 Branch 一定會找得到一個共同的 base，因此我們在對分支間做合併和比較時，並不是將整份拿出來做大量核對，而是從這個 Base 當作基準點來進行變更的比較。這個 base 的概念和我們後續的合併、衝突等操作會比較相關。

補充：如果建立分支的時候不小心取錯名字之類的，可以先偷看後面的查詢分支列表、刪除分支的小節。如果一切順利的話，我們後續在 ~~利用完分支~~ 跑完整個流程才會進行分支的刪除，請繼續看下去囉～

建立分支後，我們再使用 git checkout 簽出分支：

git checkout Branch-B

應該可以看到 Git 告訴你已經切換到 Branch-B 了，我們也可以用 git status 來進行確認：

題外話：用 branch 來建立新分支應該相當直覺，但為什麼是用 checkout 來切換分支呢？

這是因為在 Git 的觀念中，比較像是「在圖書館的櫃台，我們去借出某一本指定的書，完事後再歸還回去」這樣的概念，因此我們才會使用 checkout 簽出的方式來取出我們要的分支。

確認我們現在是在 Branch-B 分支之後，現在請把 B.txt 刪除，並且 Commit：

接著，讓我們切換回 Master 分支：

git checkout master

觀察一下，B.txt 是不是復活了？

現在我們可以再練習一次：新建一條 Branch-C 並簽出，並且刪除 C.txt 後 Commit。

如果覺得每次都要先新建分支，再跳過去做兩步很麻煩的朋友，可以試試 git checkout -b Branch-C，就可以在簽出的同時建立分支囉。

接著移除 C.txt 之後 Commit：

現在，可以試著用 checkout 在 Branch-B 和 Branch-C 之間來回切換並觀察一下，就能稍微體會到分支之力囉。

Git Stash：讓我們快速存個檔

要注意，checkout 只能在已經 Commit 的情況下進行。如果萬不得已必須中斷手上工作切換到其他分支的時候（例如突然被叫去修正式環境的東西），可以使用 stash 來做暫存的動作。

關於 stash 的使用方式，由於我個人比較少用，故不再贅述，可以參照以下兩篇：

2021.04.30 補充:

才剛說比較少用而已，結果沒多久就遇到需要使用 stash 來暫存的時候囧。所以這邊還是簡單記一下語法，感謝連猴子都能懂的 Git 入門指南：

git stash 直接進行暫存
git stash save 可以在 save 後面替這次暫存取名字
git stash list 可以看現在有哪些暫存
git stash pop 可以取出最新的暫存，或指定 ID 來取出指定暫存
git stash drop 可以刪除最新的暫存，或指定 ID 來刪除指定暫存
git stash clear 刪除所有暫存

Git Merge：讓我們合併兩條分支吧

「真是太諷刺了紹安，你拉了新分支繞了一大圈，
　最後做出來的 feature 竟然是你不想做的，你老闆的需求。
　所以說呢，分支最後終究是要回到 master 來的，
　這四千個 Commit 的盡頭 Merge，或許正是你的極限也說不定。」

不管是新功能的開發，問題的修復，效能的測試等等，大多數以上的分支最終都是需要合併回來的。每個專案大概就像那種機器人合體戰隊的動畫的每一集一樣，最後都要來 Merge 一下，可以說是避無可避。

我們在前面一節有開出了兩個分支：Branch-B 和 Branch-C，現在讓我們把他們合而為一。首先，讓我們先簽出到 Branch-B：

git checkout Branch-B

接著使用 git merge 指令來用 Branch-B 分支把 Branch-C 分支給吃進來：

這時候可以觀察看看 hello-git 資料夾，B.txt 和 C.txt 應該都已經消失了。

我們可以用 git log 來觀察一下：

可以看見，我們在 Branch-C 所做的 Delete C.txt 這個 Commit 也出現在 Branch-B 的記錄中的，並且 C.txt 也確實消失了。

這邊可以注意，當我們用 Branch-B 把 Branch-C 吃進來的時候，Branch-C 本身並沒有任何改變，仍然停留在 Delete C.txt 這個 Commit 上，而用來吃掉對方的 Branch-B 則取得了所有 Branch-C 的變更。

所以合併的時候要注意一下當前的分支，是將目標分支匯入到當前所在的分支，不要弄反了，不然把一堆測試用的東西合併上去正式環境就完蛋啦。

現在我們再把 Branch-B 的變更也合併進 master 吧。

同樣地，先簽出 master，再 git merge Branch-B

這樣就成功將兩個負責不同項目的分支裡的變更都合併回 master 囉！

什麼是衝突（Conflict）？

當然，不是每一次合併都能順利，就像不是每次合作都能順利一樣。只要兩個分支有共同增刪改同一份文件同一個區塊，在合併的時候就會發生衝突。

衝突的時候我們得要開啟檔案逐一審查有衝突的區塊，並選擇使用對方還是自己還是手動合併成新的版本。

現在讓我們來實際操作看看吧：

首先，讓我們先確認自己在 master，然後新建並簽出一支新的分支 Branch-X。

如果要同時做簽出並且新建分支的話，可以在 checkout 的時候加上 -b 試試：

git checkout -b Branch-X

然後，將 A.txt 的內容改成 Hello X!：

並且 Commit：

git commit -a -m "Hello X!"

緊接著，讓我們回到 master，重新建立並簽出另一支分支 Branch-Y：

git checkout master
git checkout -b Branch-Y

這次我們把 A.txt 的內容改成 Hello Y!：

並且 Commit：

git commit -a -m "Hello Y!"

現在，我們手頭上有 Branch-X 和 Branch-Y 兩條分支了，並且他們都變更過了 A.txt，現在我們直接用 Branch-Y 來合併 Branch-X：

git merge Branch-X

可以看到 Git 跳出訊息跟你說自動合併失敗（Automatic merge failed），要求你進行修復。

並且 git status 也會告訴你，你有未處理的 merge 問題，A.txt 這個檔案都有被變更到：

這時候讓我們去看看 A.txt 的內容：

會看到 Git 標示出發生衝突的部分，上半部是我們當前 HEAD 也就是 Branch-Y 的內容，下部分則是 Branch-X 的內容。

我們必須把這個衝突的部分處理好，並且把這些標示拿掉，再重新 Commit 一次。假設Ｘ跟Ｙ兩位同事經過扭打討論之後，決定改成兩個人的名字都要標在上面，變成 Hello X & Y!，我們就可以進行 commit 來結束衝突囉：

通常來說，如果是使用 GUI 工具的朋友，應該會像 Diff 那樣給一個對照的列表讓你選擇，例如說我平常用的 Visual Studio 就會並排讓你勾選要使用哪一邊的，或是自己修改（這邊借用一下官方文件的圖）：

又或是可以直接選擇「使用當前分支」、「使用對方分支」的這類方便選項。但要特別注意一點，就是衝突一定要好好解開再上傳，絕對不要沒解衝突就直接 Commit 掉推上來造成大家困擾，這個一定要特別記得，弄不好可是會折壽的，物理上的折壽。

通常來說，發生衝突的時候必須了解兩方修改的內容和意圖，並且協調好處理的方式，再編寫成程式碼並解除衝突。這時候我就很佩服幫忙合併的前輩，我真的會看到眼花。

補充：如果衝突的檔案不是文字檔而是圖片檔，又或者是接下來要說明的 rebase 造成的衝突，處理的方式會不太一樣。可以參考為你自己學 Git 的這篇合併發生衝突了，怎麼辦？

Git Rebase：讓我們移花接木

在處理分支的時候還有另一種合併方式，就是使用 Rebase。

我們在前面分支的章節有稍微提起過，分支的 base 是建立出分支的 Commit，也是分支和其他分支比較的基準點。而 rebase 就是「重新設定基準點」的意思。

剛剛在 merge 的時候，我們已經將 Branch-X 併入了 Branch-Y ，現在就試試用 rebase 的方式，將 Branch-X 併入 master 吧。

git checkout master
git rebase Branch-Y

這樣就會將 master 的 base 重新設定到 Branch-Y 分支上囉，因為我們的狀況比較簡單，所以比較像是 master 推進到了 Branch-Y 的進度，讓我們用 git log 確認一下當前的狀況吧：

可以看到剛剛在 Branch-Y 上的操作，例如解衝突的 Commit 都已經進到 master 來了。

Rebase 跟 Merge 最明顯的差別在於 Rebase 是將這個分支 逐步移植 到另一個分支上，而不是像 Merge 將兩條水流引流成一條，所以並不會有合併時的 Commit。

但也由於是從切出分支的基準點開始做移植和計算的動作，我個人是覺得相對比較危險的，例如說你的 Git 分支樹就會和別人的那一份產生差異等等，畢竟這是一個變更歷史的行為，因此還是小心使用比較好，我個人是盡量能用 Merge 就用 Merge 的流派啦。

關於 Rebase 的部分，為你自己學 Git 的這篇另一種合併方式（使用 rebase）相當詳細，有影片還有圖解及 rebase 的步驟說明，失敗救回的方法。如果有需要用到 rebase 來處理，可以先稍微閱讀一下。

還有 Rebase 和 Merge 兩種合併方法的差異，可以參見猴子都會的 Git 的這篇分支的合併，有針對 Merge 和 Rebase 代表的操作進行圖解。

此外，Rebase 也可以用來修改先前的 Commit 之類的，例如搭配 squash 來把多個 Commit 壓縮成一個 Commit，請參見使用 rebase -i 合併提交、送 PR 前，使用 Git rebase 來整理你的 commit 吧！

我們現在有哪些分支（Git Branch）？要怎麼刪除分支？

現在我們針對分支的基本操作已經告一段落。可以用 git branch 來稍微看一下本地端的儲存庫都開了哪些分支。

前面加上 * 號的就是當前所在的分支，如果已經和遠端儲存庫連線的朋友，也可以使用 -r 參數來看遠端儲存庫上的分支，用 -a 來看本地和遠端的所有分支。另外，遠端儲存庫的分支將會用 remotes/ 開頭。

由於前面示範合併和衝突的分支們的工作都已經告一段落了，我們現在就要稍微清理一下它們。要刪除分支，只需要加上 -d 參數就可以了，像現在這個例子就是：

git branch -d Branch-B
git branch -d Branch-C
git branch -d Branch-X
git branch -d Branch-Y

接著再讓我們用 git branch 確認一下吧：

認識 Git 的斷頭（detached HEAD）

我們在前面切換分支的時候，主要是使用 checkout 來進行。但如果我們並不是針對某個 branch 去做 checkout，而是對某個 commit 去做的時候，就會變成斷頭狀態。

因為 HEAD 會指向當前的分支，所以當我們用 checkout 並不是用來切換分支，而是單純回到某個 Commit 的時候，Git 實際上是幫我們建立一個未命名的分支，這時候如果又做了一些事情並 Commit ，又來回跳（例如說 checkout 到別的地方去），我們就會找不到這個仍未取名的陌生分支，並遺失掉這些變更。

這也就是為什麼上面的 checkout 範例，會有一大段警告，告訴你你的 HEAD 掉了，現在在斷頭狀態。

這時候如果要做什麼變更，就開條新分支吧。畢竟，分支標籤不用錢，成本超低廉，各位還是在分支間跳來跳去吧，至少跳完了找得回來嘛。

關於 Git 的分支策略

既然是團隊合作，雖然大家各自拉了一條分支出去做事，但還是要有點 SOP，這就叫做分支策略。

以最常見的 Git Flow 來說，會有兩個最重要的分支：正式服務的主要分支（master, main）、開發用的測試分支（develop）。接著再衍生出相關的分支，例如功能（feature）、修復（hotfix）等等。

當然針對這些分支，也會有一些相關的規定，主要會有命名規定和合併的規定。例如微軟的分支命名建議就比較像 {分支種類}/{人員}/{描述}，例如說小明拉了一個產品功能的分支，就是 feature/Ming/product 等等。

流程的部分就有多個流派，目前我們常用的方式和上面提到的 Git Flow 比較相像，是從 master 拉出 develop，然後在 develop 上拉出多個 feature 進行開發。

這些 feature 分支開發完畢後，再匯回 develop 進行測試，當專案完成、develop 的測試通過後，就可以推上 master。

而當線上有問題發生的時候，會從 master 拉出 hotfix 分支，並修復完成之後同步更新給 master 和 develop。藉此保持 master 分支的穩定和乾淨。

不過當然這是我所屬的團隊常用的方法，這些流程還是很吃團隊文化的，記得入境隨俗哪。

關於這些分支的介紹和協作，可以參照這些文章：

另外，關於分支的處理和觀念，特別推薦這個系列，獲益良多：

什麼是 Git 的遠端儲存庫（Remote）？
要怎麼把變更推送（Push）到遠端儲存庫？

開始本章節之前，你可能需要先註冊好 Github，註冊過程挺簡單的，不用擔心

既然都已經使用 Git 了，當然要推送到遠端儲存庫啦！作為儲存庫的服務有蠻多的，例如 Github、GitLab、Gitea 等等，本篇會以最知名的工程師交友網站 Github 為例。

“what’s the difference between git and github?”
“It’s the difference between porn and pornhub.” (Reddit)

首先讓我們在 Github 上新建一個儲存庫，從 My Repositories 或是首頁進去都可以：

接著讓我們填寫一些基本訊息，像是專案名稱和專案敘述：

底下會有一些選項，像是是否加入 .gitignore 啦、是否加入 readme（說明文檔）等等，這邊暫時還不會用到。

完成後就可以按下 Create Repository，接著就會來到專案啟動畫面：

這個畫面已經說明了不同狀況下的操作，像我們已經在本機已經存在儲存庫了，所以我們可以參考「…or push an existing repository from the command line」這個部分進行操作。

其中最重要的是上面那串 .git 結尾的網址，我們接著就要使用這個網址來將剛剛的 hello-git 資料夾推送到這個儲存庫。

現在讓我們鏡頭回到棚內的 git 指令，首先 git status 確保 Commit 等動作都已經完成：

接著讓我們用 git remote add 來增加叫做 origin 的遠端儲存庫到這個儲存庫中，完成了之後再用 git remote 確認遠端儲存庫列表是不是已經有 origin 了：

git remote add origin https://github.com/yourGithubName/yourGithubRepository.git
git remote

因為 Github 的主要分支已經改成使用 Main 了，因此我們順應一下，也用 git branch -M 把 master 分支改名成 Main 吧

git branch -M main

完成之後，就可以開始上傳囉。在 Git 中，推送到遠端儲存庫只要使用 push 指令就可以了，語法是 git push {遠端儲存庫名稱} {要推送的分支}，例如我們現在的推送就是：

git push origin main

推送完成後，讓我們再回到 Github 上查看：

可以看見東西都已經推送上去了。這時候按下旁邊的 Commit，也能夠查看這個儲存庫的 Commit Log 囉：

到這邊就成功把存檔弄上雲端啦！

補充：如果儲存庫曾經有用 reset 之類的往後跳，並且遠端儲存庫的版本又相對較新，例如遠端是第五版，抓下來之後 reset 回到第三版，這時候的 push 就會被擋下來，要求取得遠端最新的版本。

諸如此類的狀況，造成無法推送的時候，如果十、分、確、定手上的這份才是對的，必須推送上去，可以使用 -f 參數來進行強制推送。可以參見：狀況題】聽說 git push -f 這個指令很可怕，什麼情況可以使用它呢？

不過說實在的，還是祈禱不會遇到需要 -f 的那一天吧…

要怎麼從 Git 的遠端儲存庫拿到變更？認識擷取（Fatch）、提取（Pull）

上傳到雲端已經沒問題了，那從雲端下載到本機呢？這時候我們就需要用到 fetch 和 pull 這兩個指令。

現在讓我們回到 Github 的畫面，並且進入 A.txt

然後按下編輯：

把內文稍微修改一下，例如改成 Hello X & Y & Z!

拉到最下面，加上 Commit Message，並且按下 Commit Changes

現在遠端儲存庫已經有了一個變更，但是我們本機還不知道呢！接著就讓我們實際操作一下，首先我們需要取得遠端的資訊，這時候就可以用 fetch 來擷取遠端儲存庫的資訊回來：

git fetch

可以看見 Git 從遠端儲存庫抓了資訊回來，這時候我們如果查看 git log，並加上 --all 來顯示全部分支的話：

可以看見有一個 origin/main 的分支超越了我們的 main 分支了，這也就是在 origin 遠端儲存庫的 main 分支的意思。這時候我們就可以知道，遠端儲存庫的進度比起我們本機的還要更新。

那麼要怎麼讓本機的進度追上呢？其實 main 和 origin/main 也就是兩條分支，所以只要使用 merge 就可以把進度往前推。

當然我們也可以不用這麼麻煩，可以直接使用 pull 指令來提取遠端儲存庫對應的分支直接和本機現在的分支進行合併，也就是 fetch + merge。這樣就是從雲端下載最新檔囉！現在就讓我們試試吧：

git pull origin main

pull 語法的邏輯和 push 是一樣的。當我們 pull 下來後，就可以 git log 來確認一下記錄囉：

可以看到我們的 main 分支已經跟上 origin/main 的進度囉！

使用 Git Clone 直接把遠端儲存庫的 Repo 抓下來

上面我們已經嘗試過「本機有儲存庫，上傳到遠端儲存庫」的場景了。但是大多數時候，像是我們在公司會需要接手開發專案啦、使用人家已經寫好的工具啦等等，都是「本機沒有任何東西，要從遠端進行下載」的場景。

這個時候就是 Github 大家最常做的 Clone 出場的時候啦！

現在就讓我們再新增一個 GitRepos 資料夾，我們的目標就是把儲存庫拉下來這裡：

接著讓我們回到 Github 上的 Repository，畫面中間靠右會有一個綠色的 ↓ Code 按鈕（這應該是整個 Github 大家按最多次的按鈕）點開就會出現下載選項：

分別是各個命令列下載方式對應的連結、Github Desktop 專用的開啟方式，還有最常用到的 ZIP 下載方式。

我個人是比較常下載壓縮檔來解壓縮啦，不過都已經用指令到這裡了，就讓我們來試試 git clone 吧：

git clone https://github.com/yourGithubName/yourGithubRepository.git

接著在 GitRepos 裡面就生出來一個 hello-git 啦，進入後檔案也都在呢：

這樣就成功把儲存庫 Clone 下來囉！

Clone 下來的儲存庫會自動建立和遠端儲存庫的繫結，也就是已經是 git remote add 好的狀態，相當方便。接著後續就和基本的 Git 操作一樣囉。

認識 Git 的提取要求（pull request, PR）

如果你 Clone 的是自己的儲存庫，當然就可以開始工作後 Add Commit Push 連發，但如果不是你自己的儲存庫，又想要幫忙修改東西，或是工作上有審核機制，該怎麼辦呢？

這個時候我們就要用提取要求（pull request）的方式來互動啦。

Pull request 就是指發出一個 request 請對方來 Pull，如果對方覺得 OK，就會同意提取要求並把變更合併到自己的儲存庫裡。不過發 PR 這個動作似乎在每個平台都有點微妙的不同。

例如說平常工作時候使用 TFS（現在叫做 Azure DevOps）的發 PR 方式，是將分支推送上去之後，發起 PR 並請主管審核，確認沒問題後再進行 Merge；但在 Github 上，則是要先叉（Fork）一份到自己家，Clone 下來修改完之後推上去，再發出 PR 請對方來提取合併。

PR 比較常見於社群協作，還有工作上的提交審核等等，也由於這個部分已經是社群互動的進階動作了，故先按下不表。附上 Azure DevOps 和 Github 的 Pull Request 操作方式的介紹文章，有興趣的朋友可以去看看：

小結

本來只是想介紹一下 Git 的一些基本操作，沒想到越弄越長（汗），儘管如此，還是有很多說明不到的地方（例如提取要求、分支策略等等），留待各位實戰的時候細細體會了。

最後還是要說句，真的要買一本為你自己學 Git 放在手邊哪，有夠實用。感謝作者，感謝網路上的各位大大，感謝公司圖書櫃，各位一生平安。

那麼，這篇就先到這裡啦，這個系列終於還是開坑了，希望這次也能順順利利了…吧。那麼，我們下次見！

本系列下一篇：菜雞新訓記 (2): 認識 Api & 使用 .net Core 來建立簡單的 Web Api 服務吧

本系列文章

參考資料

菜雞新訓記 (0): 前言

Igouist (Igouist) — Mon, 05 Apr 2021 22:39:00 +0800

長夜將至，我從今開始守望。
　　　　　　　　　　　　　　　　　　　　　　　　　——《冰與火之歌》守夜人誓詞

年初整理完物件導向系列後，休息（沉迷遊戲）了好一陣子，終於要繼續整理公司新訓的內容啦！

因為這個系列會是公司新訓時期的筆記整理，所以會是比較簡易的實作紀錄，並不會太過深入，需要的時候會用延伸閱讀的形式補充上去。如果看文的過程中覺得有什麼能夠補充的，也歡迎告訴我呦。

本系列預計會從 Git 的基本操作開始，簡單建立一個 Web Api 為主軸，逐步介紹相關的部份，例如簡單地引入套件、簡單地分層等等。基本方針就是直接抄襲隔壁同事的部落格。

後續有更新的文章，就會整理到這篇目錄中。或是也可以從菜雞新訓記裡面做系列文的查詢。

那麼，就從第一篇：Git 入門這樣做開始吧！

本系列文章

《隻狼》＆《黑暗靈魂３》白金紀念

Igouist (Igouist) — Sat, 13 Mar 2021 09:38:00 +0800

苦難終於告一段落了，開心到 PO 一篇來紀念一下！

接下來…… 就坐等血源詛咒上 PC 啦（等得到嗎？）

Visual Studio: 書籤 (bookmarks)

Igouist (Igouist) — Sat, 13 Mar 2021 00:38:00 +0800

今天從同事們那邊學到了書籤這個方便功能，趁還記得的時候來做個紀錄。

那麼馬上就來操作一次：

使用 Ctrl K, Ctrl K 可以在指定的行號上加上一個「書籤」

接著我們就能在書籤視窗中看到這個書籤（檢視＞書籤視窗，或是 Ctrl K, Ctrl W）

在書籤視窗中，也可以對書籤重新命名，或是建立資料夾進行管理

而當頁面中有多個書籤的時候，就可以利用 Ctrl K, Ctrl P 和 Ctrl K, Ctrl N 來在書籤中移動

這個快速移動能用在什麼時候呢？

我們在進行一個專案時，會常常需要在多個檔案，或是在一個較長的檔案的各處來來回回。

例如 private 方法離使用到的 public 方法有點遠，又或是我個人就常常會寫某個 Function 到一半的時候，突然發現：「啊！我忘記在建構式的時候把要用的對象傳進來了。」

這時候就需要來回跑確認方法內容，或是移動到整個類別的頂部去增加宣告和修改建構式，接著再回到剛剛撰寫中的方法，在程式碼裡面折返跑，好不愉快。

以往遇到這種狀況，我會稍微記一下行號，再利用 Ctrl G 跳回去。

今天跟同事聊到書籤的時候，就想到：像是上面的場景，便可以利用書籤來紀錄常用的幾個地方，並快速切換。並且用法也簡單直覺。~~大概就像飛雷神之術一樣吧。~~這邊就記錄一下，也分享給大家。

參考資料

設定程式碼書籤 - Visual Studio | Microsoft Docs

菜雞與物件導向 (Ex1): 小結

Igouist (Igouist) — Fri, 01 Jan 2021 23:50:49 +0800

隨著 2020 進到了 2021，菜雞與物件導向也推進到了五大原則結束，可以暫時告一段落了。

最初和朋友約好了要把公司新訓學到的東西做個整理（廣告一下他的部落格：Sian），只是沒想到因為太常發廢文偷懶，大半年才推進到物件導向的基礎而已，甚至占不到新訓內容的十分之一。希望 2021 能繼續推進，把這部份的坑給填一填，然後把前面的文章也重構一下，只是按照我的個性，可能又會忍不住開新的坑吧，哈哈。

至於物件導向相關的心得和紀錄，也就是這個系列，偶而有想到或是有所體悟的時候再發上來吧，暫時想先把前面隨手寫凌亂文章給整一整先。在這個十幾篇的短系列，記錄了從類別與物件開始，到耦合、內聚及五大原則，每個主題的心得。這邊稍微做個小整理：

類別、物件

物件就是用來表達「我們知道的某個東西」，物件導向是用物件彼此互動的方式來建立架構
類別去定義我們要的物件有什麼特徵、有什麼功能，再從類別中實例化（也就是根據設計圖產生）物件出來使用

建構式、多載

建構式用來在建立物件時就進行一些我們想要的操作，例如狗狗的毛色等等天生的東西，或是這個建立這個物件的必須素材
多載指的就是可以有很多個同樣名字的方法，各自去接不同的參數，讓同個目標的函式可以根據傳入的參數不同做不一樣的處理

封裝

封裝將物件視作一個整體，讓每個物件保留自己的隱私。將物件的實作內容隱藏起來，互動的其他物件和使用者只需要知道怎麼使用即可
兩個物件彼此了解越多，耦合就會越高。因此藉由封裝，我們提高類別內的內聚性，降低對外的耦合性，隱藏複雜資訊，並且迴避掉一些不小心直接用了不該用的方法造成的問題

繼承

繼承是一種「is-a」的關係。當你能說出Ａ是一個Ｂ的時候，就代表你認為Ａ可以繼承自Ｂ
- 最直覺的繼承例子就是物種的分類。舉例來說，狗跟貓都是哺乳類，因此他們都可以繼承到一些哺乳類共通的特徵（例如哺乳、用肺呼吸）
繼承讓我們能只修改基底類別，便讓所有衍生出來的類別都一併受用，大大提高了程式碼的重複使用性
但是，同時也帶來了強耦合，讓我們在修改基底類別時，不容易察覺到衍生類別因為這次修改而連帶發生的問題
謹慎使用，或是乾脆不要用

多型

多型允許繼承同一個父類別的各個子類別可以用不同方式去實現父類別的要求。藉著用子類別實作出各式各樣不同的方法，就能讓父類別的方法達到延伸和多樣化的效果，而不需要更動父類別本身
同時，當子類別被以父類別的名義建立出來時，他就只能夠表現出父類別的樣子。使用者基於封裝的精神，不需要知道實作的細節

抽象、覆寫

這邊的抽象指的是抽象類別，也就是無法被實例化的類別，通常我們會用來宣告那些不應該被實體化成一個物件的類別，例如哺乳類
覆寫是指對於像是前述的抽象方法，或是一些父類別定義好要求子類別必須重新實作的虛擬方法時，子類別繼承後必須重新去實作該方法，藉此達到多型

介面

介面就像是針對類別的實作、物件的行為去做規定的一個契約書，只需要先定義好該做的事，裡面怎麼做不需要管；所以只需要宣告要求的方法，不需要撰寫方法本體
介面將物件之間的互動的著眼點放在該物件的行為上，降低了物件之間的耦合，更提高的物件彼此替換的彈性

內聚、耦合

內聚是指：把需要的程式和資料都包裝在同一個模組內，使得該模組能夠做為一個單獨的個體執行
內聚代表的是該模組的獨立性，當這個模組可以獨力完成工作，就代表我們能夠重複使用它，且不需要擔心影響到其他模組
追求高內聚是絕對必要的，但達到完全內聚是不應該的，容易創造神之類別或大量複製貼上，使程式碼難以重複使用
耦合是指：如果模組和另一個模組有關聯，那這兩者之間就耦合
耦合會讓物件之間彼此相關，容易導致改東壞西的狀況，提高修改的難度。但因為物件導向讓物件之間協作的精神，達到毫無耦合是不可能的
彼此關聯就會彼此牽連，因此我們要讓物件彼此之間保持一個舒適的距離。注意，是舒適的距離，而不是不相往來，健康的內聚就是健康的耦合
判斷健康的內聚和耦合的標準，取決於該模組是否符合單一職責原則

SOLID

隨著物件導向的亂用、誤用、無腦用，軟體就會逐漸腐化。因此，大前輩們整理並提出了一些可以致力的方向，也就是所謂的「原則」
藉由這些原則，我們可以讓程式碼「能容忍變化、容易理解、能讓模組和元件使用」，達到降低程式碼的腐化臭味的目標
整個 SOLID 就是面對變化的作戰策略

單一職責原則

顧名思義，就是一個類別應該只負責一個職責，但是職責的定義和大小容易產生誤會。因此實際定義是：就一個類別而言，應該只有一個引起它變化的原因
引起變化的原因可能是業務需求的變更或追加，注意不要讓類別做它不該做或好像超出範圍的事情
把工作交給負責該職責的類別去做，自己只需要關注在自己正在處理的職責即可，也就是封裝的體現
單一職責的關鍵在於展現程式碼的意圖，並時常自問：是否只有一個原因造成改變？職責是否清晰？
當我們並未遵守單一職責原則時，會容易產生意外的重複、修改時也無法界定影響範圍、並且每次修改都要閱讀大量無關程式碼，使得修改成本大幅上升
而遵守單一職責時，我們提高的程式碼的重複使用率，降低修改成本，並且也提高了內聚、降低了耦合，讓程式更容易管理

開放封閉原則

軟體實體（類別、模組、函式等等）應該對擴展開放，而對修改封閉
面對需求，對程式碼的改動是透過增加新程式碼進行的，而不是更改現有的程式碼
開放封閉原則的關鍵在於模組化，以及準備擴充點。藉由單一職責切分出模組，並在主要邏輯和附加邏輯之間，加入抽象層來解耦合，可以讓物件之間保持彈性
目標在於降低修改成本和風險，凡是變化都有成本，但如果我們做好模組化，並事先準備面對修改的策略，就可以降低修改的風險

里氏替換原則

子類別必須能夠替換父類別，不需要改變，也不會發生任何錯誤或異常
我們預期了這個函式或類別需要準備的輸入參數，也預期了應該要有的輸出結果。如果某一天替換了子類別，卻不是這麼一回事，就會發生很多意料外的錯誤
里氏替換原則的關鍵在於繼承時必須遵守三個條件：先驗條件不可以強化、後驗條件不可以弱化、不變條件必須保持不變
繼承的時候應該著眼在能否做出父類別期望的行為，而非子類別是否所屬於父類別（企鵝不會飛，鳥會飛）

介面隔離原則

不應該強迫用戶依賴它們未使用的方法；應該最小化類別與類別之間的介面
介面也必須要通過單一職責的考驗，在定義介面時，優先從組合的方面進行考慮，把想要的行為用職責的角度去思考

依賴反轉原則

高階模組不應該依賴於低階模組。兩者都應該依賴抽象
Ａ模組直接受到Ｂ模組的影響，我們就稱Ａ依賴了Ｂ。同時，抽象不應該依賴細節；細節應該依賴抽象，因此我們需要用抽象層將依賴做隔離
依賴反轉原則的關鍵在於抽象層的觀念：並不是低階模組的實作提供了抽象層，而是高階模組針對所需要的功能提出了抽象，而低階模組去實現它
針對反轉之後如何建立實例的問題，控制反轉是一個常見的思路：讓控制反轉中心去建立低階模組，然後高階模組要使用的時候再把這個低階模組交給高階模組使用，這個過程的實現方法就叫做依賴注入。藉此讓高階模組處於控制權上的被動，同時也不用再負責建立低階模組，解除兩者間的依賴

最少知識原則

只和直接的朋友溝通，不和陌生人說話，一個物件應該對其他物件應該只有最少的了解
- 直接的朋友包括：該方法所屬的類別、該方法所接收的參數、該方法中建立的類別、該方法所屬的類別所依賴的對象
- 換個方向想就是直接具有依賴關係的類別和方法
不應該使用其他類別的方法所回傳的類別的方法
最少知識原則的關鍵在於良好的封裝：複雜性隱藏到自己內部，對外只開放必要的功能，並且只使用到直接關聯的對象，確保不會造成意外的耦合

當然，還有許多沒有收錄或是我也尚未學習到的部分，就先收錄在本篇結尾的遺珠之憾單元。如果有什麼體悟了，或是累積了一些數量（也就是之後腦洞又開了）就再拿來發新文章，如此豈不樂哉。如果對內容有什麼想法或能補充的，有發現我有所疏漏的地方，也還麻煩跟我說一聲，這邊就對那些願意給予幫助、以及把這些文章看完的朋友道個謝囉。

那麼，我們下個系列再見囉，各位新年快樂！

</2020>

遺珠之憾

這邊放一些物件導向相關的咚咚和推薦文章，彌補本篇一些沒提到的部分，例如合成複用原則、三次原則等等。當然，有想到也會回來補充一下啦～

同系列文章

菜雞與物件導向 (15): 最少知識原則

Igouist (Igouist) — Sun, 20 Dec 2020 23:57:00 +0800

在上一篇我們紀錄了依賴反轉原則，到此五大原則介紹完畢…是這樣嗎？太天真了！就像四天王總是五個人一樣，五大原則當然也有第六個！

今天的主角就是五大原則中Ｌ位的第一候補：最少知識原則，也被稱作迪米特法則。

最少知識原則 (Least Knowledge Principle)

只和直接的朋友溝通，不和陌生人說話

那麼所謂的朋友是什麼呢？就是指這個物件或方法有直接相關的物件啦。例如當我們使用一個方法時，這個方法應該只認識：

該方法所屬的類別
該方法所接收的參數
該方法中建立的類別
該方法所屬的類別所依賴的對象

除此之外對這個方法而言都是陌生人。什麼情況會遇到陌生人呢？有一個蠻常遇到的狀況就符合定義：當我們使用依賴對象的方法，該方法給了我們另一個類別時，我們就正在接觸毫無關係的陌生人。

這個原則的要求就是：不要跟陌生人說話，就算是朋友介紹了他的朋友給你也一樣，不認識就是不認識，更不能拿陌生人的東西。換個方式就是說：不應該使用其他類別的方法所回傳的類別的方法。

用文字的可能會有點繞口令，簡單來說就是像 Foo.GetBoo().BooDoSomeThing() 這種情況，我們不該去跟 Foo 要 Boo 回來然後使用 Boo 的方法，因為我們只認識 Foo，而不認識 Boo。

畢竟，很多時候我們不該直接插手控制：

主人可以叫狗坐下，但主人不應該直接控制狗的腿坐下
當我們按下牆壁的開關時，是希望燈直接打開。而不是彈出兩條電線讓你自己接起來
當我們去餐廳時，會讓服務生替你把要求的餐點交給廚師烹調，而不是我們直接殺進去廚房對著廚師吼「你給我煮啊！」

這種直接叫廚師煮給你看、甚至自己搶過來煮的做法，就是平常直接伸手進去其他模組的控制狂、完全和封裝的概念背道而馳。

腿的動作就應該讓狗去自己控制，讓燈泡亮就應該隱藏在開關之後。物件就該只和直接的朋友溝通。

除了只和直接的朋友溝通，也就是只和直接依賴的類別互動，這個互動也是要講究一點的。畢竟朋友之間也還是會有共通的默契和距離，類別之間的互動也應該只做必要的溝通。

這就是我們在封裝提過的「給程式碼隱私的空間」：為了避免物件之間的互動情況過於複雜，我們應該加以控制，把各自的工作封裝在各自的物件內部，使其只有必要的往來。

因此最少知識原則就要求了：一個物件應該對其他物件應該只有最少的了解。

到這邊讓我們稍微整理一下：

只和直接的朋友溝通，不和陌生人說話：
物件或方法應該只和自己及直接接觸的對象互動
不應該使用其他類別的方法回傳的類別的方法：
不該破壞封裝並造成額外且違反邏輯的互動
一個物件對其他物件應該只有最少的了解：
類別只開放 (Public) 必要的功能，並且類別之間應該只有必要的互動

也就是說：只依賴應該依賴的對象，只開放應該開放的方法。

聰明的朋友應該能從這邊看出最少知識原則的核心理念了，就是解除耦合。

我們在耦合篇提過，物件彼此有關聯就會產生耦合，而不好的耦合就會散發出臭味。為了方便管理和降低複雜性，減少臭味出現的機率，我們的目標就是追求耦合。

相對於依賴反轉原則利用抽象和介面的方式在模組之間做出隔離和控制的作法。最少知識原則則是利用封裝的概念來解除耦合，畢竟，關聯越少耦合也越少嘛。

所以我們可以說：良好的封裝就是符合最少知識原則的封裝。複雜性隱藏到自己內部，對外只開放必要的功能，並且只使用到直接關聯的對象，確保不會造成意外的耦合，且讓關聯的模組之間更加靠攏。如此一來，就能夠更加提高內聚、降低耦合了。

然而，為了好好地切分朋友和陌生人，也可能會變成需要建立更多的中間類別，或是更多的依賴關係。

例如人原本可以直接把電線接起來讓燈泡亮起來，但為了把電線使燈泡變亮這件事的複雜度封裝起來，我們就必須要有一個開關，再把電線放到開關後面去，變成了人按下開關，開關藉由電線點亮燈炮等等，整體來說會使系統內的類別變多。

因此，在設計的時候也必須要考量到整個方法串的深度，可以用單一職責的角度下去衡量。請不要越封裝越細，類別越做越多，反而變成過度設計了。

那麼，今天就記錄到這裡。由於最少知識原則的概念，大多在封裝篇和耦合篇的時候就已經偷渡完了，所以這邊就針對觀念簡單介紹，實務上處理類別間的耦合時，就可以稍微從最少知識原則的角度想一想，一定會有幫助的。那麼，我們下次見～

本系列下一篇：菜雞與物件導向 (Ex1): 小結

參考資料

同系列文章

菜雞與物件導向 (14): 依賴反轉原則

Igouist (Igouist) — Sun, 13 Dec 2020 21:53:00 +0800

章節目錄

在聊依賴反轉之前，先讓我們聊聊什麼是依賴：

例如說如果有個像我一樣的肥宅每天一定要來一片雞排才能療癒身心，那我就是依賴雞排；
同樣的，如果有個大叔不抽菸就會全身不舒服，就是對香菸有所依賴。

當有「必須要藉由某個人事物來達到目的、受到某個人事物的影響和牽制」時，就是依賴。

而在程式設計裡面的概念也一樣，如果Ａ模組直接受到Ｂ模組的影響，我們就稱Ａ依賴了Ｂ，最明顯的狀況就是Ａ模組需要藉由Ｂ模組的實例來完成某個功能的時候。

例如「匯出報表」功能建立了一個「Excel 控制類別」的實例以建立檔案；
或是「會員查詢」功能建立了一個「DB 連線」的實例來進入資料庫取得會員資料

遇見這種「必須要藉由某個模組的實例來完成想要的動作」的狀況時，就是依賴。

依賴與耦合

我們在之前的耦合篇提過，如果模組和另一個模組之間有關連，那這兩者之間就耦合。以此來看，依賴就是一種耦合的關係，那麼，依賴是健康還是不健康的耦合呢？

現在讓我們用多型篇用過的「老闆徵工程師」的例子來舉例一下：現在有間小小公司，老闆請來了小明當工程師，並請他開工撰寫產品程式碼。

當「撰寫產品程式」對「工程師」直接依賴的時候，狀況可能是這樣的：

public Product Work()
{
    Ming programmer = new Ming();
    var product = programmer.Programming();
    return product;
}

過一陣子，老闆發現小明寫出來的東西似乎不太行，於是把小明趕走，另外請了小華。這時候因為「工程師」這個實作類別不一樣了，我們就必須要改一次程式碼：

public Product Work()
{
    Hua programmer = new Hua();
    var product = programmer.Programming();
    return product;
}

又過了好一陣子，老闆又另外請了小美來工作。於是又要再改一次，而且小美的工作方式甚至不叫做 Programming，而是 Coding：

public Product Work()
{
    Mei programmer = new Mei();
    var product = programmer.Coding();
    return product;
}

現在有感覺到一點問題了嗎？如果一直換人，Work 的程式碼豈不是每次都要修改？甚至根據依賴對象的不同，連使用方式都可能受到影響，很明顯這樣就是所謂不健康的耦合。

這邊還有個例子我很喜歡，在這篇依賴倒置原則的文章中，用吃東西來舉例：如果寫死了依賴漢堡，難道一輩子就只能吃漢堡了嗎？如果想改成吃義大利麵，就要修改程式碼；有一百種食物，難道就要改一百次嗎？

試想，因為「DB 的連線方法」有了一些變更，使用到該方法的「會員查詢」就連帶要更動，甚至有關聯的地方都必須要變動，如此一來改動的範圍如森林大火般延燒。

同時由於我們在開發功能的時候，都是讓大功能（高階模組）調用各個小功能（低階模組）來實現目標，越高層的就越整體、越抽象、越接近目標；而越低階就越細節、越接近實作，關注點越小。而我們的思維通常是由大範圍往下到小實作，從整體目標逐漸拆解成各個步驟。

但是，當我們的高階模組直接依賴低階模組的時候，事情就會變得有點怪怪的。就像董事長必須清潔廁所導致沒空進行公司決策一樣，原本職責在於高層次、整體的模組，卻不得不因為這些低階模組的變動受到影響。那麼隨著層次越高，底下依賴的模組越多，改動的頻率就會提高。

既然改動範圍又大，改動頻率又高，耦合又不健康，就代表這樣的依賴是有問題的。然而，物件導向的精神就在於讓物件之間互相協作，消除多餘的重複。因此，依賴又是不可能消除的。

依賴反轉原則 (Dependency-Inversion Principle)

面對這樣的困境，依賴反轉原則告訴我們：

高階模組不應該依賴於低階模組。兩者都應該依賴抽象。

是的，不應該直接去依賴，而是必須藉由抽象來隔開。不應該直接去受到實作的影響，而是只要關注在所需要的功能。

這部分其實已經破梗完了，我們在介面篇已經說明過依賴反轉最基本的思維路線。我們並不是用低階模組的功能直接拼湊出高階模組，讓高階模組直接依賴低階模組然後受到影響；而是把關注點放在需要的功能上，用介面隔開實作，解開他們彼此之間的耦合，介面就是模組之間的抽象層。

同時也要明白一件重要的事：並不是高階模組去依賴低階模組。而是高階模組提出它需要的功能，低階模組去實作出這些功能、達成高階模組的目標。

我們並不是因為有「DB 的連線方法」和「處理會員資料的方法」所以才說「我們有這兩個東西欸，那我們來組成會員查詢功能吧」；而是「我們想做一個會員查詢功能，所以我們需要連線到 DB，然後對這些資料做篩選和處理」

就如同我們在介面的例子所提的一樣：「老闆為了製造產品（高階模組的目標），開出了工程師的應徵條件（介面），而小明前來應徵（低階模組的實作）」

如此一來，依賴就「反轉」了。

原本是 高階模組 → 低階模組 的關係，變成了 高階模組 → 介面 ← 低階模組。

並不是高階模組去依賴低階模組，而是低階模組去依賴高階模組所要求的功能。

這也就是依賴反轉原則的第二點：

抽象不應該依賴細節；細節應該依賴抽象。

到這邊我們就推完介面篇的前提了，請大家再回顧一下介面篇的內容。也就是說，上面的例子改用抽象層隔離之後，就會和介面篇的例子相同，變成：

public Product Work()
{
    IProgrammer programmer = new Ming();
    var product = programmer.Programming();
    return product;
}

控制反轉 (Inversion of Control, IoC) &
依賴注入 (Dependency Injection)

即使我們反轉了依賴關係，但總是要建立實例才能使用的呀。所以，只是將對具體的依賴更改為對抽象的依賴，仍然是不夠的，在要使用的瞬間就會遭遇到問題。面對這個問題，大大們提出了許多個解決的方法，今天就介紹一個比較常見的方向：控制反轉 (Inversion of Control, IoC)。

思路非常的簡單：既然如此，我們把實例的建立和實例的使用切分開來就好了，不再是由高階模組去建立並控制低階模組，而是我們讓一個控制反轉中心去建立低階模組，然後高階模組要使用的時候再把這個低階模組交給高階模組使用。

如此一來，控制權也跟著反轉過來了，高階模組從主動建立低階模組，變成被動接收低階模組；

也就是從原先的：高階模組 —(建立)→ 低階模組
變成了：高階模組 ←(傳遞低階模組)— 控制反轉中心

控制反轉的概念比較像是：當肚子餓的時候，如果自己煮菜的時候，必須自己備料、自己烹調、才能有東西吃。但如果去餐廳點餐，只要說出自己想要的餐點，店家就會負責備料，廚師就會烹調，最後就把需要的餐點送上桌來吃。

但是，要怎麼把控制中心建立的低階模組，交給高階模組做使用呢？這時候的實作方式就是我們所謂的 依賴注入 (Dependency Injection) 了。

依賴注入說穿了很簡單，就是用各種姿勢把東西丟進去給類別使用。

例如說我們先前提過的建構式，就是其中一種解決方法。用上面的例子，就會變成：

public class ProductService
{
    private IProgrammer _programmer;

    public ProductService(IProgrammer programmer)
    {
        this._programmer = programmer;
    }

    public Product Work()
    {
        var product = this._programmer.Programming();
        return product;
    }
}

在這個例子中，我們利用建構式的方式，從外部傳入該介面的實體來使用。現在撰寫產品程式碼的工作再也不用為了換工程師而改變，也不用因為實作細節或是方法名稱而煩惱，只要照個介面合約使用就可以了。至於要傳遞哪個實體進來，這份工作要交給小明還是小美，就讓控制中心去決定，大家各司其職，落實單一職責。

當然，注入的方式不只建構式注入，還有設值注入（也就是從外部改變目標的某個屬性值來達到注入）等等；提供 IOC 的方式也不只一種，例如 .net 的 Unity，甚至到了 .net Core 時代 IOC 還直接是內建的功能呢，由於口味眾多，此處暫且按下不表。

補充：下個系列文補了使用依賴注入 (Dependency Injection) 來解除強耦合吧，有興趣的朋友可以接續看看

結語

那麼，我們最後再來複習一遍：

高階模組不應該依賴於低階模組，兩者都應該依賴抽象。為了解除耦合，必須用介面這種抽象層進行隔離。

抽象不應該依賴細節。細節應該依賴抽象。介面應該是高階模組提出的要求，然後才去使用實作了這些要求的低階模組。這些實作應該圍繞著這些要求，而不是讓要求去配合實作，更不要讓要求中包含實作。

為了解決介面實例化仍然會產生依賴的問題，就有了控制反轉。把控制權交給第三方，藉此讓使用者能夠不用關心實例化的過程，而注重在使用並達成目標的職責上。

而控制反轉的具體實現方法是依賴注入，藉由從建構式傳遞、更改目標的屬性等方式，把低階模組交給高階模組使用者。當我們藉由依賴注入的方式實現控制反轉，就能夠讓物件的設計符合依賴反轉原則。

這個部份的做法還是挺複雜的，~~所以才拖稿這麼久~~，因此決定把原因的順序推過一遍，也算是幫自己重新了解一次。參考資料有蠻多篇我都相當喜歡，想更了解依賴反轉、控制反轉等等的朋友可以再自行閱讀。那麼，我們下次見～

本系列下一篇：菜雞與物件導向 (15): 最少知識原則

參考資料

同系列文章

7+ Taskbar Tweaker —— 簡單方便的 Windows 工作列調整工具

Igouist (Igouist) — Sun, 06 Dec 2020 23:49:00 +0800

故事是這樣的——

Win10 工作列的合併設定有這些選項：

當選擇「一律、隱藏標籤」時，工作列上同樣的程式就會摺疊起來：

而「永不」和「當工作列滿時」則會將工作列展開：

好的，那麼像我個性這麼麻煩的人，如果覺得顯示名字很佔位置，可是又不想要摺疊之後按兩次才能打開我要的應用程式，偏偏又很愛開一整排 IDE 的話，有沒有什麼簡單的辦法不要讓圖示合併，但也不要顯示名字呢？

如果有個小工具，可以讓這些工作列的設定更彈性就好了，會有嗎？

有的！

今天要記錄的是 7+ Taskbar Tweaker 這個小東東，他的畫面是長這樣的

可以調整的部分挺多的，可以隨個人喜好進行調整，從滑鼠操作工作列一路到時間要不要顯示秒都有。

例如我前面想要的需求，就可以把分組的部分改成「不分組」

這樣工作列的圖示就變成：

就是這樣！

另外如果對這些選項仍然不滿足的朋友，也可以右鍵開啟進階選項：

像我就有開啟大 icon，看了就是比較舒服

另外也能自訂一些滑鼠操作、鍵盤快速鍵等等，能微調的地方蠻多的，很適合有興趣的朋友可以自己研究看看。另外也要感謝巴哈的這篇徹底爆改多挖了很多小玩具可以玩，哈。

那麼今天就介紹到這裡，絕對不是玩小工具和逛耶誕城結果就廢掉沒寫文囧，抱歉啦催稿的碰油，我們下次見～

讀《離開公司，我過得還不錯》

Igouist (Igouist) — Sun, 29 Nov 2020 23:54:06 +0800

無論喜不喜歡自己的工作，都應該好好思考自己和工作的關係，畢竟每天花三分之一的時間做這件事，如果和它處得不好，人生也不可能會變好。

這本書並不是那種精神勝利法，又或是超猛接案全攻略之類的書；反而給我的感覺比較像是作者藉著這本書，分享他這一路摸索的心得，和遭遇到的一些困難，看的時候有種像在和作者聊聊天的感覺。

也因為這本書比較接近作者分享他選擇的道路、內容比較廣雜，遇到的部分都稍微說一些，但不是那種針對某個議題深入探討的書籍，所以比較適合想稍微了解自由工作的朋友閱讀。同時也必須了解到，自由工作者也只是眾多職業道路的其中一種，每個人的條件也不盡相同，因此抱持著好奇的心情閱讀，會更有收穫的感覺。

從博客來的書籍簡介就可以看到，目錄真的把自由工作遇到的議題都碰了一些：從適不適合接案工作，到報稅、勞保、合約、工作場所都聊了一點。因為真的挺廣的，這邊我就只記錄一些我比較感興趣的話題。

章節目錄

我們和工作之間的關係

本書最開始的時候作者敘述了他踏入自由工作的歷程：太過熱情工作、燃燒殆盡、失去熱情、休養了一年，最後重新思考人與工作之間的關係，才決定踏上接案的道路。

就像我這篇文章決定引用作者前輩說過的話作為開場，我也相當認同：不管你做什麼，工作在大多數人的生命中都佔了不少的份量。但我們真的有好好思考過我們和工作之間的關係嗎？有思考我們為什麼工作、想要什麼工作、適合什麼工作嗎？只要曾經思考過這些問題，就會明白我們和工作之間的關係，其實就是我們和生活之間的關係。而我們想要的工作，就是我們想要的生活。

當作者的前言問說：「總是人去符合職位的要求，把我們原本奇怪的形狀塞進方方正正的外框，身處職場當然不可能完全舒服，但，有沒有可能換個角度，從自己原本奇怪的形狀延伸，慢慢長出各種不同的工作」這倒讓我好像看到了黑馬思維的影子，黑馬思維也是要求我們要先了解自己的微動力，再根據自身去選擇策略。

因此，當作者接著說明上班的心態和接案的心態：上班打混過了一天也是一天的薪水，但接案為了生存就會講究效率；但上班相對比較穩定，有安心感，接案則是有做有錢沒做沒錢，兩者之間對於效率和時間的意義相當不同。從這開始，其實也就區分了適合接案和適合上班的人們了。

書中也有了一小段來接續這個話題，說明作者認為誰適合上班，誰又適合自由工作。上班相對於自由工作，有三個明顯的優勢：明確的社會位置、穩定的收入來源、勞基法保障的福利。因此，不確定想做什麼的朋友，或是喜歡穩定、安全的朋友就比較適合上班。

反過來說，自由工作者必須了解自己在社會中的位置，用專業來取代職稱，在開始接案的時候，也得要先找一件有趣的事情開始做，其他任務才會找上門來。也因此最好有點存款，才能保留接案時的選擇權等等。所以比較適合能承受不穩定性，又或是有想持續追求的目標的人。

要注意，這邊的承受不穩定性包含的心理和經濟能力等方面。例如作者的家人能夠經濟獨立，並且作者對工作的要求是能夠賺取生活所需的金錢讓他能夠自由做想做的事情即可，因此在衡量接案和上班之間的差異時，千萬別忘了要從自身的條件、想要的生活等方面開始估算。試著去想想兩者之間的條件，和自己比較傾向哪邊的生活。

即使最後發現此路不可行，但就像書中說的：「光是從不同角度去思考工作和自己的關係，換個視野看看職場十字路口的風景，也都會有收穫。」

自由與不自由

自由意味著責任，正因為如此，多數人都懼怕自由。

都說自由接案比較自由，但聽來聽去也不知道到底有多自由，曾經聽到唉呀那個接案的又出國玩啦，也曾聽到欸那個誰案子趕不完了好像三天沒睡了，總感覺這族群對我來說有點…太過動盪？所以「接案有多自由？」一直是我蠻有興趣的問題。

作者在書中也列出了幾項接案工作者的自由和不自由，例如能夠隨心所欲安排時間、能夠自己選擇案子、可能自己調整工作內容等等。同時也會有偷懶就沒有收入，必須維持工作成果等壓力。

但就像本節引用的這句「自由意味著責任」，為了能夠隨心所欲安排時間，必須先學會時間規劃，必須要能夠遵守紀律；為了能夠自己選擇案子，必須要維持住經濟水準，也必須要磨練專案到擁有話語權；為了能夠自己調整工作內容，就必須好好思考過工作和生活的比例，必須自己找到目標。所有的自由相對都需要先有所付出，因此自由並不是比較簡單的道路，而是學會對自己負責，還有可能餓死。

也因為這些責任，所以自由工作者必須具備一些能力，大多數作者都會在書中提到，例如：

在財務管理方面，就不能像領薪水的上班族一樣，每個月五號十號無腦等錢入帳，必須主動按照專案去管理每一筆帳。

而且通常是同時多個專案非同步地進行著，例如Ａ專案做到一半Ｂ專案開始，同時手上還有Ｃ專案準備啟動會議等等，這些專案簽訂的合約、入賬的時機也都有可能不同。

所以就必須學會掌握各個專案的進度和帳務狀況等等，所以自由接案者只能被迫好好學記帳，才能掌握住工作和款項的節奏，避免周轉不靈或是破產。

同時，既然都有可能多個專案非同步地進行了，為了能夠自由地工作和生活，也就必須好好把工作狀況記錄下來，回顧和規畫整體的時間。

就像公司前輩曾經說過的：能夠估算工時，也是工程師專業中的一環。那麼保持對時間的敏感度，把主導權拉回自己身上，自然也是自由工作者的一項專業與責任吧。

針對時間管理，作者認為應該從記錄開始，並提出了四個步驟：

每天記錄做了什麼
每周歸納整體工作
每月回顧時間使用狀況
每年檢討新目標

說實在的，我看到這段不自主驚呼，這不是子彈筆記的精神嗎？因此這邊就不再贅言，直接丟幾篇對我影響比較大的時間管理文章：

既然前面都計算了賺錢的效率，在選擇案子的時候，自然就會開始有所取捨。就如同書中所說的：什麼案子都接的話，跟在公司上班有什麼兩樣？

因此，就會劃分出賺錢與不賺錢的案子、有興趣和沒興趣的案子，甚至感覺不太對勁的案子等等。

在書中，作者的工作收入要求只要能維持生活即可，因此他會主動搭配賺錢的案子和比較有興趣的案子，讓自己邊維持生活又能有時間做有興趣的工作。

關於案件的選擇和搭配這部份，畢竟比較吃個人經驗，我就沒什麼特別的心得。但書中有個建議仍然值得參考：請相信直覺，當直覺有問題，那通常就真的有問題。

當你感覺到危，猶豫就會敗北。

除了上面這三項以外，還有許多篇幅用來說明工作場所、報價與合約等等，過於實際操作的部份，這邊就略過不提了。

重新定義

書中最後的篇幅，作者用自己的看法重新定義了生活、職涯、退休、成功等等話題。

其中有幾個部分我挺有興趣的，例如作者說：「在討論斜槓、自由工作時，有幾個前提條件得說清楚：只是兼差很多，卻沒有自己的熱情與專長，不能算斜槓；如果接一堆案子，卻沒有挑案子的自由、沒有安排時間的原則、說不出對工作和生活的想法，也稱不上是自由工作者。」

無情的接案機器，似乎也跟爆肝上班族沒什麼兩樣，都一樣沒有自由。接著作者又問：能否不依賴公司，以個人名義在職場生存？

從這些出發點思考，到「拿回人生的選擇權」就是作者對自由工作者的「自由」下的定義。

想要自由，也得先從思考生活和培養熱情、磨練專長開始。

不過這就像是書中提到的：「自由工作者憑什麼生存？小說家尼爾蓋曼（Neil Richard Gaiman）說，才華洋溢、交件準時、人好相處，是三項重要能力」並且，只要能符合其中兩項就足以好好生存了。

但這些能力，和上面能夠自由的條件，不管放到自由工作者或是職場，我個人覺得都是適用的，因為這些就是個人的軟實力。所以，不論你選擇上班工作，或是自由接案，終究還是要走向自我成長。

而成長的方向和道路何其多，又怎麼不讓人好好思考、好好摸索呢？

最後謝謝這本書，算是讓我思考了一個新的方向。書中其實還介紹了蠻多作者的心得和自由工作的一堆眉眉角角，也推薦有興趣的朋友可以讀看看，當作了解自由工作的入門磚，多多少少也會有收穫的吧。

這本書，描述的就是我的嘗試方法、犯錯教訓，還有交換的代價。不過我摸索出來的道路，也只是解開工作謎團的其中一條路線而已，每個人都可以有自己的路線，而且比我的更寬廣自在才對。

《離開公司，我過得還不錯：成為自由工作者的理想生活提案》

菜雞抓蟲: 在 Amazon Linux AMI 安裝 .Net Core 時卡在 Requires: openssl-libs

Igouist (Igouist) — Sun, 22 Nov 2020 23:40:00 +0800

最近遇到在 Amazon Linux AMI 要安裝 .net Core 3.1 環境的時候，會一直跳出
Requires: openssl-libs 而無法安裝的問題，儘管明明已經有 openssl 了，但還是解析失敗找不到依賴，過程一直碰壁，因此在這邊紀錄一下。

過程中嘗試了安裝 openssl-libs（會找不到該套件）、下載 Dotnet 的 tar.gz ，再直接對執行檔下 Dotnet 指令起站台（雖然網站起得來，但執行者會是當下的登入身分，也就是 ‘’@連線進來的IP-伺服器位置，而非由本機執行。後續如果有連線資料庫等檢查權限的地方就很容易出錯）

最後在 Dotnet Core 的 issue 翻到這篇 Cannot install .NET Core 2.0 on Amazon Linux AMI 才成功解決。

首先先將 openssl-libs 的 SPEC 抓下來，然後給 RPM 建置一下。這兩句可以參考一下這篇 RPM 打包︰由一竅不通到動手濫用 (二) 的說明。

wget https://github.com/dotnet/core/files/2186067/openssl-libs-ami.spec.txt
rpmbuild --bb openssl-libs-ami.spec.txt

接著我們去把打包好的 openssl-libs 安裝起來，路徑可能會有不同，所以記得先用 find 找一下

sudo find / -iname RPMS
sudo rpm -i /usr/src/rpm/RPMS/x86_64/openssl-libs-1.0.0-0.x86_64.rpm

到這邊應該就解決標題遇到的問題囉！讓我們回到安裝的正軌

sudo yum install -y powershell
sudo yum install dotnet-sdk-3.1.0

最後就可以 dotnet 試試囉！

菜雞與物件導向 (13): 介面隔離原則

Igouist (Igouist) — Sun, 15 Nov 2020 12:00:00 +0800

章節目錄

今天要記錄的是介面隔離原則，顧名思義是和介面高度相關的原則。因此在閱讀本篇之前，可能需要先對介面有一點了解呦。

事情就從上一篇里氏替換原則的鳥類物流公司開始說起。老闆痛定思痛，決定先用介面先規定好物流士們的應徵條件，例如裝貨、卸貨、飛行、必須有帥氣的喙等等。

這道命令下來後，倉庫們的企鵝都慌了，來檢查的編譯器瘋狂跳出 Error:「您未實作 IBird 的 Fly() 方法！」這下怎麼辦呢，為了要保住飯碗，企鵝們就必須實作出飛行才行，可是企鵝真的就不會飛呀！

這下子企鵝們只剩下兩個選擇：不實作飛行，但是就不能被當成物流士，最後就會被開除；或是……空實作。

public class Penguin : IBird
{
    public void Fly()
    {
      // Do nothing;
    }
}

企鵝們終於騙過了編譯器檢查員，然而當送貨的命令下來之後，企鵝們再一次卡在倉庫門口發呆，最終物流公司仍然踏上了虧損的老路，再度面臨倒閉危機…

介面隔離原則（Interface Segregation Principle）

不知道大家對企鵝遇到的狀況有沒有經驗呢？

當介面規定了太多要求，而我們實作的子類別只需要其中一部份，或是有些要求根本無法達成，就會發生這個困境：放棄實作介面，或是用空實作和錯誤處理去欺騙介面。

例如資料庫存取的介面要求太多和當下資料庫過於一致的方法，結果替換資料庫的時候導致部份方法實作不出來；或是像俺同事文章中的例子，交通工具的介面要求能開關車門，結果電動機車無法實作。

然而，如果我們選擇用空實作或是拋出錯誤的方式，去欺騙介面，等到需要呼叫該方法的時候，就會發生許多非預期的錯誤。甚至讓接手程式碼的人在什麼都不知道的情況之下就讓系統掛掉。聰明的朋友們一定發現了，這就是違反了里氏替換原則！

為了迴避到處都是空實作地雷的結局，大前輩們就提出了介面隔離原則：

不應該強迫用戶依賴它們未使用的方法

這邊的用戶也就是我們的子類別，它們等同是這個介面的使用者。當我們必須強迫使用者去實作一些他們不需要的方法時，就代表了一個事實：我們的介面太「胖」了！裡面的某些要求可能是非必要的，以至於造成了實作上的冗餘。

也基於這條原則延伸出了一個方向：應該最小化類別與類別之間的介面。

介面也要單一職責

但是，我們要怎麼知道是我們設計的介面太胖，還是子類別在偷懶呢？又要怎麼知道我們的介面設計是否已經「最小化」呢？

那就是單一職責原則出場的時候了。一個合理的介面設計是能夠符合單一職責原則的，反過來說，我們可以用單一職責原則來檢視我們的介面設計是否良好。

當我們設計介面的時候，或是像上面遇到必須空實作的時候，就可以思考一下：這個介面的職責是否單一？這個介面的意圖是什麼？這個介面是否只對一個角色負責、只有一個原因改變？

當我們的介面符合單一職責、足夠內聚的時候，我們自然就能夠說這個介面已經足夠精簡了。

用組合實現功能

有些人可能就會疑惑了：「但是我就是需要這個功能呀，如果我不塞在介面，要放去哪呢？」

很簡單，放去另一個該職責的介面就可以了。

和繼承需要注意的部分一樣，濫用介面也是濫用繼承，我們應該用組合去實現功能而不是用繼承去綁死功能。一個資料串列能做的功能可能相當多，但我們並不需要一次就要求實現全部能做的事情，而是將這些工作分組，再從中組合出我們需要的部份。

此處以 C# 來說，例如我們很常接觸的 List 類別，並不是只實作了 IList，而是實作了 ICollection<T>, IEnumerable<T>, IEnumerable, IList<T>, IReadOnlyCollection<T>, IReadOnlyList<T>, ICollection, IList 這些介面，層層堆疊，相互嵌合。

那我們就知道 List 由這些介面「組合」而成，也知道了我們 List 具有這些介面要求的能力，讓我們能在合適的時候使用這個類別。同時又保留了這些介面能搭配出另一種組合的彈性，例如 Array 就是由 ICollection, IEnumerable, IList, IStructuralComparable, IStructuralEquatable, ICloneable 組合而成。

就像可能有位大神，名片一拿出來就是一串「程式設計師／架構師／攝影師／貓奴」，我們的類別也要懂得斜槓。如此一來類別就比較不容易被介面綁死，也能因應不同場合來決定身分，從「每次都被逼著買套餐可是又不喜歡小菜」變成「餐餐自由配」，組合就該如此自由！

回到開頭的例子，把想要的行為全部定義在一個介面裡，然後用一個類別去實現它遇到不需要的動作就詐騙介面，是相當不 OK 的；而是應該把想要的行為用職責的角度去思考，根據職責建立成一或多個介面。然後只挑選並實作該類別需要的動作（介面），如此就可以讓介面不再臃腫，而是變得靈活。

就像是武術秘笈中的招式，其實也是一連串的動作所組成；所謂的功能，其實也是一連串行為所組成的。既然行為組合成了功能，我們也要從組合的角度去思考如何建立類別。組合就像是積木一樣，我們用積木堆疊來完成作品，同時每個積木又可以各自靈活運用。

而積木也分成了好用的積木，和很難使用的積木，在程式中可以從夠不夠 SOILD 看出來。不好用的那些用起來會覺得卡卡的，測試也很難寫；好用的則會讓你面對變化的時候，就像拆裝樂高一樣順手方便。聰明的朋友可能聯想到了，這就是開放封閉原則中我們提過的模組化。

通常來說積木的形狀越複雜、體積越大，就越難以靈活使用，介面也是如此，因此我們在設計介面的時候，要謹記介面隔離原則，利用我們在單一職責原則、里氏替換原則學到的原則來檢驗我們的介面，如此就可以迴避相當多尷尬兩難的實作場面，也能讓介面的使用更加靈活。

那麼，在結束之前，有興趣的朋友可以跟我一起想一想：介面隔離原則，只適用於設計類別架構時的介面嗎？其他的介面（Interface）呢？例如 API，是不是也可以按照介面隔離原則的精神下去設計呢？

後日談

企鵝詐騙介面的事情終究還是暴露了。

但是這群企鵝的夢想就是成為物流士，老闆也狠不下心把牠們趕走。

「也許……」鴨子顧問說：「我們可以有別的方法。只要使用介面隔離原則。」

老闆：『介面隔離？怎麼做呢？』

「我們可以把送貨放到 IDelivery，然後讓他們用不同的介面來實作移動方式，例如 IFly、ISwim、IRun 等等。用組合的方式來完成不同種類的物流士類別，這樣就可以有很多種送貨方式了」

『原來如此，不只是空運 —— 我們要征服陸海空嗎！』

改變作法的鳥禽物流公司搖身一變成了動物物流公司，同時廣徵天下動物，除了企鵝也能從南極發貨中心快速運貨以外，公司還招到了明星成員獵豹物流士，從此蒸蒸日上、強勢打入各大物流市場，最後進軍宇宙。可喜可賀，可喜可賀。

本系列下一篇：菜雞與物件導向 (14): 依賴反轉原則

參考資料

同系列文章

Dark Reader —— 暗黑模式愛好者的 Chrome 必備套件

Igouist (Igouist) — Sun, 08 Nov 2020 23:39:00 +0800

不能信任那些 Terminal 或編輯器用白底的人。
—— JokeKappa

這禮拜推薦了個常用的 chrome 套件給同樣喜歡黑色背景的同事，這邊也推薦給大家。

~~絕對不是因為隻狼更新了不小心砍太爽，結果來不及寫介面隔離只能介紹套件水一下，Heiya～~~

今天要介紹的就是這款 Dark Reader，這是我用 chrome 時首選的暗黑模式擴充套件，在俺寫文的這時候已經超過了三百萬次的下載次數，現在就讓我來記錄一下這款擴充套件的一些特色唄。

照慣例先上個預覽圖：

當我們安裝完成之後，就可以從 Chrome 右上角的擴充套件區看到 DarkReader 的 icon。點開就可以看到它的選單：

由上而下分別就是最常用的主要調整，左上角可以選擇是否套用，右上則是套件開啟關閉和快捷鍵。接著是一些對比度、亮度等等的調整，可以隨著個人喜好條找到舒適的程度。

其中我覺得最中意的就是最下面的「僅適用於ＯＯＯ」的功能，這代表我們可以將上面的設定僅僅針對某個特定網站作變更，而不會遇到在Ａ網站辛辛苦苦調整後覺得順眼了，結果到了Ｂ網站同樣的配置卻相當刺眼的狀況。

如此一來，對於某幾個常用的網站，我們完全可以自主微調再套用，甚至針對一些不太適合轉黑色的網站也能夠選擇關閉，這個彈性對我來說是相當實用的功能，幾乎是我最後愛用這款暗黑模式套件的主因。

這些紀錄是否要開啟黑色模式的網站，就會記錄在第二個「網站列表」的頁籤。雖然可以手動增加，但我個人是不常用到，在首頁設定即可。

而在第三個「更多」的頁籤，就有一些有趣的設定可以調整了：

首先是文字描邊的部分。由於黑暗主題下的白色字會讓人覺得字的筆劃較粗，因此大多時候字體就會經過調整。但如果覺得太超過了太細怎麼辦呢？這邊可以調整文字描邊，讓字看起來不要看不見，也不要過眩過粗。

再往下則是有四種模式可以設定，預設是動態模式，這邊直接上圖給各位感受一下：

過濾
過濾+

-靜態

-動態

其中靜態會有一個編輯畫面，可以自己加入 CSS 達到完全客製。

而動態則是就交給 Dark Reader 幫你算，像我這種懶人仔就是一路動態到底；像我這種會喜歡 One Dark Pro 主題，這類非純黑、漸層質感配色的人，動態的結果也比較符合我的口味。

當然，動態產生的 CSS 也是能修改的，點選下面的開發者工具就可以看到完整的 CSS 囉。像本部落格也是基於 maupassant 這款好看的白色主題，再加上 Dark Reader 處理後產生的暗黑模式當底來逐步修改出來的。這方面真的要感謝製作主題和套件的大大們呢。

今天的介紹就到這裡囉，推薦喜歡暗黑模式又想懶人用套件的朋友可以試試這款套件，真的相當好用！那麼，我們下次見～

菜雞與物件導向 (12): 里氏替換原則

Igouist (Igouist) — Sun, 01 Nov 2020 11:31:44 +0800

章節目錄

里氏替換原則 (Liskov Substitution Principle)

子類別必須能夠替換父類別

並且，子類別替換父類別後，不需要修改，也不該發生任何錯誤或異常。

從定義就可以看出來，這項原則是來替我們處理繼承問題的。因此，在開始本篇之前，可能需要先對繼承以及多型有基本的認識。如果可以的話，也請先看過介面。

那麼，就讓我們從很久很久以前開始說起…

我的子類別進入叛逆期了，怎麼辦？

很久很久以前，有一間公司受到鴿子封包所啟發，打算發展鳥類運輸技術，強勢打入無人機市場，用生物智慧掀起對人工智慧的革命。既然鳥類都會飛行，理所當然可以藉由飛行來進行空運，甚至還可以偷偷擊墜那些無人機對手，野心勃勃的老闆立馬徵了一批鳥類物流士，打出「凡是鳥類都可應徵」的旗號，各式各樣的猛禽響應而來，一時之間掀起整個物流業的風暴！

但是好景不常，公司營運之後發貨狀況不佳，頻繁發生丟包問題，甚至有些貨根本就出不了倉庫，虧損越來越大，心急如焚的老闆下令徹查，這才發現—

企鵝是鳥，企鵝不會飛。一堆企鵝在倉庫門口發呆。

但是一切已經來不及，虧損已經造成，這家鳥禽物流公司最後也慢慢消失在塵埃之中……

這個故事告訴我們：如果子類別（企鵝）沒有達到我們對父類別（鳥）的期待，就很容易在不知不覺中出事！

我們已經預期了「鳥＝會飛行」這個前提，但繼承的企鵝卻無法實作飛行，如此就會讓我們被誤導、在使用時誤入陷阱。這種子類繼承時搞叛逆，和父類別行為相違所發生的問題，難以預期也難以察覺，絕對是我輩不能容忍的。因此，里氏替換原則就出現了。

註：感謝這篇里氏替換原則 Liskov Substitution Principle (LSP) - Finn 的附圖，我之後就想不出比企鵝更貼切的例子了囧

所以，我們該如何遵守里氏替換原則？

我們再提一次：子類別必須要能替換掉父類別，而不需要改變。

我們在多型篇的時候提過「用子類別實作出各式各樣不同的方法，藉此讓父類別的方法藉此達到延伸和多樣化的效果」如此我們的物件彼此之間才能保持彈性，擁有可替換可擴充的特性，進而達到開放封閉原則所要求的：對修改封閉（不需要修改使用到父類別的地方），對擴展開放（而是只需要用子類別進行擴充，就能完成變動）

然而，這個擴展不該是天馬行空隨便亂擴的，必須要有原則。

最首要的就是：至少父類別能做到的事情，子類別也要能做到，不能說今天換成子類別就整組壞光光。畢竟，如果原本的東西變少了或壞掉了，那就不叫延伸了，對吧？

也就是說，一個好的擴展方式，應該能滿足這些條件：

要求不應該比父類別多
回饋不應該比父類別少

例如說：爸爸每天都去市場賣香蕉，一支二十，數十年間颳風下雨從未改變。某一天爸爸生病，不想打破這個傳統，就請兒子去代班。這時：

熟客們知道一支是二十元，他們順路來買香蕉的時候也只會準備二十元。
所以，兒子不能亂漲價到五十元，因為客人也拿不出來，而且臨時漲價還會被留負評
熟客們知道給了錢就可以拿到香蕉，他們給了錢之後就會等著老闆把香蕉給他們。
所以，兒子不能收了人家二十元，然後只給半支香蕉，客人會很傻眼，攤子會很危險

這些熟客，其實就是我們工程師。我們預期了這個函式或類別需要準備的輸入參數，也預期了應該要有的輸出結果。如果某一天替換了子類別，卻不是這麼一回事，就會發生很多意料外的錯誤。對買香蕉這件事而言：

給足夠的錢就是所謂的「前置條件」或「先驗條件」
預期拿到香蕉就是「後置條件」或「後驗條件」，
每天都會去市場賣香蕉就是「不變條件」

因此當我們想要符合里氏替換原則時候，其實就可以試著遵守這幾條規則：

先驗條件不可以強化：
父類別要求的是矩形，子類別就不能要求得更嚴，只准人家給正方形

後驗條件不可以弱化：
父類別產出的是正方形，子類別不能說沒關係啦，就給人家隨便一個矩形

不變條件必須保持不變：
父類別是一個產生矩形的方法，子類別不能背骨，跑去產生圓形

只要確保了輸入和輸出都是一致的，就可以減少很多神奇妙妙問題。這個也就是所謂的契約式設計 (Design By Contract)。

稍微想一想，你可以不要（隨便）繼承

有沒有發現，這個契約式的描述，和我們提過的介面概念是不是很像呢？可以稍微想一想：介面和繼承間的關係，以及介面與里氏替換原則的關係。

首先，為什麼我們要使用繼承呢？如果只是為了減少重複程式碼，那實在是，呃，相當不建議。

這邊需要了解一個觀念：我們不應該因為單純的「IS-A」就濫用繼承，那樣是危險的。企鵝「是」鳥類、正方形「是」矩形，在想法上似乎是沒有問題的，但是貿然繼承就會遇到「企鵝不會飛」、「正方形四邊等長」等問題，讓實作上有種綁手綁腳的感覺。

真正的繼承應該是基於行為的：這個子類別能不能做到父類別期望的行為？這才是里氏替換原則的核心。

不要用繼承去掠奪父類的程式碼，而是把目光放在行為，試著去思考父類別期望的行為是什麼、哪些是不可變的；期望的前置條件、後置條件，也就是輸入和輸出又代表什麼。

當我們需要繼承時，就稍微想一想，把觀看物件的角度集中在它的功能上，去試著了解父類別所期望的繼承方式，和使用者期望的預期結果。如此一來，我們自然就會朝向遵守契約式設計精神的介面來取代繼承，又或是釐清功能之間的職責，利用組合各個功能的子模組的方式來完成我們要的行為。

放下繼承的包袱，了解繼承的原則，才能真正達到多型的精神，這就是里氏替換原則替我們指引出的方向。

既然我們需要用到介面，那介面又有什麼要注意的地方呢？這就要到我們的介面隔離原則再聊了。欲知後續如何，且待下回分曉。

那麼，我們下次見～

本文主要參考至這幾篇，建議想對里氏替換原則更了解的朋友可以閱讀一下呦：

物件導向設計原則：里氏替換原則，定義、解析 - WadeHuang的學習迷航記

使人瘋狂的 SOLID 原則：里氏替換原則 (Liskov Substitution Principle) - 程式愛好者

本系列下一篇：菜雞與物件導向 (13): 介面隔離原則

參考資料

同系列文章

菜雞與物件導向 (11): 開放封閉原則

Igouist (Igouist) — Sun, 25 Oct 2020 11:58:00 +0800

章節目錄

開放封閉原則 (Open-Close Principle)

軟體實體（類別、模組、函式等等）應該對擴展開放，而對修改封閉

在我們了解什麼是「對擴展開放」和「對修改封閉」之前，先讓我們談談：什麼是擴展，什麼又是修改呢？

用白話一點的方式來形容，修改就是把東西拆開來改，像是手術；而擴展就是對東西額外加裝模組，像是添購設備。我們用飛行來舉例，像是鳥類直接用翅膀飛行，如果有需要修改飛行方法的話就得對鳥直接進行手術；但如果今天是一個裝備了噴射背包的人，我們只需要把噴射背包換成噴射鞋子、甚至噴射翅膀就可以了，不需要去修改人這個本體。

這邊可以發現開放封閉原則是針對「改變的時候」去做一個行動的建議，例如需求追加和變更等等。凡是變化都有成本，例如變動的難易度、變動造成的影響範圍等等都會影響到成本，若是程式碼冗長、內部邏輯複雜，類別之間互相耦合、影響範圍很廣，導致綁手綁腳或壞東壞西等等狀況，使得修改很困難，成本就會變高，進而使得開發效率變低。

然而，軟體並不是製造完畢就完工的東西，而是隨需求而生、隨需求而變的動態作品，因此程式碼的修改或重構相當頻繁。就像我們在內聚耦合篇提過的：軟體面對改變的能力，就像基因適應環境並生存下去的能力。因此，程式必須具有彈性，也就是需要盡可能降低修改的成本。

那麼讓我們回到前面：動手術跟換道具，哪個的成本比較高呢？

面對需求，對程式碼的改動是透過增加新程式碼進行的，而不是更改現有的程式碼　　
（《大話設計模式》）

所以，我們希望能夠用擴充的方式去完成變化，而不是用針對內部進行修改的方式來做；希望藉由良好的設計，能迴避上面那串修改困難導致成本高昂的問題。

而這個思路，其實你我都已經很習以為常了，就是模組化。

模組化

組裝電腦的時候，就是針對主機板加裝各種模組；寫程式的時候，我們也很習慣引入套件來使用；甚至使用 Visual Studio 或是 Chrome 這類軟體的時候，我們也都會使用擴充套件來加上我們需要的功能。甚至洛克人也是，我們打倒 BOSS 之後就能替洛克人加裝各種模組，讓他能夠具備各個 BOSS 的功能。噢當然我們不會把整台洛克人拆開然後改造成另一台，不然拆來拆去多麻煩。

我們的周遭四處可見模組化，用模組來擴充本體的想法自古以來比比皆然。

這邊就可以發現到：主機板上面事先會留好許多讓你接顯示卡或記憶體等等的插槽、Chrome 這類軟體會開放 API 和權限等功能給擴充套件來使用。當我們想要利用擴展的方式來擴充本體的能力時，我們需要留下一個供對接的地方，也就是擴充點。

擴充點可以說是留給後人的貼心禮物（跟另一種留給後人的炸死人禮物並不相同）但是，我們要怎麼知道哪些地方可以擴充、可能擴充呢？我們可以先區分主要邏輯和附加邏輯，像是洛克人跟技能，你和噴射背包，又或者是「查詢客戶」的主邏輯和各種不同「查詢客戶的條件」等等的組合。

因為如果不加以區分，我們就沒辦法把附加邏輯做成模組，也就找不到主要邏輯和附加邏輯之間的擴充點，如此一來就勢必要針對混成一坨的邏輯做修改和業務處理，接著就會落入我們在上一篇單一職責原則提過的各種悲慘下場：修改一個地方影響一狗票功能、修改前必須痛苦地閱讀大量不相關的程式碼…等等。

這些問題，也正是單一職責原則所要解決的。此處可以直接參考上一篇也引用過的再談物件導向設計原則: 單一職責原則，定義、解析與實踐這篇，裡面的學生列表例子就蠻直接好懂的。

另外也必須推薦一下這位大大的物件導向設計原則：開放封閉原則，定義、解析與實踐，對業務邏輯和附加邏輯的說明也相當明確，從為什麼要隔離兩者，到如何實踐都有說明，值得一看。

而我們辨認出主要邏輯跟附加邏輯之後，該怎麼實行開放封閉原則呢？

實行

答案就是抽象。（《無瑕的程式碼：敏捷完整篇》）

這邊舉幾個方向：我們可以在主要邏輯和附加邏輯之間，加入抽象層來解耦合，也就是我們介面大哥該出場的時候了。當我們的類別不再堅持依賴某個物件，例如說我就是要噴射背包，然後把背包黏死在背後；而是接受我只需要能飛的東西，不論傳遞進來的是噴射背包還是噴射鞋子，如此一來就夠用介面表達出需求，使得功能可以被任何符合需求的方式擴展。

另外還有，使用外部注入來處理附加邏輯。除了不將附加邏輯寫在類別中，降低修改的機會以外，和介面的邏輯一致：你給什麼工具我就用什麼工具。當我們的附加邏輯是從外部丟給類別，使得類別預先留好擴充點，並且能由外部決定擴充方式，要擴展也就相當容易了。順便一提，我進公司學習以來，注入跟介面通常都是一起出現的 Combo 技。

當我們在設置我們的擴充點（上個世紀稱作「放置鉤子」）時，有時會預測失敗，變成不必要的複雜性。也很容易走火入魔，就變成過度設計。因此，我們最終會等到足夠確信將會變化時，才進行重構的動作。

在無瑕的程式碼中，建議可以接受「被愚弄一次」，先假設不會變化，而當真的變化到來時，就將該變化相關的部份重構抽象起來，得了一次病，從此就免疫，還可以少走冤枉路。又或許，也可以嘗試看看三次原則。

2024.09 補充：
看見 Huanlin 大大寫了這篇避免過早的抽象設計，覺得和「被愚弄一次」的精神相似。最近也在體會過早抽象帶來的痛苦，決定把這篇補充回來，給正在認識 OCP 的朋朋們參考。

OCP 能幫助我們思考並寫出乾淨彈性的程式碼，但切記不要走火入魔，否則反而會帶來更多維護的成本。謹記三次重構原則，保一世平安，阿彌陀佛。

結語

最後，開放封閉原則的範圍實在是太大了。事實上，其他設計原則，例如單一職責、依賴反轉等等，都是為了達到開放封閉這個終極的目標而產生的。但是，我們不可能預測到所有變化，也沒有任何做法能夠適用於所有狀況，因此要達到完全的封閉是不可能的。然而，這是我們應當嘗試精進的目標，只要謹記開放封閉原則，就能不斷改善架構，也就離良好的設計更進一步了。

而對我而言，開放封閉的好處在於強迫像我這樣的工程師去思考：哪些地方是附加邏輯，哪些地方可以留作擴充，又該怎麼做才能方便擴充，這個過程和嘗試對我輩菜鳥才是真正最有價值的地方吧。

最後感謝一下 Ray 大大的路過指點。我當時問了不知道怎麼形容開放封閉原則，大大就說了個例子：咱們人哪，學新東西可是比改個性來得簡單多了。也基於這個例子讓我想到了手術和洛克人，還有變動的難易度、本性（核心邏輯）和新技能（附加邏輯）的差別可以這樣咻咻地串起來，這邊就謝過啦。順便也貼下大大的 Blog，加減蹭一下。

本系列下一篇：菜雞與物件導向 (12): 里氏替換原則

參考資料

同系列文章

菜雞的 Markdown 筆記

Igouist (Igouist) — Sun, 18 Oct 2020 22:00:00 +0800

Markdown 是一種寫作用語言，特色是只要用簡單的符號就可以替文章進行排版，例如 # 就代表了標題，因此能相當簡潔迅速地應用 Markdown 語法來撰寫出文件，目前已經被廣泛使用在各個撰寫文章或是文檔的場景中。

例如 Github 用來說明專案的 Readme.md，從副檔名 md 就已經告訴你這是一篇 Markdown；又像是這個部落格的文章，也都是使用 markdown 來寫的。除此之外，像是 Facebook 和 Line 都開始支援簡單的 Markdown 語法了 —— 因為它實在是太方便好用了。

使用Markdown格式撰寫的文件應該可以直接以純文字發佈，並且看起來不會像是由許多標籤或是格式指令所構成 —— markdown.tw

既然用簡單的符號就能完成這些簡潔的排版，我們自然就能把專注的重心挪回到撰寫文章本身，這也就是 Markdown 最大的魅力：專注於內容。

也因為 Markdown 的特色就是非常的簡潔乾淨，文檔本身的可讀性就相當的高，撰寫起來也很直覺容易。就如同其說明文件所說的：「Markdown 的目標就是實現『易讀易寫』」

這篇就來稍微紀錄一下 Markdown 的常用語法和好用的編輯環境吧！

章節目錄

語法

標題

Markdown 中要加入標題，只需要在開頭加上 # 就可以了。

# 標題一 H1
## 標題二 H2
### 標題三 H3
#### 標題四 H4
##### 標題五 H5

或是使用底線標示的方式也可以告訴 Markdown 這是標題，例如：

標題一 H1
========

標題二 H2
--------

分隔線

如果是想區分段落，不想要輸入標題，也可以直接用分隔線 ---，但記得要空一行，不然會被誤認為標題，例如：

我是紅海

---

我是紅海

斜體

當我們需要斜體的時候，可以用 * 或 _ 來將文字包起來，例如：

我是 *斜體* 啦！會有一點 _斜斜的_

粗體

當如果需要強調某個語句或段落，則可以用 ** 或是 __ 來將文字包起來，例如：

我是 **粗體** 啦！這一段 __很重要__ 哦！

列表

列表分為有序和無序，其中有序的使用數字加上點來標示，例如：

1. 我是第一項
    1. 我是第一項的第一小項
    2. 我是第一項的第二小項
2. 我是第二項
3. 我是第三項

而無序清單則可以用 +, -, * 來標示，例如：

- 蘋果
- 柳橙
- 香蕉
    - 香蕉？
    - 香蕉！
- 水蜜桃

核取方塊

當我們需要建立待辦事項這類需要勾選的列表時，就可以考慮用核取方塊 [ ] 和 [x]：

- [ ] 買蘋果
- [ ] 買柳橙
- [x] 買香蕉

引用

需要引用某個片段或特別標示的時候，可以用 >，例如：> 我是一句名言

紙上得來終覺淺，絕知此事要躬行

大多數平台也會支援巢狀的用法，例如：

子非魚，安知魚之樂？

子非我，安知我不知魚之樂？

連結

需要加入連結的時候，可以使用 [連結文字](網址)，例如當我要插入 Markdown.tw 的說明時就可以：

請參見 [Markdown 語法說明](https://markdown.tw/)

圖片

當連結是圖片的時候，只需要在最前面加入 ! 變成 ![](圖片網址) 就可以囉，例如：

![](https://avatars2.githubusercontent.com/u/16403463?s=460&u=fccdf65b21cb2dc5c544c3b473f135f00c574030&v=4)

就會跑出我家的貓（插入圖片也太難擷取成示意圖了吧，各位意會就好）

表格

表格應該是我在 Markdown 中覺得不太親切的東西了…

其實就是要你直接畫一個表格出來（排版請見諒，已盡力）：

| 水果名稱 | 好吃程度 | 昂貴程度 | 爆炸程度 |
| --- | --- | --- | --- |
| 蘋果 | 高 | 高 | 高 |
| 香蕉 | 中 | 低 | 無 |

也可以設定置中或靠右，例如：

| 靠左 | 置中 | 靠右 |
| :--- | :---: | ---: |
| 芭樂 | 奇異果 | 蓮霧 |

程式碼區塊

程式碼區塊使用反引號 `，就是鍵盤左上角那個。如果只用一對把文字包起來就會是單行，例如：

你可以使用 `Hello()` 這個語法來打招呼

而如果用三個反引號為一組，就可以產生程式碼區塊，例如：

有些平台會支援程式碼上色，這時候只要在第一組反引號後面加上程式語言就可以上色，例如：

static void Main(string[] args)
{
    Console.WriteLine("Hello World!");
}

另外有些平台也支援行號顯示，像 Hackmd 只需要在反組號的程式語言後加上等號就會顯示行號，例如 csharp=，而我現在用的部落格主題，則是要到 config 統一配置才會顯示。

由於 Markdown 力求簡潔，所以這些比較延伸的語法，通常需要看一下使用的編輯器是怎麼支援的。

其他

另外隨著平台的支援，可能還有提供其他語法。例如用一或是兩個 ~ 將文字包起來就常用於表達刪除號。提供寫作的平台多少都會有說明，開工前可以先翻翻看，畢竟語法糖不嫌多嘛。

工具

接著讓我們介紹一些撰寫 Markdown 時的方便工具，以下這些是我比較常接觸的 Markdown 編輯環境，如果有什麼也挺不錯的還請告訴我一聲呦

Hackmd

Hackmd 一定是必須推薦的！它是我目前做為主力的 Markdown 編輯器，它能夠：

提供了方便的線上編輯環境，能用雙欄同時編輯和檢視
多人協作
貼上圖片自動上傳到 imgur
可以嵌入 Youtube 影片等等
將 md 檔直接儲存到 Github 或 Dropbox 等等空間
可以使用語法直接產生 LaTeX、UML、流程圖甚至五線譜

另外還能夠將筆記分享給其他人，或是直接公開到網路上，甚至將筆記整理起來整理成書本。

支援的用法相當多，打開瀏覽器就能用，可以說是使用 Mackdown 寫作的工具首選！甚至不少人直接當成團隊文檔庫或部落格在使用。有興趣的朋友，就從它的使用教學開始試試吧！

Typora

對我來說最方便的 Markdown 寫作環境是 Hackmd 的話，那最美的 Markdown 寫作環境就是 Typora 了。直接前往 Typora 的網站就可以感受到它的那種極簡風格。

另外 Typora 也支持使用自訂主題，只要從設定中打開主題資料夾，把 CSS 丟進去就好了，因此可以上社群（例如熟悉的 One Dark）甚至自製主題來讓編輯器更好看。

Typora 也支援將文檔製作成 PDF 的功能，並且這個 PDF 是吃得到主題的 CSS 的！像我自己的履歷表就是用 Typora 寫完之後，調整 CSS 直接壓成 PDF 的，這邊也推薦給大家。

改得順眼之後只能用舒服優雅來形容，寫起來都賞心悅目了，推薦熟悉 Markdown 語法之後可以試試。

但記得要先去偏好設定改成一體化視窗，並且去主題資料夾稍微修改一下字型讓中文舒服一點，像附圖就是使用了更紗黑體。

整體來說，如果你要去咖啡廳之類的寫文章，那就真的可以帶 Typora 回去改個自己喜歡的主題，真的舒服。

更新: Typera 也有主題下載頁囉！可以從 設定 → 偏好設定 前往

或是直接到 https://theme.typora.io/ 下載主題

這邊也推薦一組很棒的主題：DrakeTyporaTheme

補充: 想要跟 HackMD 一樣能夠直接貼上圖片上傳的朋友，也可以參考這兩篇：

Typora 自動上傳圖片到 imgur (for Mac)

Windows 下采用 Typora + PicGo 搭建 Markdown 图床

Visual Studio Code

~~那真是太諷刺了紹安~~，繞了一圈最後最常用的還是 Visual Studio Code 直接開寫，畢竟 Hugo 寫部落格的時候也是在本機寫好推上去，過一陣子就懶得開東開西，只想直接開工。所以還是直接用 VSCode 最快了。

安裝一下 Markdown 的套件之後就能直接開工了，我個人是安裝 Markdown All in One，該有的都有了。

不過上面的 Hackmd 也有推出 VScode 用的 Hackmd 套件包，像上面提到的繪製流程圖、數學式等功能也包含在內，有這類需求的朋友也可以使用看看。

補充: 想要跟 HackMD 一樣能夠直接貼上圖片上傳的朋友，也可以試試 vscode-imgur 這套插件呦

總結

這篇記錄了一些常用的 Markdown 語法，並且推薦了三款 Markdown 編輯器，有興趣的朋友可以嘗試用 Markdown 打打文章或是規範文檔，相信一定能感受到 Markdown 的魅力。那麼，我們下周見～

參考資料

外接螢幕初體驗

Igouist (Igouist) — Sun, 11 Oct 2020 23:50:17 +0800

這週入手了新玩具，在這邊記錄下～

~~我們家大神大大跟我說部落格就當推特發就對了，唉呀我也是深表認同吶~~

像我這種被實驗室和公司寵壞的人，已經習慣了雙螢幕的好。結果不管是在放不下兩台螢幕的家裡書桌，還是帶著筆電出門，尤其是一邊寫東西一邊查資料，需要來來回回切換視窗時，總是會想「唉呀真想把這丟到另一個螢幕啊！」

因此！幾經掙扎之後，還是入手了外接螢幕！

開場先說心得，雖然尚未有外出機會，但目前的使用相當滿意。這邊就說說個人體會的好壞：

2021.01.30 補充：外出也相當方便，只是桌面的空間就需要大一點

外接螢幕的讚

有雙螢幕很爽
可以攜帶出門，到圖書館之類的地方也能有雙螢幕很爽
雙螢幕在一邊 Coding 一邊 ~~抄Stackoverflow~~ 查資料，或是像部落格一邊編輯一邊看結果的時候很爽

其實整個說起來就是帶著筆電也能雙螢幕的那種爽感，一旦用過雙螢幕，感受到不用一直切換視窗的流暢感之後，就真的回不去啦。

外接螢幕的沒那麼讚

加上保護套之後幾乎都要一公斤左右，不太能忽視
出門在外還要接一堆線有時候不太美觀
背包裏面又是筆電又是螢幕又是手機錢包的，身家財產哪！包包離開視線就會心神不寧

誰適合用外接螢幕

有出外工作習慣，例如跑去咖啡廳帥一天的朋友們
像我一樣桌電筆電交替使用的朋友們
只是想要出門用大螢幕打 Switch 的朋友們

大概先這樣，推特也有字數限制呢。等有外出機會還是有什麼心得再來補充一下，先去享受新玩具了這週也是今年最後一個連假了，各位開工愉快，咱們下周見

補充一下：我個人入手的型號是 MSI Optix MAG161V，算是相當輕便好看。線材接的位置也挺不錯的，螢幕看著也挺舒服。

Google 一下也有挺多開箱文和介紹影片的，有興趣可以看看。我這真拍不出像樣的開箱文，太難了，我嘗試過了…。這邊就推薦一下外接螢幕這東西，有興趣的朋友再自己做功課吧～

菜雞與物件導向 (10): 單一職責原則

Igouist (Igouist) — Fri, 02 Oct 2020 11:03:00 +0800

我們在前面的內聚和耦合有提到過，內聚並不是無腦把相關的程式碼都封在一起就好了，也有分成健康的和不健康的。但我們要怎麼知道這個類別是否足夠健康呢？單一職責原則就是很好的檢驗方式，這篇就讓我們來紀錄一下。

章節目錄

單一職責原則 (Single Responsibility Principle)

「單一職責」原則顧名思義，就是一個類別應該只負責一個職責。

但是這樣太過籠統了，「職責」相當容易產生誤會，容易變成各說各話。~~畢竟咱們工程師最愛戰定義了嘛。~~

「你這類別不優，它有兩個職責！登入跟登出！」

『沒有啦，我這個類別就是負責帳戶管理的啊』

「OSSO。乾脆你全部放一起，然後說是負責網站管理算了，呵」

『……你存心來找碴的是不是？』

為了避免像這樣產生職場糾紛，我們需要先定義一下什麼是「職責」。經過前輩們的努力（解釋）之後，單一職責的定義就成了：

就一個類別而言，應該只有一個引起它變化的原因

另外，我也看過「一個類別應該只對一個角色負責」的說法，這兩者的核心概念是一樣的。

這邊讓我們簡單舉個例子。如果在訂單管理的類別中有一個新增訂單的方法，在收到訂單之後，會依序處理訂單、並取出會員的聯絡資訊，再依靠聯絡資訊寄送通知信件給會員。但它的實作全靠自己來，如下：

新增訂單()
{
   // 收到訂單
   /*
     一些訂單的商業邏輯
   */

   // 寫入訂單
   /*
     一些和資料庫連線寫入資料的處理
   */

   // 取得聯絡資訊
   /*
     一些連到資料表或服務拿會員資料的處理
   */

   // 寄送通知
   /*
     一些寄送信件的處理，如寄送者和寄送方式等等
   */
}

這樣一路就是流水帳打完收工，這樣的一個函式參雜了一堆不相干的邏輯，可能動輒數百行，每一段都處理各種不同的工作，一看就很明顯違反單一職責原則。

當訂單處理的商業邏輯、查詢會員資料的邏輯或是通知會員的方式有變更的時候，這個函式都會受到影響，也就是說這個函式同時對多個不同對象負責。這樣的類別或函式就是不穩定的。

遇到這種情況，我們可以將其拆分。讓上帝的歸上帝，讓凱薩的歸凱薩。

例如說會員的處理一律封裝回會員管理類別，我們再藉由會員管理類別去調用其方法取回資料；寄送信件也封裝到通知管理類別，不用去管用什麼方法通知的，我們只需要去要求其通知即可。

有些朋友可能會有疑問，這樣不就會和會員處理類別、通知管理類別之類的其他類別有了耦合關係嗎？有這樣的疑問是很合理的，這也就是為什麼我們會需要介面來讓類別之間不要直接彼此依賴，這部份我們在介面有詳細介紹。

新增訂單(訂單)
{
    處理訂單商業邏輯(訂單)

    訂單資料存取服務.儲存訂單() // 可能由資料存取層或連線管理等該職責的地方去實現

    通知服務.寄送訂單通知(訂單.訂購人編號)
}

處理訂單商業邏輯(訂單)
{
   // 專注在處理商業邏輯，不用管其他事
}

// 其他的職責拆分出去給負責該工作的類別
通知服務 { 寄送訂單通知(編號); }
訂單資料存取服務 { 儲存訂單(); }

我們把工作交給負責該職責的類別去做，自己只需要關注在自己正在處理的職責即可。聰明的朋友可能已經注意到了，這就是封裝的體現。封裝得夠舒服，我們就能舒服地處理自己的事情就好，這就是分工合作的偉大呀。

2022.01.23 補充：

前面提到的「職責」的部分，雖然我們前面提過了是「引起變化的原因」，但可能還是太過模糊，~~畢竟咱們工程師真的最愛戰定義了嘛。~~

今天在群組裡有前輩分享了講解單一職責原則的影片：Fred 聊聊 SOLID 設計原則，其中單一職責的部份，將前述的「引起變化」從業務需求變更的方式切入

影片中用實例來說明什麼時候該切分職責和其重點，例如 「業務耦合造成的問題就是職責不明確」、「不要讓類別去碰它不該做的事情等等」 ，我個人覺得非常不錯，推薦給想更了解單一職責原則或 SOLID 的朋友

雖然文章中的例子相對簡單。但有一個部份我個人覺得要特別注意：單一職責當然也可以用在函式上。甚至資料表或任何需要管理、分類抽象事物的東西上。

有些朋友可能跟我前陣子一樣，覺得函式就是用來消除重複的程式碼，直到我看了可不可以不要寫糙 code 和一句「難道只有重複才需要做成 Function 嗎？」才明白：函式真正的工作其實是封裝邏輯。

既然是封裝邏輯這種抽象的東西，必然也會有其職責，自然也得好好注意單一職責囉。

走向單一職責

我們可以從上面的差別重新思考，遵守與不遵守單一職責原則會有哪些顯著的差異。

當我們並未遵守單一職責原則時，同個類別裡面充斥著不同工作的處理邏輯。也就是不健康的內聚：完全不夠聚，就只是盤散沙。

容易產生意外的重複。每個類別每個方法都自己去查詢會員資料，當查詢會員資料的方式或規則有變更的時候，影響範圍就會非常大，同樣的事情有一大堆地方要改，還得要先全部找出來，想到就頭痛。
同時我們在修改時也無法界定邊界，無法確定這次修改影響到的範圍，我們並不知道這些放在一起的東西，或是同一段做的所有事之間是否會相互影響，這將導致每次修改的時候都在挑戰我們自己的心臟負荷量，讓維護變成試膽大會，類別變成危樓改建。
承上，我們為了要確保修改沒有問題，我們必須大量閱讀不相關的程式碼，無形中造成開發負擔，降低開發效率。

如果你曾經有閱讀別人的程式碼，卻始終看不懂這東西到底在幹嘛，每分鐘髒話數筆直上升的經驗。答應我，我們不要讓別人經歷相同的悲劇，我們要斬斷仇恨的鎖鏈。我們，今天就開始走向單一職責。

當我們終於選擇單一職責，我們的類別才能真的擁有健康的高內聚。以上的這些問題，也都變成：

每個類別都專注在自己職責上，需要這個功能的其他類別就能來使用。大大提高了程式碼的重複使用程度，同時也降低了程式碼的重複性。並且因為類別內都是朝同樣職責前進的成員，彼此關聯性相當高，因此也提高了內聚。這兩點讓我們能迴避掉「要改的地方太多了，就改天吧」的悲傷結局。
同時，當我們要修改時，只需要找到負責的類別修改。因為已經把不屬於職責的工作交給其他類別了，達到了封裝和隔離，所以我們就能輕鬆看出修改的區域和邏輯，並較少地被不相干的東西影響、馬上掌握修改的目標和影響範圍，使得架構和類別更容易管理。也就是說，單一職責可以達到降低耦合的效果。

展現你的意圖

單一職責讓我想到前陣子看的《先問為什麼》中的芹菜測試：當你在超市結帳時，手上拿著巧克力、豆漿、餅乾跟芹菜，沒有人看得出來你到底要幹嘛。

寫程式也是如此，如果你的類別或方法裡什麼都要，彼此間又甚無關連，那就沒人看得懂這到底是幹嘛的。

如果團隊的其他人不能瞭解這個類別的職責，那後續協助修改的時候就會沒辦法把相同工作的程式碼歸類在一起，甚至難以修改，做起事綁手綁腳，新增個方法都會陷入混亂。整個架構就會開始腐敗。這也就是為什麼我們需要保持程式碼的可讀性，並且盡力實踐單一職責。

如同我在先問為什麼文中所引用的「你的一言一行，都要能證明你的信念」。在這裡，你的類別、方法，甚至是程式碼中的每一區塊，都必須要能夠展現你的意圖。

因此，單一職責不只能用來檢驗類別。從一整個服務，到單一個函式，都可以用它的意圖來問問自己。這一段是否只有一個職責？是否只有一個原因造成改變？職責是否清晰？

當然，從模組到函式每一層級的抽象概念是不一樣的，模組有模組關注的點，函式有函式關注的點，其規模有所差異，請不要用函式的職責大小去要求整個類別，我個人覺得這中間的差異還是挺吃經驗的，但不去嘗試思考，就沒得經驗可說嘛。這邊還是鼓勵大家多多利用單一職責去檢驗任何片段的程式碼。

當我們利用單一職責原則去檢驗，或是思考方向的時候，如果列得出兩項以上的變更原因，且這些原因彼此關聯很薄弱的時候，就是警訊。

反過來說，即使有兩個原因引起變化，但這些原因之間的關聯很強，例如總是一起變化，那其實就不必分離，或是可以暫緩分離，避免過度設計所引起的不必要的複雜性。（白話文來說就是走火入魔）

如果能做到撰寫功能當下，或是重構的時候不斷自我檢驗，那寫出來的程式碼品質相信也能展現出一定的水準了吧！共勉之。

本文整理時主要參考了這兩篇，寫得相當不錯，想更瞭解的朋友可以參考一下：

再談物件導向設計原則: 單一職責原則，定義、解析與實踐 - WadeHuang的學習迷航記

深入淺出單一職責原則 Single Responsibility Principle - jyt0532’s Blog

看到這篇覺得很不錯，從另一個角度切入單一職責，回來補充給各位朋友：

工程師的簡單觀念 – Ruddy Lee 分享空間 (wordpress.com)

本系列下一篇：菜雞與物件導向 (11): 開放封閉原則

參考資料

再談物件導向設計原則: 單一職責原則，定義、解析與實踐 - WadeHuang的學習迷航記
SOLID 之單一職責原則（Single responsibility principle）- Miles - iT邦幫忙
深入淺出單一職責原則 Single Responsibility Principle - jyt0532’s Blog
Fred 聊聊 SOLID 設計原則
Object Oriented 物件導向設計原則 SOLID-1:Single Responsibility Principle(SRP) 單一職責 - Sian
SOLID-I 單一職責原則(Single Responsibility Principle) - 黃子源 - Medium
《大話設計模式》 Ch3. 拍攝UFO －－單一職責原則
《無瑕的程式碼：整潔的軟體設計與架構篇》 Ch.7 SRP －－單一職責原則
《無瑕的程式碼：物件導向原則、設計模式與C#實踐》 Ch.8 SRP －－單一職責原則

同系列文章

C#: 元組 (Tuple)

Igouist (Igouist) — Sun, 27 Sep 2020 23:56:00 +0800

因為隔壁介紹原則的部分有點卡住了，所以這週來紀錄一下挺常用到的方便東西：Tuple

這篇的 Tuple 指的是 C# 7.0 後提供的 ValueTuple 和相關語法，舊版得用 Tuple.Create 建立，成員的名稱也只能使用 Item1, Item2…，實用性並不是很高。但新 Tuple 出現後，方便程度大大提升，這邊就稍作紀錄一下。

註：此處使用的 Dump 是 Linqpad 提供的輸出方法，把它當成 Print 就行了。

var student = (1, "王小明");
student.Item1.Dump(); // 1
student.Item2.Dump(); // 王小明

student.Dump();

可以看到 Tuple 的建立相當簡單，只需要用小括號 () 括選起來即可。建立後的內容就會像這樣：

但這樣使用就和之前一樣，取出來時只能拿 Item1, Item2，放個幾天根本就不記得 Item1 裡面是啥東西了。這時我們就可以替成員們取名字：

(int ID, string Name) student = (1, "王小明");
student.ID.Dump(); // 1
student.Name.Dump(); // 王小明

如此使用的時候就和一般操作物件的習慣沒有差別，也增加了可讀性。

到這裡可能感覺只是個方便的變數打包小工具，但其真正順手的地方就在於作為回傳值的時候。

過去要一次回傳多個值，除了使用 Ref 等方式以外，就只能乖乖做一個類別來裝，但有時候傳的東西又相當簡單，實在不太願意就此建立一個類別，又或是事情已經無法挽回，專案虛胖了一堆米蟲類別。有了 Tuple 之後，面對這種情況就可以直接使用 Tuple 解決，並且替成員們命名之後，既簡便又好讀！

// 回傳型別使用 Tuple
public (bool IsSuccess, string Message) DoSomeThing()
{
    // 做了一堆事情
	return (true, "操作成功");
}

void Main()
{
	var result = DoSomeThing();
	result.IsSuccess.Dump(); // true
	result.Message.Dump(); // 操作成功
}

而當我們作為回傳值使用時，也可以直接原地解封：

// 回傳型別使用 Tuple
public (bool IsSuccess, string Message) DoSomeThing()
{
    // 做了一堆事情
	return (true, "操作成功");
}

void Main()
{
    // 直接拆開賦值給多個變數
	var (isSuccess, message) = DoSomeThing();
	isSuccess.Dump(); // true
	message.Dump(); // 操作成功
}

作為一個簡易臨時型別挺方便的，但要注意不要用過頭了。兩三個成員還算方便，如果有七八個甚至十來個成員，請還是乖乖做成類別吧！

參考資料

菜雞與物件導向 (9): SOLID

Igouist (Igouist) — Sun, 20 Sep 2020 13:51:00 +0800

終於進入了原則篇，接下來的幾篇我們會介紹幾個物件導向的原則（基本上就是指 SOLID 原則）。因此這篇就讓我 ~~水一下~~ 當成後半段的目錄，方便之後可以把相關的部分整理進來。

為什麼我們需要這些原則？

我們在前面的章節已經說明了一些物件導向的特性，例如繼承和多型等等。然而我們並沒有討論到怎麼運用、或是怎樣設計才能算是更好的、更優雅的、更符合物件導向精神的；我們並沒有提到一個評估的標準，或是指引一個更好的方向。

然而，混亂的使用物件導向對整個專案的毀滅性甚至比乾脆不使用物件導向還高。

這些特性使用起來很簡單，大多數語言只需要一個符號或標示就能完成繼承，把一堆東西全部塞在一起就可以說我在封裝。但怎麼使用得好，又該什麼時候使用呢？這就是難的地方吧。

例如說濫用繼承，或是封裝時完全不隱藏複雜度一路 Puuuuublic 到底，又或者是類別之間過於相互依賴，全部耦合成一團等等。如果隨便地使用物件導向的各項特性，就會讓整個架構變得僵化、脆弱、危險、充滿臭味。

更可怕的是，這個發臭的過程是每一次設計、每一次修改都會有所影響，所謂「持續發生，腐敗成真」，隨著物件導向的亂用、誤用、無腦用，軟體就會逐漸腐化。一組腐化的軟體可能會有以下特徵：大量的依賴使得修改變得困難、修改後看似不相干的各個地方發生問題、或是修改時沒辦法依循原本的設計、到處出現不必要的複雜性和不必要的重複，模組也變得難以理解等等。

阻止程式碼的腐化、追求更好的架構和設計、寫出更好的代碼，當然是我輩所追求的目標。儘管面對的可能是不同的問題和不同的環境，那些優質、穩固、具有反脆弱特質的程式碼也必然會有些共通之處。例如說：需要具有面對改變的能力、具有方便管理的能力、具有隱藏複雜性的能力。

因此，大前輩們整理並提出了一些可以致力的方向，也就是所謂的「原則」。如同心法、教義一般，只要實作的同時將其牢記在心，就能讓我們作為一些行動的準則和依據。

所謂練拳不練功，到老一場空。我們可不能看了招式就無腦用，先讓我們看一下這些 SOLID 原則的目標是什麼。

在 Clean Architecture 裡是這樣說明的：

這些原則的目標是建立中層級的軟體結構，這樣的結構包含：

能容忍變化

容易理解

在許多軟體系統中能夠使用的元件的基礎

「中層級」是指這些原則是程式設計師在模組層級工作時應用的原則。它們應用在程式碼層級之上，並且有助於定義模組和元件內使用的軟體結構類型。

我們應用這些原則的場景，應該是在所謂的「中層級」發生。也就是並非小到一行程式碼，也並非是一整個專案，而是其中的各個「模組」。不論是類別、介面又或是其他名稱的任何東西，凡是具有函式或資料的中層級，我們就可以運用這些原則來處理。

而我們之所以要用這些原則，就是為了達到 能容忍變化、容易理解、能讓模組和元件使用 這些目標。

這些目標可以當作一個良好的程式碼模組該有的特徵。你的類別必須能容忍變化，必須具備可擴展性和可修改性，畢竟軟體的需求大多時候都是擴展跟修改。更進一步說，功能和彈性之間甚至應該先選擇彈性，畢竟為了功能犧牲彈性的話，一但面對變化，整個程式就碎了；但優先選擇彈性的話，至少你還有機會能把它修改得更符合功能，所以對這些原則而言，能容忍變化是相當重要的。甚至，整個 SOLID 就是面對變化的作戰策略。

而容易理解就更重要了。Clean Code 裡有提過，閱讀程式碼和實際開工打字的時間大約是佔 10 : 1，因此是否容易理解，是否乾淨好懂就是相當重要的一環。看得快，就寫得快；寫得越快，心越慢。

如同我們在首篇所說，物件導向就是在替我們把概念抽象化，而這抽象過程所使用的這些特性，就是為了減少複雜性、提高可理解度而存在的。因此，一組優良的程式碼，容易理解是絕對必要的。

另外關於為什麼我們需要這些原則，我個人推薦可以先閱讀這幾篇，對我個人來說很有收穫：

說那麼多，所以到底有哪些原則？

現在我們已經了解到，因為軟體會逐漸腐化，所以我們要找出原則；這些原則的目標，就在於設計出可變化可理解的優質模組。現在，是時候公布我們 SOLID 五大天王的名諱了：

單一職責原則 Single Responsibility Principle (SRP)
開放封閉原則 Open-Closed Principle (OCP)
里氏替換原則 Liskov Substitution Principle (LSP)
介面隔離原則 Interface Segregation Principle (ISP)
依賴反轉原則 Dependency Inversion Principle (DIP)

註：大多時候 L 的位置也會多一個 Law of Demeter 迪米特法則（= Least Knowledge Principle 最少知識原則），畢竟也挺重要的，而且四大天王都有五個人了，五大原則有六個也是剛剛好。

而它們的首字合起來就是 SOLID，表達出那種穩固的、可靠的感覺！順便一提，順序沒有任何關係，會排成 SOLID 純粹只是作者朋友當時覺得這樣比較好記。

那麼從下一篇開始，我們就按照 SOLID 的順序，從單一職責開始介紹。我們下次見～

本系列下一篇：菜雞與物件導向 (10): 單一職責原則

參考資料

同系列文章

菜雞與物件導向 (8): 內聚、耦合

Igouist (Igouist) — Sun, 13 Sep 2020 23:56:00 +0800

做為前後段落的分水嶺，這篇文章我將紀錄一下 「內聚」(Cohesion) 和 「耦合」(Coupling)，這兩者是評估一個類別或元件的重要概念。

在實務上，為了提升擴展性，降低維護成本等因素，我們對於單個類別或元件，會有著 「低耦合」 及 「高內聚」 的期待。例如我們在菜雞與物件導向 (3): 封裝中，我們就有提到封裝的好壞相當重要，其中也包含了「提高類別內的內聚性，降低對外的耦合性」。那麼，到底什麼是內聚，什麼又是耦合呢？

內聚

「把需要的程式和資料都包裝在同一個模組內，使得該模組能夠做為一個單獨的個體執行」

白話一點說，就是就是把用到的東西都打包到一處，該有的自己都有了，所以即使單獨一個人也能完成工作的能力、可以自己 Carry 整場不用看豬隊友臉色的能力。越能自己單幹，越不需要依賴其他類別的時候，內聚力也就越高。

也就是說：如果你的類別什麼都要依賴其他類別，像小嬰兒一樣需要呵護照顧，那內聚力就很低。反之，如果像野外求生大師，啥都靠自己，那內聚力就超高。

內聚代表的是該模組的獨立性，當這個模組可以獨力完成工作，就代表我們能夠重複使用它，且不需要擔心影響到其他模組。

並且也基於這點，我們不用擔心變動這個模組時需要先處理其他的模組，因為這個工作所需的都包含在模組內了，這樣就可以單獨修改該模組，減少維護成本。

例如你的筆已經包含了所有寫字工具的條件，具有墨水跟筆芯等等，可以只使用筆就完成寫字這個工作。那麼我們就可以隨身帶著，在任何需要的時候重複使用它，而不用擔心我們會不會漏了什麼必要零件沒有帶出門。同時，如果我們需要換筆芯或墨水，我們也知道要更換的部份就在筆裡面，不需要去找鉛筆盒中別的地方。

而我們在物件導向的世界中，是將不同的邏輯和功能，封裝成不同的物件，藉由這些物件的互動來構築我們抽象化的世界和想法。為了隱藏這些物件內部的複雜性，同時又保持物件的整體性，讓物件能真的符合我們概念中的「一個」物件，那麼追求高內聚就是必然的。內聚，是物件的一種美德。

然而，盲目地追求高內聚是很危險的。只要你希望，當然可以寫出一個超級內聚的類別，但這代表什麼呢？

為了提高內聚，把所有相關的東西都一股腦塞進同一個類別，越塞越多越塞越多，沒那麼相關的東西也硬塞在一起。從模組變成義大利麵，再從義大利麵變成大補帖，最後終於變成神。這樣實際上根本就不內聚，類別裡面就是一堆散沙，功能一大堆動輒數千行，改個 Bug 先看三千行程式碼，維護者莫不痛哭流涕…

又或是為了避免上面的狀況，限制了功能範圍。但卻又為了能獨立作業，為了不依賴別人，硬是把別的地方已經有的功能複製一份過來，用到的東西都複製複製複製進來，人人都有一份。最後遇到修改時，要改這又要改那，等著改的地方遍地開花，維護成本暴增，維護者再度痛哭流涕…

到這邊應該能瞭解到完全內聚是不可能也不應該的，過於執著就會走火入魔。那麼怎樣的內聚算是剛剛好呢？或是說，一個良好的高內聚？這就牽涉到這段程式碼的意圖了。

良好的內聚應該只關注在一件事情上，並適時地將不屬於自身職責的工作交給別人，達到所謂「該內聚而內聚，該耦合而耦合」。

所謂「只關注一件事情」、「不屬於自身職責」云云，我們在之後的單一職責原則會更進一步地說明。且先按下不表。

為了減少重複程式碼，和降低維護的困難，不管怎樣互動都是不可避免的。那既然我們的物件多多少少都得依賴別人，就不能不提到耦合了。

耦合

「如果模組和另一個模組有關聯，那這兩者之間就耦合」

耦合的定義就是這麼寬廣。不管是接收另一個物件傳入的值，或者是共用同個全域變數，更何況我中有你你中有我，都是耦合。

當兩者之間的關聯越緊密，越無法分離，其耦合度就越高。例如說繼承關係就是強耦合的代表。

當我們的目標放在減少重複的程式碼時，就會有多個模組共用同一段程式碼的情形發生，也會造成這些模組和這段重複使用的程式碼彼此耦合。

那當我們為了其中一個使用者修改了這段程式碼，就會連帶影響其他用到的地方。變成改了這裡壞那裡，修了那裡壞這裡的詭異情況。這也就是我們追求降低耦合的最大原因。

彼此關聯就會彼此牽連，因此我們要讓彼此之間保持一個舒適的距離。

注意，是舒適的距離，而不是不相往來，從這點來看，健康的內聚就是健康的耦合。

內聚與耦合

內聚是模組的獨立性，耦合則是模組的關聯性

「低內聚高耦合」的組合，牽一髮動全身，改個一行程式碼動輒就是大規模傷害，我們甚至不能切分模組，完全和物件的精神背道而馳，這是萬不能接受的。

「高內聚低耦合」則是大家所追求的目標。為了讓每個物件各自獨立又能彼此互動，從物件導向中封裝的角度出發，這個方向絕對是正確的。

但所謂過猶不及，若是太過火變成「超高內聚無耦合」，又會變成可怕的 All in one 融合怪物或是 Ctrl C VVVVV 的複製大軍……

不健康的內聚和不健康的耦合都是問題，內聚和耦合這兩者就像天秤的兩端，我們的目標就是找到那個合適的平衡點，也就是健康的高內聚低耦合才是我們所追求的。

同時也可以注意到內聚和耦合會發生的問題，例如修改時影響其他物件導致壞一整片，又或是修改時太多地方要改成本過高，總是圍繞在擴展和維護，基本上就是面對改變時會發生的問題。

就像基因的優劣在於適應環境並生存下去的能力，程式碼也是如此。為了協助我們追求健康的高內聚低耦合目標，也為了讓我們面對改變（遭遇災難）時有個方針，因此才有了一些原則。

就像我們前面敘述內聚時一直迴避的這些問題：

怎樣才是適合的內聚？怎樣才是健康的耦合？
如果說過高的內聚會塞太多功能或複製重複功能而變成怪物，過低的內聚則會四處拈花惹草，那我們要怎麼知道這個類別或元件的功能範圍剛剛好？

這些問題的參考準則，就在於我們之後要介紹的「單一職責原則」！

小結

過了兩個月再度接續這個系列，一回來就是一篇碎碎念充當預告片，總之就先交代一下內聚和耦合的概念。

但要真的達到健康的內聚和健康的耦合，不造神、不亂依賴、物件裡面高內聚、物件彼此低耦合，就必須要有一些原則。

所以下回開始就要進入物件導向五大原則的段落了，那麼，我們下次見！

註：內聚跟耦合算是相當重要又基礎的觀念，我個人也還在摸索，只聞其聲不見其影。想要更了解這兩個概念的朋友，可以將參考資料的文章都看過一遍，我個人覺得頗有幫助，尤其是實務上的高內聚與低耦合、搞笑談軟工兩篇，值得特別推薦。

本系列下一篇：菜雞與物件導向 (9): SOLID

參考資料

同系列文章

讀《先問為什麼》

Igouist (Igouist) — Sun, 06 Sep 2020 10:02:00 +0800

如果你樂於接納新事物，希望成功能持久，也相信自己的成功需要別人的幫助

我向你提出一個挑戰 ——

從今天起，做任何事情之前，請先問自己「為什麼」。

這本書的中文副標很好地點出了本書的重點：顛覆慣性思考的黃金圈理論，啟動你的感召領導力。大多篇幅用在舉例以及逐步說明何謂感召，以及黃金圈。

本書的想法和一些例子，尤其是書中最重要的黃金圈理論，在作者上 TED 的影片「偉大的領袖如何鼓動行為」都有說明，有興趣的朋友可以直接看演講影片，足夠掌握到黃金圈理論的核心。

（偉大的領袖如何鼓動行為 - TED）

作者認為影響人類行為的方法有兩種：操弄以及感召，其中操弄是指使用手段或策略去影響他人，例如說談判、利誘、情緒勒索、削價競爭等等，所謂「人有所好，以好誘之無不取；人有所懼，以懼迫之無不納」就是操弄。

同時操弄也是我們日常最常接觸到的方法，可說是無所不在，並且很容易達到目標，短期見效。但如果將目光放到建立長期關係，則操弄就不一定是個好方法：它能帶來短期的利益，但並不能帶來忠誠度和信任，過度依賴操控就像在懸崖邊跳舞，一失足就難以挽回。

而感召，則是用激勵人心的方式去影響他人、促使別人展開行動。為了說明這些領導者如何能做到感召他人，作者提出了黃金圈理論。

從最外圈到最內圈分別為：

做什麼：負責什麼工作、提供什麼商品等等。每個人都能說得出來。
怎麼做：流程、方法、技術。知道怎麼把事情做好，比做什麼更加抽象。
為什麼：目的、使命、信念。真正的核心，但很少人能清楚說明。

我們能很清楚說出我們正在做什麼，有些時候也能說得出來該怎麼做，但很少人會提及為什麼要這樣做。這是因為大多數人傾向從較為清楚的點開始，而將模糊的事往後延，所以行為模式就會是從黃金圈由外往內。從具體的行為到模糊的原因。

然而，能激勵熱情的做法卻不一樣，他們是由內往外的，他們會先問為什麼。作者針對這兩種的差異，給了一組電腦公司的銷售方式做為例子：

我們很會做電腦
我們的電腦有最美的設計，不但使用簡單，也容易上手
想要買一台嗎？

這就是先從最外圈做什麼開始的訴求，但這樣實在沒有什麼吸引力。然而，大多數的企業和廣告都採用這種方式行銷，先從「我們做的商品，這項商品和其他商品的不同處」開始，然而這並不能達到感召。接著，作者提出了蘋果的溝通模式來對比：

我們做的每件事，都是為了挑戰、改變現況，因為我們相信「不同凡想」的力量
我們挑戰現況的方法，就是讓我們的產品有最美的設計，而且簡單好用
剛好，我們做的就是最棒的電腦
想要買一台嗎？

只是調整一下訴求的順序，並說明為什麼而已，感覺就會截然不同。

這之間的差別在於，所謂設計、簡單、好用，只是你的理念具體化的表現。所有公司都能夠聘請厲害的設計師和工程師，所有公司也都各有優劣之分，多數人和企業認為有形的功能和價值會是致勝關鍵，不可否認產品和策略對於優勢息息相關，然而在這些背後，你為什麼而做，你所做的是否能夠表達出你的理念，這就會是關鍵的差別。

吸引人們的，不是你做什麼，而是你為什麼做。

用優劣得失衡量而來的顧客，終究會因為優劣得失離開；但用理念吸引來的顧客，將會和你並肩作戰。這也就是開場時，作者將操弄和感召作為對比的原因，在這裡直接延伸成忠誠度，若只用手段和策略去鞏固顧客，這樣的關係危險且無法持久。但當你的目標和理念能和顧客產生共鳴時，顧客甚至能夠包容你產品的缺點，而以你產品的優點為傲。這是只講究手段、策略、怎麼做的人難以理解的。

只執著在怎麼做的人，會用差異化的方式來試圖脫穎而出，也就是說服顧客自己和其他競爭者與眾不同。然而，大多數的產品對顧客來說都是所差無幾的，例如生活用品、衛生紙、牛奶，對顧客來說牛奶就是牛奶。並且，當我們只用怎麼做和做什麼兩個著眼點去進行這件事時，很容易陷入惡性循環。例如說削價競爭，用低價當做訴求，不斷削價的結果可想而知。

真正最有效的差異，就在於你為什麼而做。

「一台擁有5GB容量的MP3播放器」和「（為了）放一千首歌在你的口袋裡」中間的差別是顯而易見的。

當然，知道了為什麼之後，還是得知道怎麼做。總不能都說要放一千首歌在你的口袋，然後連個撥放器都造不出來吧，因此知道為什麼的人，還是需要那些知道怎麼做的人。不是說想到好棒的點子就趕快找認識的工程師朋友去咖啡廳泡茶，而是先知道為什麼的好處在於，你能夠區分出選擇有哪些。

當你的信念是為了改變世界，你就不會考慮削價競爭。當你的訴求是「讓每個人躺上我們的沙發都像個國王！」你就不會考慮用抽換劣質棉花的方式來降低成本。先知道為什麼之後，有助於讓你的怎麼做變得清晰。

而當你的黃金圈趨向一致、平衡的時候，你的為什麼足夠清晰、具有號召力，怎麼做和做什麼都能展現出你的信念的時候，自然就能吸引到那些和你志同道合的人們，創造忠誠度和歸屬感。所以，與其要求所謂「忠誠」、「誠信」這些結果（如果還必須特地要求這些，那應該也是相當危險了），不如把自己的「為什麼」表達出來，有紀律地根據「為什麼」去貫徹「怎麼做」，讓黃金圈完善，那麼自然就能達到這些效果。

就像我們在前一篇《黑馬思維》的心得所說，先知道微動力之後，就能據此選擇適合的策略，所以選擇並不難，符合自己就好。如果你能先找出為什麼，那麼你該怎麼做的選擇就會縮小到符合為什麼的範圍，如此一來也就簡單多了。再拿我喜歡的卡牌遊戲舉例，當所有人的牌組都一致時，對於核心概念的理解程度就會呈現在策略方針的差別，進而決定最後的高度。因此，想要做出明智的選擇，就先從問為什麼開始。

為了表達「為什麼」與「怎麼做」之間的關係，作者提出了芹菜測試：

假設你去參加一個晚宴，忽然有朋友跑來告訴你，「你知道你的組織需要什麼嗎？M&M巧克力。不用M&M，根本就是有錢不去賺。」

這時，另一個朋友又跑過來，說：「你知道自己該做什麼嗎？豆漿。研究顯示，現在每個人都在買豆漿。你應該賣豆漿才對。」

當你站在雞尾酒桌旁邊的時候，另一位朋友又給你一個建議。「Oreo餅乾，」他說。「我們靠Oreo餅乾賺進了好幾百萬美元。你絕對要做Oreo餅乾。」

這時又來了一個人，告訴你：「芹菜！你一定得做芹菜這門生意。」

所有這些有成就的朋友給了你那麼多重要建議。有些人和你身處同一產業，有些人比你成功，有些人也給別人相同的建議，結果讓人受益匪淺。這時，你該怎麼辦？

當你跑去超市把上面提到的東西一股腦都買了，在排隊付錢時，所有人看著你手上的東西，根本不知道你相信什麼。你做的事情應該體現你的目標，但你手上什麼都有。

但如果在你去超市之前，先確認好自己的為什麼。假設你的目標是為了健康，那你就只會拿著豆漿跟芹菜。而從結果來說，你在超市花的時間和金錢也比較少，每個人也都能感覺得到你的理念。

你的一言一行，都要能證明你的信念。為什麼的本質就是信念。怎麼做，則是你實踐信念的行為，而做什麼則是這些行為的結果。《先問，為什麼》

作者在書中小心叮嚀不要走歪，所謂的走歪就是為什麼和怎麼做兩者漸行漸遠，手段開始不符理念，策略遠離目標的時候。由於怎麼做的操弄和策略通常是立即有效的，而為什麼的感召則是緩慢的、可能會停滯的。一旦鐵粉量飽和了、理念號召的做法陷入停滯時，多數人會不斷嘗試採取各種手段以求突破現況，這中間難免會為了立即的甜頭而走上了岔路。

為了抓住所謂市場機會或是尋求突破等等，而使得「為什麼」和「怎麼做」脫鉤的時候，很可能造成原本的忠誠度下降，進而引發其他問題。長久以來就會變得危險，如同不斷追尋成長的殭屍，但世界上沒有所謂的『持續成長』，失去信念後盲目亂竄只是變成我們開頭舉例的那些公司的其中一員罷了。

因此時刻檢驗自己的「為什麼」，自己的「怎麼做」和「做什麼」有沒有符合「為什麼」是相當重要的。

換句話說，就是莫忘初衷。

釐清自己的做什麼並非最困難的部分。真正難的是相信自己的直覺、堅持自己的願景、使命或信念。保持平衡與真誠才是最困難的部分。《先問，為什麼》

最後，這本書的副標和內容似乎都展現出是一本管理學書籍的感覺，例如企業、忠誠度、領導力等等。但作者也說了：每個組織或團體，都是由一個人或一小群人來的。就像我們前一篇黑馬思維的心得提過的，你要把你個人當一個品牌來經營。這些道理應用在個人的生活和行為也是相當符合的。

如同作者所說的：我們永遠只能從我們自己開始。

最後就放一下作者書中提到的工人故事，在 [好書分享] 先問，為什麼？看到之後就蠻喜歡的：

有一位哲學家到一個建築工地分別問三個正在砌築的工人說：「你在幹什麼？」

第一個工人頭也不抬地說：「我在砌磚。」

第二個工人抬了抬頭說：「我在砌一堵牆。」

第三個工人熱情洋溢、滿懷憧憬地說：「我在建一座教堂！」

願各位都能找到心中的教堂，找到自己為何而戰，找到「為什麼」，共勉之。

延伸閱讀及參考資料

遺珠之憾

作者在書中將黃金圈的三層，和大腦的結構對應起來，並將為什麼類比為我們的緣腦，掌控情感、信任、決策等等，同時將做什麼類比為我們的新皮質，掌控理性和分析。並且認為我們常有無法理性分析的直覺，並且常常證明是對的，作者將其和為什麼的信念連結在一起。對直覺和理性之間的互動有興趣的朋友，可以試著讀讀看《快思慢想》，或是看過網路上大大整理的系統一和系統二關係圖。

另外，書中還有一些段落並沒有節錄出來，例如用黃金圈和市場溝通，如何引爆趨勢（可以參見創新擴散理論和病毒行銷），以及關於「為什麼」的一些不錯的例子（西南航空、沃爾瑪、福特）等等。如果有興趣的話，還是推薦可以入手一本來看看，這邊就附上博客來和 Kobo 連結。有興趣的朋友可以考慮入手看看呦！

C#: 時區轉換、民國西元、國曆農曆、中文月份週期

Igouist (Igouist) — Sun, 30 Aug 2020 11:58:00 +0800

聊到將時間從 UTC 轉到台灣時間，居然還是聽到朋友表示使用 +8 小時的做法，驚為天人。這種做法可能會造成後續的問題，例如時區並不會跟著變動，或是遇到日光節約等特殊狀況就容易出事。和西元民國轉換直接 -1911 一樣不穩定。

這篇就用來記錄一下之前看過比較優雅的時區轉換方式，順便將先前存著的時間處理相關資料整理一下，方便之後需要時可以馬上回來查詢。

章節目錄

TimeZoneInfo: 時區資訊

轉換方式主要參考自 [食譜好菜] DateTime 具有文化特性的格式化及時區的轉換及在各時區間轉換時間，感謝前人的指引。

關於文化特性，也可以參考本站的菜雞抓蟲: DateTime.ToString() 之我們不一樣 & CultureInfo 文化特性小筆記呦。

// 假設現在是要從標準時區 +00:00 轉換到台灣時區，故這邊使用 UtcNow 先取標準世界協調時間
var nowDateTime = DateTime.UtcNow;

nowDateTime.ToString("yyyy/MM/dd H:mm:ss zzz").Dump();
// 2020/08/30 15:56:05 +00:00

// ==================================================

// 傳統的 直接對時間做計算的方式…
var addedDateTime = nowDateTime.AddHours(8);

addedDateTime.ToString("yyyy/MM/dd H:mm:ss zzz").Dump();
// 2020/08/30 23:56:05 +00:00
// 可以看到儘管時間變動了，時區仍然還在 +00:00

// ==================================================

// 使用 TimeZoneInfo 先取得台北時區
var timeZone = TimeZoneInfo.FindSystemTimeZoneById("Taipei Standard Time");

// 再使用 TimeZoneInfo 來變更時間
var convertedDateTime = TimeZoneInfo.ConvertTime(nowDateTime, timeZone);

convertedDateTime.ToString("yyyy/MM/dd H:mm:ss zzz").Dump();
// 2020/08/30 23:56:05 +08:00
// 可以看到除了時間變更以外，時區也切換到 +08:00 了！

上面取得台北時區的步驟，可以參照 Time Zone IDs 來查詢想要的時區。這樣的時區切換方式，不僅副作用少，不會因為時區沒轉雷到後續接手的人，也省卻了擔心日光節約等等問題，這種事就交給微軟去煩惱吧！

另外這邊也逐步放一些時區處理相關的參考資料：

TaiwanCalendar: 西元年轉民國年 &
TaiwanLunisolarCalendar: 國曆轉農曆

可以參考這篇基本題 - C# 西元年轉換取得民國年格式字串 - mrkt 的程式學習筆記。

內文示範了使用 System.Globalization.TaiwanCalendar 和 System.Globalization.TaiwanLunisolarCalendar 來進行安全轉換的作法。

基本上來說就是指定文化特性中的時間格式（曆法）為農曆，至少依靠微軟爸爸，比自己加減 1911 來得安全多了囧。

var time = new DateTime(2021, 12, 01);

// 直接從 TaiwanCalendar 取民國年，自組字串時常用
var taiwanCalendar = new TaiwanCalendar();
taiwanCalendar.GetYear(time).Dump(); // 110

// 將文化特性的曆法改成民國年
var info = new CultureInfo("zh-TW");
info.DateTimeFormat.Calendar = new TaiwanCalendar();

// 西元年轉民國年(字串)
time.ToString(info).Dump(); // 110/12/1 00:00:00

// 民國年(字串)轉西元年
var timeString = "110/12/1";
DateTime.Parse(timeString, info).Dump(); // 2021/12/01 00:00:00

DateTimeFormatInfo: 月、週、時間的格式

不用再傻傻地手刻陣列「星期一」、「星期二」、「星期三」…之類的了，只要用 DateTimeFormatInfo.CurrentInfo 的就好啦：

var MonthCh = DateTimeFormatInfo.CurrentInfo.MonthNames;   // 中文月份名稱列表
var MonthEn = DateTimeFormatInfo.InvariantInfo.MonthNames; // 英文月份名稱列表

除了月份以外，DateTimeFormatInfo.CurrentInfo 也包含了當地的其他欄位與格式。

例如 AbbreviatedDayNames 能拿到週一、週二、週三…；DayNames 則會拿到星期一、星期二、星期三…

時間格式的話，FullDateTimePattern 就會拿到 yyyy'年'M'月'd'日' tt hh:mm:ss 等等

內容還有許多欄位，有興趣的可以用 LinqPad 來 Dump 看看，或是直接翻閱 DateTimeFormatInfo 囉！

參考資料

Powershell 美化作戰 —— 字型、執行原則和 oh-my-posh

Igouist (Igouist) — Sat, 15 Aug 2020 18:00:00 +0800

最近在兩天內經歷了記憶體死去、系統毀損、機殼碎裂等等，終於電腦重灌。一堆設定都要重弄，正好也是個機會，這篇順手記一下常用好幫手 Powershell 的美化步驟。

先放一張施工後的圖鎮樓：

可以在開始圖示上用右鍵打開選單，之後點選 Powershell；或是 Win + X 打開選單，然後按 I 或 A （後者會以系統管理員身分開啟）就能開啟了。

如果選單打開還是 CMD 而不是 Powershell 的，可以先去切換成 Powershell，真的是比較好用啦（Windows Terminal 笑而不語）

剛打開的畫面是這樣的：

抱歉，光細明體我就不太行了。所以接下來就從字型這些內建設定開始！

章節目錄

基本設定

在上方的標題列按下右鍵，選擇內容

首先就讓我們修改字型，我這邊還是採用習慣的更紗黑體。

另外還有一些推薦的字體，可以參閱前陣子整理的 Visual studio 環境設定 —— 字型、套件、快捷鍵。

補充：還有擴充了 Nerd Fonts 的等距更紗黑體：Sarasa-Gothic-Nerd-Fonts 可以選擇，Nerd Fonts 能提供許多精美的 icon 讓我們後續改主題的時候大大加分！

除了字型以外，我個人還推薦可以修改一個設定，保證質感 UPUP，那就是透明度

我個人習慣採用 80~85% 左右的透明度，搭配黑色背景。在桌面使用的時候看起來就像這樣：

可以拉回去和一開始的預設狀況做比較，透明感＝質感。

另外，背景透明還有意想不到的好處，那就是——

打指令偷看可以不用切換視窗！

基於以上兩點，推薦可以調整透明度，找個適合自己的區間。但要注意，如果太透明的話會讓字跟背景糊在一起，很容易眼花，自己斟酌一下。

以上就做完了基本設定，沒意外要做兩次（一般身分和系統管理員）

安裝 posh-git

然而我們並不打算在此停止！因緣際會之下，我拜讀了這篇使用 oh-my-posh 美化 PowerShell 樣式，頓時驚為天人，跟預設的（請自己再拉回去比對第一張圖）實在是相當有差距，於是當時就直接安裝下來了。

畢竟這是第二次安裝了，接下來的區段就記錄一下安裝 oh-my-posh 主題的流程。oh-my-posh 是受到 Linux 上 oh-my-zsh 的啟發誕生的，總之就是個挺讚讚的主題載入工具。

而且安裝相當方便，只需要從 Microsoft Store 或直接打 Install-Module 指令，就能從 PowerShell Gallery 把模組安裝下來囉！

在安裝 oh-my-posh 之前，由於顯示的內容包含 Git ，因此我們還要先下載另一個套件 posh-git。讓我們用系統管理員身份開啟 Powershell，並輸入以下指令來進行安裝：

Install-Module posh-git

到這一步，會有幾種狀況：

提示安裝 NuGet：安裝就行了
提示不安全儲存庫：安啦，選是就對了
跳出錯誤，顯示「因為這個系統上已停用指令碼執行」云云，則接著看下一段落
什麼事都沒發生，很順利地裝好了，請跳過下一段落

執行原則

如果跳出「因為這個系統上已停用指令碼執行…」的情況，代表遇到執行原則的部份。因為安全性考量，預設是不能執行 Powershell 腳本的，連帶也不能使用 Install-Module 這類方法。

關於執行原則，可以參閱這篇 Windows PowerShell 基本操作 - 執行 Windows PowerShell 腳本的說明。該系列也挺實用的，值得一看，這邊我們就節錄一段來說明執行原則的種類：

Restricted ：關閉腳本檔的執行功能，這是預設的設定值。
AllSigned ：只允許執行受信任發行者簽署過的腳本檔。
RemoteSigned ：在本機電腦所撰寫的腳本檔，不需要簽署就可執行；但是從網際網路（例如：email、MSN Messenger）下載的腳本檔就必須經過受信任發行者的簽署才能執行。
Unrestricted ：任何腳本檔皆可被執行，但是於執行網際網路下載的腳本檔時，會先出現警告的提示視窗。

如果要確認目前的執行原則，可以使用 Get-ExecutionPolicy

這個分類也是為了保護使用者，不要亂執行一些來路不行了奇怪腳本，整個電腦打包起來送人。不過我們身為白目工程師，難免會有要裝套件和自己寫腳本的時候，這邊就直接調整為 Unrestricted 全面開啟吧！

調整執行原則的語法如下（必須在系統管理員身分時才有效果呦）

Set-ExecutionPolicy Unrestricted

調整完就可以繼續下載囉！

像我重灌的狀況，提示會如下圖，如果已經安裝過 Nuget 提供者，提示應該會更少。

安裝 oh-my-posh

接著讓我們安裝 oh-my-posh：

Install-Module oh-my-posh

安裝完畢後就可以來試試看囉！

更新：Oh-my-posh 也可以從 Microsoft 搜尋並安裝囉！

設定主題

更新：由於 Oh-my-posh 設定主題的語法已經改變，因此移除 2020 時的內容，改為 2023 重灌電腦時找到的指令。

因為 Oh-my-posh 還蠻頻繁更新的，建議後續的操作可以開著 Oh My Posh 的官方文檔來排查一下

要更改主題的話，我們會需要使用 oh-my-posh init pwsh 這個指令，並且將該主題的 Json 檔案傳遞給 --config，例如：

oh-my-posh init pwsh --config "$env:POSH_THEMES_PATH/powerlevel10k_rainbow.omp.json" | Invoke-Expression

我們丟了一個 powerlevel10k_rainbow 這個主題的 Json 檔案路徑給 oh-my-posh，然後呼叫 Invoke-Expression 執行它，這時候主題就會變啦～

補充：這邊用到一組環境變數 $env:POSH_THEMES_PATH 實際上是一個資料夾路徑，Oh-my-posh 安裝的主題都會放在這個資料夾裡：

如果你有自己下載的主題，可以也丟到 POSH_THEMES_PATH 的位置，或是直接更改 --config 的路徑就可以了。

每個主題的樣式都不大一樣，可以翻一下 Oh-my-posh 的 Themes 頁面挑個喜歡的。

撰寫腳本

聰明的你一定發現了，每次重開都要重輸入一次 init 實在是很麻煩。因此我們接著要設定讓它能一打開就載入主題。

當 Powershell 開啟時，預設會去讀取使用者的設定檔（Profile），我們就是要把這些指定加到設定檔裡，讓 Powershell 一打開就能美美的。

在 Powershell 裡輸入 $PROFILE 就能取得當前的設定檔位置，通常來說會在 我的文件\WindowsPowerShell 底下。

補充：Powershell 啟動時會依序檢查四個位置來載入設定檔，分別為

所有使用者及所有 Shell: $PSHOME\profile.ps1

所有使用者的 Powershell: $PSHOME\Microsoft.PowerShell_profile.ps1

目前登入者的所有 Shell: $Home\My Documents\WindowsPowerShell\profile.ps1

目前使用者的 Powershell: $Home\My Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1

其中的變數

$PSHOME 是指 Powershell 的安裝目錄，通常在 system32 的 WindowsPowerShell 底下

$Home 則是使用者的主目錄，也就是大家熟悉的 users/{你的名稱}

而前面提到的 $PROFILE 就是指「目前使用者的 Powershell」這組

對設定檔有興趣的朋友可以參照保哥的文章及官方文檔：

如何在 Powershell 開啟時自動引入常用的 ps1 指令檔腳本 | The Will Will Web

關於設定檔 - PowerShell | Microsoft Docs

接著我們就前往此處去修改 Powershell 的腳本，如果發現並沒有這個檔案，那還請自己建立一個，檔名和路徑請和 $PROFILE 一致，像我就取 Microsoft.PowerShell_profile.ps1

之後開啟檔案，貼上我們引入套件和設定主題的指令：

oh-my-posh init pwsh --config "$env:POSH_THEMES_PATH/powerlevel10k_rainbow.omp.json" | Invoke-Expression

再次補充：oh-my-posh 改版之後一些語法有改變，如果有在 Set-Theme 這步的時候遇到「無法辨識…」問題的朋友，可以嘗試改成用 Set-PoshPrompt -Theme Paradox 試試看。

接著讓我們重開 Powershell

可以看見它已經順利載入主題囉！

因為我覺得切主題前跑那些 Powershell 提示之類的有點醜，所以我會回去 Profile 補一行 Clear：

oh-my-posh init pwsh --config "$env:POSH_THEMES_PATH/powerlevel10k_rainbow.omp.json" | Invoke-Expression
clear

也可以在這裡寫一些 function 來使用，像我個人之前做我要訂便當因為懶得每次都 cd 到腳本所在的位置還要 Pyhton 執行，所以就直接包成 Get-Bandon 的方法直接叫，真的舒服，推薦嘗試

如果有想要自己試試新增主題，或是想像我一樣做小修改的，可以到 $env:POSH_THEMES_PATH 這個路徑的資料夾，找到 .omp.json 檔案來動手

例如說把 powerlevel10k_rainbow.omp.json 開啟後，就可以看見組出那一串資訊的過程，也就可以隨意更改囉。我就特愛把一些 icon 都改成 °д°，感覺活潑多了（？）

補充：該路徑會根據安裝 oh-my-posh 的位置而變動，基本上開 Powershell 直接從環境變數的路徑下去找比較快。真的找不到的話也可以下載別人的主題改一改，再修改 `–config`` 的路徑指到自己改好的 json 就好囉

順便提一下，載入使用者設定對用到 Powershell 的地方都有效喲！

例如 Visual Studio Code 的 Powershell

或是 Visual Studio 的開發人員用 Powershell

都是會吃到個人使用者的設定的。

那麼今天就到這裡，最後再把完成品跟預設狀況比對一次吧～

2023 回來更新文章，順便附個現況：

同場加映：

跟朋友志得意滿地說明了 Powershell 美化作戰後，對方只說了淡淡的一句

「哦，我都直接 Cmder」

那又是另一個故事了……

參考資料

C#: 字串插值 (String interpolation) 的格式化

Igouist (Igouist) — Sun, 09 Aug 2020 20:35:00 +0800

自從 C# 有了字串插值這東西之後，我就一直是愛用者。畢竟比起 string.format 這東西可是看起來優雅多了。例如：

var message = $"哈囉，{userName} 您的點數將於 {cutoffTime} 到期。";

簡潔又明瞭，一眼就能理解字串內容。實在是挺方便，後來發現這東西還有一些延伸用法，這邊就稍加紀錄一下：

字串插值中能夠做簡易計算，例如：

var message = $"您輸入的數值為：{a}、{b}。他們相加為：{a + b}";

同時，在字串插值時可以針對內容作格式化，只需要用 : 來區隔，妥善運用可以省下一堆 ToString() 的空間。

例如當我們要將時間格式化的時候，就可以：

var date = new DateTime(2020, 8, 9);
var message = $"您的商品已於 {date:yyyy/MM/dd} 抵達。";
// 您的商品已於 2020/08/09 抵達。

另外，數值當然也可以格式化，不過數值的應用比較複雜，主要是用來定下小數點、百分比等符號的位置。可以參見自訂數值格式字串 - Microsoft Docs

var cost = 2100;
var message1 = $"您的商品一共是 {cost:#,###} 元";
// 用 # 可以替數字預留位置
// 您的商品一共是 2,100 元

var message2 = $"您的商品一共是 {cost:#,###.00} 元";
// 也可以用 0 來預留位置，若該數字有值就會顯示該數字，沒有就會自動補 0
// 您的商品一共是 2,100.00 元

而格式化也支援列舉，在同時顯示列舉的意義和值的時候會很有幫助：

// public enum Color { Red = 1, Blue = 2, Green = 3 };
var color = Color.Blue;
$"編號 {color:D} 是 {color:G}".Dump();
// 編號 2 是 Blue

承上部分，由於 : 在字串插值裡已經有特殊意義了，因此想在字串插值中使用三元運算子，必須先用 ( ) 括起來，如下：

var message = $"您的包裹 {(isArrival ? "已" : "尚未")} 抵達門市";

對字串插值有興趣的朋友，也可用微軟官方的教學課程來試試呦。

參考資料

C#: 使用 System.Environment 取得環境資訊、特殊資料夾路徑

Igouist (Igouist) — Sun, 02 Aug 2020 13:31:00 +0800

有時候我們會需要取得一些系統資訊，例如說取得設備和當前使用者等資料來寫 Log，或是取得特殊資料夾路徑、讀取環境變數等等。這些時候就可以使用 System.Environment ，這邊就稍微紀錄一下用法。

先列出幾個常用的環境資訊，詳細可查詢的內容可以到 Environment Class 查詢：

資料夾路徑則需要用 Environment.GetFolderPath 搭配 Environment.SpecialFolder 列舉使用，該列舉包含資料夾可以到 Environment.SpecialFolder Enum 查詢。

除此之外還有一些實用的方法，例如用 GetEnvironmentVariable 取得環境變數，如此就可以將部分資訊交由環境變數來決定：

而最常用的應該就是 NewLine 了，畢竟不同環境的換行符號可能會不同，養成用 NewLine 的習慣總是好的：

參考資料

C#: 程式碼風格備忘

Igouist (Igouist) — Sat, 25 Jul 2020 00:16:00 +0800

前言：本篇是整理公司規範和網路文章後，方便我自己在各個場所也能回來查閱使用的，故仍會不定時修改（畢竟我這人挺三心二意的）。另外本篇有重新調整過行距，發現有點跑版的朋友可以先 Ctrl+F5 一下，感謝閱讀。

如果你想知道的是如何寫出更優雅、更乾淨、品質更高的程式碼，那並不是該看這篇我個人的備忘錄，我會建議可以閱讀《無暇的程式碼》。或是可以參考這幾篇，我覺得都寫得很好：可不可以不要寫糙 code、Clean Code 無瑕的程式碼閱讀筆記、易讀程式之美學，共勉之。

如果你是正巧路過並且也寫 C#，希望這篇能讓你做為參考。但請記得，程式碼風格沒有絕對，最終還是回歸到團隊能否接受和將來的可維護性去考慮，畢竟教條是死的，人是活的。了解這樣做背後的原因，以及為自己寫的程式碼負責，這些都比對著隻字片語斤斤計較更加重要。

Nothing is true, everything is permitted. —— Assassin’s creed.

2025.01.03 補充：
剛好看到保哥分享了他們家的 C# 程式碼撰寫規範，有需要的朋友也可以作為參考

命名原則

想像下一個接手你程式碼的人是個暴力傾向的重度精神病患者

而且他知道你住在哪。　　—— 《無瑕的程式碼》

使用有意義的命名，請重視描述性。除了迴圈計數器例外
盡量不要超過五個單字
業界和慣例中有對應縮寫時可以使用縮寫
承上，縮寫兩個字母時全大寫，三個字母以上時只第一字大寫

命名空間

基礎類別庫：{組織} . {大類/應用範圍} . {小類/專案名稱}
- MyStudio.Libs.Basic
- MyStudio.Libs.Web.BaseTools
專案類別庫：{專案名稱} . {子專案/類別/用途}
- MyProject.Permiss.Proxy
- MyProject.Permiss.Repository

類別

使用名詞或名詞片語，不使用任何前綴，須和檔案名稱相同類別應該要能夠在 25 個字之內做出描述

基底類別 (Basic Class)：後綴 Base
- public class ProductBase （=產品基底類別）
一般類別 (General Class) 註：抽象類別與一般類別的命名相同
- public class Product （=產品類別）
集合類別 (Collection Class)：後綴 Collection
- public class ProductCollection （=產品集合類別）
工廠類別 (Factory Class)：後綴 Factory
- public class ProductFactory （=產品工廠類別）
Help 類別：應以 Help 名稱、Help 性質方式命名
- public class SystemTimeHelp
有使用 Partial 的類別：檔名按照類別階層命名
- public partial class Core 此類別分散到 Album 和 Banner
  - internal Public class Album -> 檔名為 Core.Album.cs
  - internal Public class Banner -> 檔名為 Core.Banner.cs
列舉：大駱駝峰，並後綴 Enum
- public enum KeywordTypeEnum
介面：大駱駝峰，前綴 I
- ICarFactory

變數、屬性

公開變數使用大駱駝峰，例如 public string Name { set; get; }

私有變數使用小駱駝峰，例如 private int approvalRating，看專案決定需不需要加上底線當前綴

常數一律大寫，但建議使用 static readonly 然後使用大駱駝峰。因為前輩的文件表示過使用常數連結 DLL 時如果修改 DLL 的常數再參考但尚未建置時會導致一些神奇的錯誤

const double PI = 3.14159;
static readonly double Pi = 3.14159;

命名變數時的注意事項：

包含邊界的極值優先使用 min 與 max
閉區間優先使用 first 與 end
半開放區間優先使用 begin 與 end
Boolean 變數開頭必須使用 is can has should 或有狀態差異的形容詞

宣告變數時的注意事項：

變數越多越難記得所有變數
- 減少沒用到的、或對可讀性沒有幫助的變數
變數存活的範圍越大，就必須記越久
- 盡量避免使用全域變數，縮限並控制所有變數的範圍
變數越常改變越難記得目前的數值和意義
- 偏好單次寫入變數，盡量不要過度重複寫入造成混亂
- 當變數內容改變，就可以考慮宣告成新的變數
- 變數的宣告和其命名都是為了讓閱讀者能直接看出改變的差異或當下變數的狀態

方法

一律使用大駱駝峰，前綴字規定如下

擷取
- Get：從資料庫抓回資料
- Search：頁面或定義為搜尋時
- Find：在既有的資料集合找資料
- Fetch：從遠端 (透過API) 獲取資料，例如：`FetchUsers()
- load：從本地端加載資料，例如：LoadFile()
修改
- Update：對資料庫的異動
- Modify：現有變數或資料集合的變動
建立
- Insert：資料庫的資料建立
- Create：資料集合或物件的建立
- Generate：單純產生特定資料供使用
刪除
- Delete：資料庫的資料刪除（資料將不存在）
- Remove：資料集合的資料移除／資料間的關係移除（資料仍存在）
其他
- Convert：代碼轉文字／編碼之間的轉換
- calculate/calc：通過計算獲取資料，例如：CalcBMI()
- show：顯示物件，例如：ShowDialog()
- on：定義 event 的時候使用，像是 OnClick(), OnChange()
- handle：當 OnClick 之類的 event 發生時所觸發的 function

方法中用到的參數視作私有變數，使用小駱駝峰，如 (string name, int age)

如果有泛型直接使用 T 做表示（如 List<T> T1, List<T> T2）

其他注意事項：

比起弄很多大櫃子然後把東西都塞進去，分工明確的小抽屜更方便靈活
輸入參數應該越少越好，如果參數高於三個以上，試著換個思路重構這個方法
輸入參數不要使用傳入 Boolean 來改變類別和函式的行為（違反單一職責）
有多載的需求時，將輸入參數最多的宣告設為 virtual，其他較少輸入參數的則以呼叫最多輸入參數的函式來完成建構
如果類別的名稱已經有足夠的說明，則方法名稱就不需要再複誦一次
- 例如 ProductService.GetProduct() 就是贅詞
- 可以改為 ProductService.Get() 就好
呼叫方法時，如果傳入參數無法直接識別內容，則應使用具名傳遞
- 例如 Get(productId, true) 很難看出來 true 代表的意思
- 可以改為 Get(productId, isInStock: true) 就好
回傳值除了單純的運算式以外，一律回傳變數

2022.01.25 補充：

最近在命名方法時，關於動詞的部份我會參考兩個實用的東東，這邊也分享給各位：

EngTW/English-for-Programmers: 《程式英文》：用英文提昇程式可讀性 (github.com)

已核准的 PowerShell 命令動詞 - PowerShell | Microsoft Docs

斷行與縮排

整潔的程式碼讀起來就像一篇優美的散文

　　—— 《無瑕的程式碼》

不要過多的斷行，也不要都擠在一起，組織成不同的段落
- 方法之間空一行
- 參數過長時斷至下一行
- 程式碼單行欄位數目以不超過 100~120 字元為原則
不要省略括弧，讓程式碼範疇／區塊明顯可見
- 迴圈和 IF 等區塊確實斷行和使用括弧，以維持可閱讀性
- 運算式的優先部分也要加上括弧，方便一眼看出計算順序
使 code 的順序流暢
- 參數按照傳入的順序排列
- 相似方法之間的傳入參數順序盡可能一致
- 相關的宣告和操作放在一起
當因為參數過多的時候必須斷到下一行時，從第一個參數之前就開始斷行
- 因本條規則斷行後，則一個參數獨立一行，必要時具名，使閱讀時能直接往下閱讀
- 不過如果方法參數過多，應先考慮是否重構該方法，極可能違反單一職責
風格一致、風格一致、風格一致

邏輯運算

儘管區塊只有一行（例如 if else），仍一律使用大括號，避免改寫時沒注意到
條件式的左側為「變化值」、右側則是前者的「比較基準」
- 符合口語邏輯：如果你高於 180 公分 => if(lenght > 180)
處理 if/else 的順序時，大多有以下思路
- 先處理肯定的再處理否定的（如：if 成功 else 失敗）
- 先處理簡單的再處理複雜的（如：if 吃了一顆糖 else 吃了兩顆糖以上）
- 先處理比較有趣或明顯的（舉例舉不出來= =）

三元運算式

簡單卻繁瑣的時候使用，但是複雜的時候就乖乖用 if else。例如：

string gender = (member.Sex == "F") ? "女性" : "男性"; 
// 很棒

int result = (exponent >= 0)? mantissa * (1 << exponent): mantissa / (1 << -exponent)
// ？？？

迴圈

迴圈不要用 do/while
- 因為大多數方法和區塊邏輯判斷都在前面，因此使用後置條件會影響閱讀性
減少巢狀結構，不要玩波動拳
- 減少巢狀的有效方法是「儘早返回」：直接離開當前的函式
- 迴圈中可以使用 continue 或 break 來直接進入下一個或離開
- 在方法／函式中可以先處理能直接 return 結果離開的區塊
- 發生錯誤或非預期結果時可以直接擲出錯誤 throw new Exception 中斷程式

存取修飾詞

型別的存取層級，用來控制其他程式碼能不能使用這些型別或內容成員，也就是指定能夠存取的範圍，進而避免誤用、亂用或其他錯誤。

Public
- 可以讓同組件和參考該組件的任何其他程式碼存取
Private
- 只能由相同類別或結構中的程式碼存取
Protected
- 只能由相同類別或結構，或是從該類別衍生的類別存取
Internal / Friend
- 可由相同組件的任何程式碼存取，但是其他組件的程式碼不能存取
Static / Shared
- 用來宣告靜態成員
- 此成員屬於型別本身而不屬於任何物件（＝全實體共用同個成員）
- 不能用在索引子 (Indexer)、解構函式 (Destructor) 以及不在類別裡的型別

註解

基本上對各個格式（如結構、函數）都必須加上說明註解，其中的參數和成員（例如列舉）也必須說明。 VS 中 /// 就會幫忙把參數註解格式打好。例如：

/// <summary>
/// 資料庫連線類別
/// </summary>
public class DatabaseConstants : IDatabaseConstants
{
    // Something
}

重點在於：

簡短敘述，避免模稜兩可或不知去向的代名詞（例如：更新那個東東）
描述函式行為，例如（計算檔案的行數 => 計算檔案中的換行位元個數(\n)）
描述處理過程的原因，要知道做了什麼可以直接看程式碼，要知道為什麼做只能看註解
常數旁邊一定要做原因或用途的說明
函式可以加上範例 <example> Strip("aba","ab") return "a" </example>
移除不需要的註解，例如日誌、署名、重複資訊、被註解掉的 code 之類
使用註解標籤：Todo = 待辦事項； Fixme = 需修復；可搭配 VS 內建的工作清單

附錄：型別

實質型別

包含所有的數字型別、布林、字元和日期，以及結構和列舉

傳值
不允許 Null （除非特別指派 Nullable）
有隱含的預設建構式，不需要用 new
初始化之後才能使用
資料傳遞時是將資料複製到另一個變數

參考型別

能進一步分為陣列和類別型別，其中包含字串、所有陣列、類別、委派和介面。以及匿名和通用型別

傳址
必須要使用 new 建立實體，並將該實體的參考記在變數
資料傳遞時是將參考複製到另一個變數

註記：字串比較特別，實際上比較像一個結構。可以試著當成字元的串列比較好記，可以從 char[] letters = {'H','e','l','l','o'}; 和 string a = new string(letters); 的實驗中感覺到一絲端倪。字串建立後也不允許直接變更，可能是藉此閃避一些更改時的問題。

轉型

隱含轉換
- 屬於安全的轉換，所以不用使用特殊語法
- 小型到大型整數型別的轉換（如 int -> long）
- 衍生型別 (Derived Class) 到基底型別 (Base Class) 的轉換
- 例如 int num = 2147483647; long bigNum = num;
明確轉換
- 資料可能在轉換中遺失或失敗時，需要使用轉型運算子
- 往精確度較低或範圍較小的型別進行的數值轉換（如 double -> int）
- 基底類別往衍生類別的轉換
- 例如 double x = 1234.7; int y= (int)x
使用 Helper 類別轉換
- 在不相容型別間進行轉換時使用（如 int -> System.DateTime）
- 使用 Helper 進行轉換（如 Int32.Parse），例如
  - System.BitConverter 類別
  - System.Convert 類別
  - 內建數字型別 (Numeric Type) 的 Parse 方法
- 例如 string x = "2016-04-08"; DateTime z = System.DateTime.Parse(x)

Pocket —— 稍後閱讀，想看再看

Igouist (Igouist) — Sat, 18 Jul 2020 10:17:00 +0800

備註： Pocket 將在 2025/07/08 下線（官方推文），我個人現在也已經改用 Readwise Reader，有興趣的朋友可以參考 => Readwise io

在兩個多月前，我們介紹過將文章用 RSS 訂閱集中起來的工具 Feedly。但是，有些時候雖然對文章挺有興趣的，但並不適合馬上看（例如在公司或學校的時候，看到社論、科技新聞等等）；或是像我個人平常休息時逛逛一些論壇或是文檔，這時候如果遇到一些比較長的、主題式的文章，就會想要把文章存放起來，等晚些時候再看。

雖然 Feedly 也有提供 Read Later 的功能，只要勾個標籤就可以之後再到 Read Later 的頁面去觀看。但懶惰如我，就會想要把所有稍後再看的文章集中在一塊，因此必須尋找一個前述場景都共用的做法，這時我就遇上了 Pocket。

Pocket 是一個簡單直接的「稍後閱讀」服務，操作方便，只需要擴充套件或分享，和一段能靜下來好好閱讀的時間即可服用。在開始介紹之前，有幾件事必須報告：

如果你和我一樣可能變成倉鼠型玩家，看到什麼都想加到稍後閱讀，可能要當心。建議可以先閱讀一下用「稍後閱讀」過濾資訊洪水的五種層次與六個方法 - 電腦玩物。
就像在 Feedly 介紹中提到的：這類工具是用來幫助我們完成被動接收資訊＋主動篩選資訊的，莫要忘記原則，否則真的很容易看不完看到超載，心會很累。
如果你是 Android 或 iOS 的使用者，由於 Pocket 有提供網頁和 APP 等平台，但本篇以電腦的操作為主，使用手機操作的朋友可以參考 Pocket 稍後閱讀 APP，收藏想看的文章和網頁！這篇的說明。
如果你已經決定要尋找稍後閱讀功能的工具，可以參考 10個稍後閱讀書籤服務大評比！Pocket、Instapaper、Diigo還有更多！本篇並不會提到別的工具。

介紹

首先，我們得先到 Pocket 申請一個帳號，我個人是直接使用 Google 帳號做登入。成功登入之後應該能到 Pocket 的大廳：

我們之後儲存的文章就會出現在這裡。上方工具列還有探索的功能，但我個人試過之後大多都是英文文章，對我這種英文白癡派不上什麼用場。

接著讓我們安裝 Chrome 的擴充套件：Save to Pocket。

之後我們直接找個一篇文章做示範，然後讓我們按下擴充套件的 Pocket 按鈕…

（如果是手機使用者，這邊就是把目標網頁分享給 Pocket App）

再回到 Pocket …

就成功把文章存下來啦！

點進去之後可以發現，它和 Notion、Evernote 那些筆記軟體的擷取方式一樣，是將文章內容擷取出來。

當然，作為一個閱讀服務，Pocket 服務該有的都有。

畫面上方有一些基礎操作的工具列，例如替文章內容畫線、或是將文章加上分類標籤、進行封存和刪除等等。此外，右上方也能調整閱讀版面的設定，但除了基本的主題色彩和字體大小以外，更客製化的設定選項就必須付費才能取得了。

（當然，如果像我這種有在使用簡閱這類閱讀擴充套件的話，這部分就不會有什麼問題了XD）

Pocket 作為稍後閱讀的暫存站，我個人是免費就用得很開心。如果有需要無限期存放文章或是無限標籤等需求，請再前往升級頁面參考。

註：Pocket 也有提供朗讀文章的功能，需要的時候可以用聽的，不過我個人沒有試過，因為遇到需要用聽的情景的話，我會跑去聽 Podcast。如果有聽文章習慣或是有興趣的朋友，可以參考[生活駭客3] 開始「聽」文章，日常時間加一倍的魔法

稍後閱讀功能的服務還挺多的，我之所以最後選定使用 Pocket，有一大半原因是因為我發現它能和我的 Kobo 電子書閱讀器同步。作為一個通勤搭車每天動輒一兩小時的上班族，搭車時間拿來看看書看看文章真是再愜意不過了。但由於我真的很懶，捷運又常常站著，書還是挺重的不方便帶來帶去，所以後來我還是毅然決然踏入閱讀器的世界，這時候我才發現了 Pocket。

利用 Pocket 我就能把早上從 Feedly 看見的部分文章，挪到上下班搭車的時候再用輕便的電子書閱讀，豈不妙哉。

示意圖（單純只是想秀一下閱讀器）

利用 Pocket 我就能把想讀的文章同步到網頁、APP 和閱讀器等各平台，並利用碎片時間來看個一兩篇，既分散了有時遇到太多篇想看的文章的那種壓迫，瑣碎時間也不用再煩惱要幹嘛就能順手看一下，對我這種懶得想當下要幹嘛的人，真的是挺有幫助啊。

結語

所有的工具都是為了完成整體流程的某個環節而存在，凡如開發功能、佈 CI/CD 環境、或是專案管理具等等，我們無不利用各項工具和技術的搭配來組合成我們需要的流程。當然，資訊篩選也是如此，Pocket 提供了延後閱讀的服務，但這個服務的使用方式取捨於個人的習慣。如果能像電腦玩物說的，在把文章丟進稍後閱讀時，能先想一想「這則資訊我真的想要認真讀它嗎？」如果是，那麼我就相信 Pocket 一定能夠幫上忙。

我個人現在的習慣方式是：

從 Feedly 取得篩選來源的文章，或是有空閒時從常用的幾個論壇和網站，從中挑選有興趣的讀
若是當天有興趣的太多，或是文章過長不適合當下閱讀，就利用 Pocket 暫存起來
閱讀後，將認為有價值或喜歡的文章存放到 Notion 並分類
需要的時候，例如用到相關技術或想分享文章給朋友，就從 Notion 中的分類提取文章出來

藉由這些工具組成了一個每日固定的閱讀流程，並穩定地增加庫存（對我本質還是倉鼠型），目前為止我都還覺得挺不錯的，這邊分享給各位。

最後的最後，因為真的覺得電子書很讚，還是想推廣一下。如果有對電子書有興趣的朋友，可以看一下以下這兩篇，整理得相當不錯，優缺點都有列到，尤其是閱讀前哨站那篇的 Q&A 整理部份已經涵蓋最常遇到的問題，推薦在考慮入坑時讀個一遍：

那麼今天的分享就到這裡，如果有不錯的工具或是建議，也歡迎不吝提出。那麼，我們下周見！

參考資料

菜雞與物件導向 (7): 介面

Igouist (Igouist) — Sun, 12 Jul 2020 23:53:07 +0800

如果說繼承是用來表明物件「屬於什麼」；那麼介面就是用來表明物件「能做什麼」。

如果說封裝是將物件視作一個整體，是隱藏複雜度；那麼介面就是封裝精神的體現。

如果說多型是指藉著繼承後能實作不同的行為的可能性達到擴展的彈性；那麼介面就是在實作多型。

介面就是這麼厲害，這麼瀟灑。介面就是我大哥，今天誰不服介面，對不起！我們不認識。

介面就像是針對類別的實作、物件的行為去做規定的一個契約書，會先定義好要實作這個介面的類別所必須要有的方法，而當我們建立符合這個介面的類別時，就必須實作出所有介面中定義好方法才可以。……這樣說起來實在太繞口，總而言之介面的核心概念只有一條：

我不在乎你是誰，我只在乎你能做什麼。

還是公司誠徵工程師的例子

由於介面基本上就是封裝繼承多型抽象之大雜燴，所以我們把前面多型的小明小華例子稍微修改來用吧。也就是以公司徵人的方式去理解介面。

介面就像是老闆開出來的要求列表，例如說：要會寫 C#、要會寫 SQL、要會 VB…等等，於是老闆就貼出了徵人啟示，要求新來的員工必須要有 IProgrammer 寫的能力：

public interface IProgrammer
{
    void WriteCSharp();
    void WriteSQL();
    void WriteVB();
}

特別注意和前面多型的例子的不同處，介面只需要先定義好該做的事，裡面怎麼做不需要管；所以只需要宣告要求的方法，不需要撰寫方法本體。

於是今天小華就又(?)來面試了，但是他其實並不會寫 C#：

public class Hua : IProgrammer
{
    // Error: Hua 未實作 IProgrammer.WriteCSharp()

    public void WriteSQL() { /* Work */ }
    public void WriteVB() { /* Work */ }
}

這時候編譯器就會跳出錯誤了：很抱歉，你不符合我們 IProgrammer 的規定，因為我們只喜歡訓練精英（略），請你實作完之後再來。否則你就不能掛上我們 : IProgrammer 的頭銜。

雖然小華面試失敗了，不過至少小華幫我們示範了一件事：類別要標上介面的方法就和繼承一樣，在類別名稱後面加上 :

而小華走了之後，馬上就輪到小明開開心心地來應徵了，他不只會寫 C#、SQL 和 VB，甚至還會泡英式奶茶：

public class Ming : IProgrammer
{
    public void WriteCSharp() { /* Work */ }
    public void WriteSQL() { /* Work */ }
    public void WriteVB() { /* Work */ }
    public Tea MakeTea() { return new Tea(teaName: "MilkTea"); }
}

火速通過面試之後，老闆就讓小明上工了：

public void Work()
{
    IProgrammer programmer = new Ming();
    programmer.WriteCSharp();
    programmer.WriteCSharp();
    programmer.WriteCSharp();
}

在這個時候，小明已經不再只是小明，對老闆而言他就是一個符合應徵要求的工程師，這裡只需要「我（老闆）要求能做這些事的人」而不是「小明」，是 IProgrammer 而不是 Ming。在呼叫 IProgrammer programmer = new Ming() 的同時，這裡就只剩下一個無情的寫程式機器，再也沒有小明。

上面這句雖然和多型範例的說明九成一樣，但絕對不是我偷懶（真的），差異的地方就是介面的本質。可以稍加對照看看。

當然，小明仍然不准在上班時間泡英式奶茶。

public void Work()
{
    IProgrammer programmer = new Ming();
    programmer.WriteCSharp();
    programmer.MakeTea(); // Error: IProgrammer 未包含 MakeTea 的定義
}

多型的時候，這個原因是由於今天的小明是工程師，工程師不需要會泡奶茶。也就是說子類別替代父類別時不需要那些父類別不會的動作。此處也是一樣的精神，我們要的是一個會寫程式的工程師，不是介面規範上的東西我們不需要。

這是達成關注點分離和職責分離必經的道路，習慣之後對於公開方法和私有方法也會有更進一步的心得，以公開方法實現介面的要求，配合私有方法拆解內部的複雜度，甚至組合多個介面讓類別具有多項能力，這個過程只能用舒爽來形容（前提是介面不要開得太爛的話啦）。

變更的彈性

介面作為特性的體現，更多的是概念上的東西。最後這一小段就讓我們聊聊這些部分。

在新訓時改變我想法最多的就是介面，在這之前我只會一個函式硬寫到底，而習慣從介面開始設計物件後，才開始從功能的角度去想要怎麼寫。

介面不同於前面各項特性是告訴我們物件應該有什麼特徵，而是要求我們用「不同功能的物件之間對接時，我們該怎麼處理」的角度去看待問題。

介面的核心概念在於提供了更多的彈性，更精確地說是變更的彈性。

原本是連線到 MySQL 取得資料，哪天突然就必須更改成要連線到 MongoDB 取得資料；

原本是只要實作出使用者儲存訂單的操作，突然接到指令說使用者必須區分成一般使用者和尊爵用戶並且實作出不同的操作流程等等。

變更總是來得又急又快，而這也讓我們靜下來想，當我們把關注點放在整個邏輯的時候－－

我需要的是「連線到 MySQL 取得資料」的工具嗎？並不是，只要是「能連線到資料庫、能取得資料」就好了。

我需要的是「以ＯＯＯ技術替使用者建立訂單並儲存」的工具嗎？並不是，「替使用者建立訂單並儲存」才是最重要的。

資料庫是可以替換的，儲存訂單到資料庫的工具也是可以替換的，甚至替使用者建立訂單的過程也是可以替換的。

因此，從介面開始設計時最重要的是釐清「我需要的是什麼」，用介面定義一份契約，把使用對象和實作銜接起來；並且把實作隔離成可替換的部件，達到解除耦合的目標。

最後還是回到了關注點分離的議題：主流程、商業邏輯專心做好自己的事，他們只需要知道這個物件能夠提供拿到資料的方法就好。而實際上怎麼拿到資料，則由實作的物件內部去處理，也就是封裝的核心精神。

要理解介面的概念，訣竅在於把目光更集中在「功能」的角度。我們在理解物件的時候，可以知道冰箱是一個物件、冰櫃是一個物件、保冷袋是一個物件；但當我們在海邊釣到魚，想要找個地方保存的時候，我們需要的是冰箱嗎？是冰櫃嗎？是保冷袋嗎？

都不是，我們需要的是「能低溫保存食物的東西」而已，今天你能用冰箱從海邊運到你家也沒關係，只要你實作得出來，並且魚是新鮮的就好。於是我們把觀看物件的角度集中在它的功能上，我們針對我們的需求去定義好我們需要的功能，這就是介面。

我們定義好什麼叫做飛行，於是鴿子跟烏鴉都算是實作了飛行；我們定義好什麼叫做游泳，於是海豚跟鯨魚都算是實作了游泳。

只要你符合我需要的功能，達到我要的目的，不論你是誰，你如何實作，我都無所謂。

如此我們既達到了關注點分離，也保留了定好規則，將來可以使用不同實作的彈性；甚至將來接手的是另一個人，他看你的介面就能知道如何替換，替換時對象至少要能做到哪些事，今天他接到需求是上頭覺得保冷袋太 Low 了，我們要改用冰櫃車，他也有個接口／介面去指示他修改的方向。

而在兩個系統，或是兩個分層之間要介接的時候，只需要提供我這個功能需要的接口／介面給對方，就能讓對方知道他必須實作哪些功能，如果我們要把運魚的需求託付給貨運公司，他看介面就知道我們要的是「低溫保存食物」，便可以提供對應的服務／實做給我們。如此豈不美哉！

備註：一些有寫過前後端銜接的，或是做過一些小工具的到這邊可能會覺得有點熟悉。例如說：程式和使用者銜接的點，叫做使用者介面；前端跟後端交換資料的 API，叫做應用程式介面。所謂的介面／接口就是這麼一回事，這裡也不例外。

小結

到這邊我們就介紹完介面的部分了，希望各位朋友能夠大概感覺到介面的精神。

當然有些讀者看到這裡可能也會有點疑惑：

像上面的例子中 IProgrammer programmer = new Ming(); 當我們宣告的當下不就還是知道了我們實作的對象是 Ming 了嗎？這樣並沒有完全分離呀？（依賴注入熱身中）

等等諸如此類一堆問題，都也是我有過的想法，在接下來的新訓系列也將會逐漸說明，欲知後續如何，且待下回分曉！

本系列下一篇：菜雞與物件導向 (8): 內聚、耦合

參考資料

同系列文章

菜雞與物件導向 (6): 抽象、覆寫

Igouist (Igouist) — Sun, 12 Jul 2020 23:53:06 +0800

備註：這邊的抽象是指程式語言中的抽象類別，而非抽象化

抽象的概念很直接，請回想一下前面的例子就可以了：

當我們在用卡牌的例子時，雖然怪獸卡跟魔法卡都繼承了 Card 這個類別，但是我們仍然能
new Card() 來建立一張新卡牌，那…怪怪的吧，這張卡牌到底是什麼呀，空白的卡片嗎？

又或是動物的例子，我們的狗跟貓都繼承了哺乳類，那我們能實例化一個哺乳類嗎？我們的狗跟鳥都是動物，那我們能實例化一個動物嗎？

小明跟小華都繼承了工程師，那我們能 new 一個工程師嗎…？

有些類別就是這樣，它們負責定義共通的那些特性，然而它們本身不應該被實體化成一個物件，這種類別我們就應該把它們標記為抽象類別。

抽象類別在 C# 裡用 abstract 這個修飾詞來表示，可以加在類別或方法上。例如 abstract class Animal 就代表動物這個類別是個抽象類別，它不能被實例化。

而當加在方法上時，例如 public abstract void Eat() 就是代表這個進食的方法無法被叫用，只能由繼承者去重新定義這個方法。

abstract class Animal
{
    public string color { get; set; }
    public abstract void Eat();
}

那麼繼承者們，也就是衍生類別如何去重新定義父類別的方法呢？

~~所謂「欲戴王冠，必 Override」~~，這時候就必須使用覆寫（override）。

覆寫是指對於像是前述的抽象方法時，在同名的方法前加上 override 關鍵字就可以讓程式知道你要覆寫這個方法（你不覆寫的話，編譯器還會生氣）。

例如前述的 Eat，狗就可以用 public override void Eat() 的方式去覆寫吃東西這個方法：

public class Dog : Animal
{
    public string color { get; set; } = "Black";
    public override void Eat()
    {
        /* 嚼嚼嚼 */
    }
}

但有時候我們只是希望秉持著多型的精神，讓子類別有可以重新定義的彈性，這時候我們就會使用
虛擬（virtual） 的方式去標記這個方法，如此一來就可以實作，同時也讓子類別可以覆寫。

例如可能狗有 public virtual void Eat() 這個進食的方法：

public class Dog
{
    public virtual void Eat()
    {
        /* 嚼嚼熱狗 */
    }
}

那假設我們有個 Giwawa 繼承了 Dog，但牠也是吃熱狗的，就可以選擇不去覆寫 Eat()：

public class Giwawa : Dog
{
    /* 不打算實作 Eat，直接使用 Dog 類別的 Eat */
}

而當我們有了 RobotDog 這個類別，它就可以繼承並且重新改寫掉 Eat() 這個方法，從吃肉變成喝汽油。

public class RobotDog : Dog
{
    public override void Eat()
    {
        /* 嚼嚼汽油 */
    }
}

除了使用 override 去覆寫父類別的方法以外，也可以用 new 去隱藏父類別的方法：

public class CyberDog : Dog
{
    public new void Eat()
    {
        /* 嚼嚼汽油 */
    }
}

override 和 new 的差別在於多型時轉型成父類別時的行為：

override 會直接取代掉父類別的方法，即使轉型為父類別還是以子類別的實作為主
new 則是會建立一個子類別專屬的方法，若轉型為父類別就會變回父類別的方法

我們直接用例子來看看吧，假設我們現在有「拉不拉多」和「機器狗」，都繼承了「狗」。差別在於拉不拉多 override 了 Eat() 這個方法，而機器狗 new 了 Eat() 這個方法：

public class Dog
{
    public virtual void Eat() 
    => Console.WriteLine("吃了熱狗");
}

public class Labrador : Dog
{
    public override void Eat() 
    => Console.WriteLine("吃了超大熱狗");
}

public class RobotDog : Dog
{
    public new void Eat() 
    => Console.WriteLine("喝了超多汽油");
}

接著讓我們來看看當他們被實例化之後，以及被轉型為父類別的時候的 Eat() 有什麼不一樣吧：

// Labrador => override
var lala = new Labrador();

lala.Eat(); // 吃了超大熱狗
((Dog)lala).Eat(); // 吃了超大熱狗

// ==============================

// RobotDog => new 
var robot = new RobotDog();
robot.Eat(); // 喝了超多汽油
((Dog)robot).Eat(); // 吃了熱狗

可以看到使用 new 來覆寫的 RobotDog 在被轉型為 Dog 的時候突然就變回吃熱狗了！

要特別注意的是：當你覆寫了父類別的方法，卻忘記加上 override 的話，默認會當成是要 new，所以覆寫的時候還是小心一點，具體地把 override 或 new 寫出來吧！

關於抽象和覆寫這部份的範例，因為我個人碰觸的比較少，唯恐我的舉例不夠深入，這邊再附上幾個不錯的範例，可以作為參考：

接著下一篇，我們就接著看這一部分的最後一片拼圖：介面吧！

本系列下一篇：菜雞與物件導向 (7): 介面

參考資料

同系列文章

菜雞與物件導向 (5): 多型

Igouist (Igouist) — Sun, 12 Jul 2020 23:53:05 +0800

多型算是比較三特性之中給人感覺比較溫和的了，不如說只要有了繼承，那麼多型的到來就是必然的。多型的定義是：不同的物件能夠做出一樣的行為，但必須由他們自己的程式碼來實作。

白話一點說就是：一樣的事，不同做法。

多型相對是比較好理解的，畢竟每個人做同一件事的方法本來就不太一樣。例如一樣是泡奶茶，英國就正常地泡，美國就會用微波爐；一樣是肉粽，有些人就是比較愛吃油飯；到了程式的世界裡也是，即使繼承了同一個物件，實現這個行為的方式也可以不同。

在此可以先推菜鳥工程師肉豬的這篇 Java 什麼是多載(Overload), 覆寫(Override), 多型(Polymorphism) 中的說明。其中可以從例子看到儘管狗跟鳥都是繼承自動物這個類別，但對於「移動」這個方法，他們實作的方式並不一樣。這就是多型的範例。

我個人更喜歡用職位的方式去理解多型。

被繼承者就像是該職位的工作，例如說：Programmer 要會寫 C#、要會寫 SQL、要會 VB…等等，於是老闆就貼出了徵人啟示，要求新來的員工必須要有 Programmer 寫的能力：

public class Programmer
{
    public virtual string WriteCSharp()
    {
        /* 努力地寫 C# */
    }
    public virtual string WriteSQL()
    {
        /* 努力地寫 SQL */
    }
    public virtual string WriteVB()
    {
        /* 努力地寫 VB */
    }
}

補充說明：這邊用到的 virtual 和 override 這兩個關鍵字
我們會在下一篇的覆寫進行介紹。有興趣的朋友也可以先偷看一眼呦！

於是今天小華就來面試了，不過他寫的程式碼品質…不怎麼樣。

public class Hua : Programmer
{
    public override string WriteCSharp()
    {
        return "ShitCode";
    }
    public override string WriteSQL()
    {
        return "ShitCode";
    }
    public override string WriteVB()
    {
        return "ShitCode";
    }
}

而小華應徵的隔天，小明也開開心心地來應徵了，他不只 C#、SQL 和 VB 都寫得很好，甚至還會泡英式奶茶：

public class Ming : Programmer
{
    public override string WriteCSharp()
    {
        return "CleanCode";
    }
    public override string WriteSQL()
    {
        return "CleanCode";
    }
    public override string WriteVB()
    {
        return "CleanCode";
    }
    public Tea MakeTea() 
    { 
        return new Tea(teaName: "MilkTea"); 
    }
}

火速通過面試之後，老闆就讓小明上工了：

public void Work()
{
    Programmer programmer = new Ming();
    programmer.WriteCSharp(); // "CleanCode"
    programmer.WriteCSharp(); // "CleanCode"
    programmer.WriteCSharp(); // "CleanCode"
}

過了幾天後，老闆決定讓小明和小華一起寫同個專案：

public void newProject()
{
    Programmer programmer001 = new Ming();
    Programmer programmer002 = new Hua();

    programmer001.WriteCSharp(); // "CleanCode"
    programmer002.WriteCSharp(); // "ShitCode"

    programmer001.WriteCSharp(); // "CleanCode"
    programmer002.WriteCSharp(); // "ShitCode"
}

這裡也就是多型的核心概念，用子類別實作出各式各樣不同的方法，藉此讓父類別的方法藉此達到延伸和多樣化的效果。

例如說一樣是 Programmer 的 WriteCSharp() 這個方法，小明的實現就是 return "CleanCode"; 而小華的實作方式則是 return "ShitCode";。

同樣地，最常被舉的例子就是動物。當有動物這個類別時，儘管狗跟貓都繼承了這個類別，但他們都可以對「叫聲」做出不同的實作。

因為有了多型，動物這個父類別，就能夠藉由子類別來完成擴展。更進一步來說，藉由子類別的擴展，我們能夠讓父類別做出各式各樣的事，而不需要更動父類別本身。

最常碰到的例子就是資料庫連線。例如說，我們可以讓 MySqlDBConnect 和 MongoDBConnect 都繼承 DBConnect，但各自保有對應不同資料庫的實作。

如此一來，DBConnect 就獲得了用不同方法連線到不同資料庫的擴展，得到了對應狀況靈活使用的彈性。同時，使用 DBConnect 物件的其他物件也可以不用管現在的 DBConnect 連線是哪個子類別來工作的，只要知道能夠連線並取得資料就好，也達到了以封裝降低耦合的要求。

以上就是多型的核心。但當我們把子類別塞到父類別的殼裡面使用的時候，還需要注意：這時候的子類別已經是父類別的形狀了

當我們將小明宣告成工程師這一瞬間，小明已經不再只是小明，對老闆而言他就只是一個工程師，這裡只剩下「工程師」而不是「小明」，是 Programmer 而不是 Ming。

在 Programmer programmer = new Ming() 執行完畢的同時，這裡就只剩下一個無情的寫程式機器，再也沒有小明。

當然，小明也不准在上班時間泡英式奶茶，我們不是請你來做這個的！

public void Work()
{
    Programmer programmer = new Ming();
    programmer.WriteCSharp();
    programmer.MakeTea(); // Error: Programmer 未包含 MakeTea 的定義
}

這樣只會讓編譯器尷尬地說：請你照我們契約書上面走好嗎？畢竟這裡只剩下 Programmer 而不是 Ming 了，一個無情的寫程式機器是不需要，也不會知道怎麼泡英式奶茶的。

這邊我們就能知道：當子類別被以父類別的名義建立出來時，他就只能夠表現出父類別的樣子。換句話說，我們宣告的是什麼，他就只會做什麼，但要怎麼做倒是沒關係。雖然是一個令人悲傷的故事，但為了遵守封裝的精神，讓呼叫的物件不需要去了解是誰繼承、又由誰實作等等，為了物件界的秩序，這也是莫可奈何。

最後再說一聲，大話設計模式用兒子代替爸爸上台表演京劇的例子實在舉得很不錯，有興趣的可以去看看，這例子很能表現出那種披著父親的皮，用著自己的技術，但遮著臉不能被發現的感覺。如此傳神！

到這邊三大特性就說明完了，雖然我說明的相當模糊籠統，但希望概念能夠傳達到。

畢竟，就像我開頭引用的，我很喜歡這句「如果你問 100 個人這個問題，可能會得到 200 個答案，所以你一定要有自己獨到、有自信、精闢的見解或描述方式。」像我女友，當我問他物件導向的時候，她（大致上）是這樣說明的：

封裝：醬包跟麵的工作都在泡麵工廠做完了，我們只要拿來泡就好
繼承：我們可以買了泡麵之後，再自己加蛋加料
多型：一樣是泡麵，實作出來的口味都不一樣

說得我都要去買一碗來煮了。但是，物件是為了貼近我們的現實世界，而每個人的世界觀本來就不一樣。你必須自己體會，然後才會有自己的觀點。

至於那些說：你不是說要用卡牌當範例，怎麼突然多了個工程師小明小華？我只能說抱歉，洗澡的時候突然想到的，不寫不舒服。卡牌就想到再補吧，耶嘿。

下一篇開始就要進入抽象等等更模糊籠統的部分了，希望還能穩住哪。

本系列下一篇：菜雞與物件導向 (6): 抽象、覆寫

參考資料

同系列文章

菜雞與物件導向 (4): 繼承

Igouist (Igouist) — Sun, 12 Jul 2020 23:53:04 +0800

接著要介紹的是繼承 aka 物件導向三大特性之王 aka 濫用榜 Ko.1 ，繼承的強大幾乎和它的惡名一樣可怕，給一個從聊聊程式的這篇 [心得整理] c# 物件導向程式 - 2.封裝、繼承、多型的三大特性摘過來的例子就可以略知一二了：

什麼也不做，僅僅只是繼承而已，就取得了繼承對象（C# 中稱為基底類別）近乎全部的內容，真是太可怕了。在 C# 中，繼承可以取得基底類別除了 Private 以外所有的內容，例如 Protected 更是表明就是只給繼承使用的。

由此可見，在減少重複程式碼的路上，繼承無疑達到了全新的高度。

那麼繼承代表的是什麼意思呢？大多的網站都能直接說明：繼承是一種「is-a」的關係。當你能說出Ａ是一個Ｂ的時候，就代表你認為Ａ可以繼承自Ｂ。

最直覺的繼承例子就是物種的分類。舉例來說，狗跟貓都是哺乳類，因此他們都可以繼承到一些哺乳類共通的特徵（例如哺乳、用肺呼吸）。藉由繼承，我們可以把這些哺乳類共有的特徵全部放在哺乳類這個物件，再由狗和貓分別去繼承哺乳類，藉此讓他們都能得到哺乳類的特徵，再進一步發展出自己的特徵和行為，甚至重新定義基底類別的方法為自己所用。因此，像大話設計模式就將繼承說明如：繼承者是對於被繼承者的一種特殊化。

如此一來，當我們需要修改哺乳類的定義的時候，只需要修改一個地方，而繼承了哺乳類的這些物件（C# 中稱為衍生類別）全都能夠一起修改到，大大地減少了跑來跑去修改的次數，也讓程式碼的重複大幅度地減少。

然而也因為如此，繼承最大的惡名出現了：繼承享受了取用基底類別內容的好處，卻也必須背負牽一髮動全身的風險。

繼承的特性和封裝有天生的衝突。為了從封裝好的物件之中取得內容，減少程式碼的重複，我們有了繼承，然而這樣無疑破壞了基底類別的封裝，完整地暴露給了衍生類別，兩者之間形成了強耦合的關係。

對於衍生類別而言，它必須依賴著基底類別，倘若哪天基底類別的屬性變更了，例如型別或名稱有變動，那麼所有衍生類別使用到的地方都會受到影響，這時候在程式碼裡的修改規模，將會隨著繼承的濫用程度提升，達到一個相當龐大的地步。

事實上，這是相當好理解的。我們藉由哺乳類去繼承出了狗科跟貓科兩個類別；那麼假設我們時光回溯，重新改變了哺乳類的演化過程，今天的哺乳類變成了三隻腳而且還有翅膀，那麼後面演化出來的狗跟貓又會怎麼樣呢？直接修改源頭，對後續的衍生者而言無疑是相當大的災難。

同時由於繼承的方便和概念實在相當廣泛，因此也經常被胡亂使用。我個人就遇過專案之中，前人為了讓某個類別擁有各式各樣的方法，先後繼承了數學運算、連線至資料庫、畫面上的資料處理等等數個類別，形成一條既長又龐大的繼承鏈，最終達到了無法修改的地步。

沒有人知道這個合成怪獸是來做什麼的，這種神之物件搖身一變就變成滅世主宰，實在是相當恐怖。

因此對於繼承，前輩們通常只有一種叮囑：謹慎使用，或是乾脆不要用。

對於繼承的概念，這邊推薦可以看看，到底誰該去繼承誰？物件導向初學者應該要知道的事情(三) 這篇從圓和橢圓的各種繼承方式切入，很仔細地講解了不同思路使用繼承遇到的問題，尤其是示範完直覺的做法之後展示經典的段落相當重要。

另外，我們在後續的里氏替換原則也會提到繼承需要注意的一些問題，此處暫且按下不表。

那麼我們就回到卡牌的例子：

假使我們的卡牌現在有了功能卡，這類卡牌在遊戲王叫做魔法卡，而在爐石稱之為法術，雖然這也是一種卡片，但和前面提過的戰士和怪獸等等顯然完全不同。

public class MagicCard
{
    public string Name;
    public int Cost; // 資源花費
    public Magic Effect; // 法術效果
    private string _description;

    public MagicCard() { /* 建構式 */}
    public string Description { /* set; get; */} 
}

魔法卡並沒有攻擊力和生命值，只有對應的法術效果。同時，我們發現卡牌有資源花費的需要，像是爐石戰記或是殺戮尖塔這類有資源的遊戲，打出卡片的時候會需要花費水晶等資源，藉此限制玩家一回合內能使用的策略。

現在我們明顯可以發現兩個問題：這兩個種類的卡片，都是卡片呀！而且，內容有一半都是重複的。這是我們該使用繼承的時機了。

首先我們將原本的卡片更改為怪獸卡。

public class MonsterCard
{
    public string Name;
    public int Cost;
    public int Attack;
    public int Health;
    private string _description;

    public MonsterCard() { /* 建構式 */}
    public string Description { /* set; get; */} 
    public void Hit(MonsterCard target) { /* 一些痛揍其他怪獸卡的方法 */ }
}

接著我們開始設計基底類別：卡片。我們可以觀察到，怪獸卡和魔法卡相同的部分有：名稱、敘述和卡片花費。

public class Card
{
    public int Cost;
    private string _description;

    public string Description { /* set; get; */} 
}

將原本的怪獸卡和魔法卡改成繼承自卡片類別，並且將重複的部份移除，直接取用基底類別的內容就好。

public class MonsterCard : Card
{
    public int Attack;
    public int Health;
    public MonsterCard() { /* 建構式 */ }
    public void Hit(MonsterCard target) { /* 一些痛揍其他怪獸卡的方法 */ }
}

public class MagicCard : Card
{
    public int Cost;
    public Magic Effect;
    public MagicCard() { /* 建構式 */}
}

可以看到我們在 C# 的繼承方式是使用 類別 : 基底類別 的方式來宣告。並且也能發現，怪獸卡的內容變簡潔了。

var goblin = new MonsterCard(name: "哥布林", attack: 3, health: 2);
var warrior = new MonsterCard(name: "戰士", attack: 4, health: 3);
warrior.Description = "他是一個專殺哥布林的戰士！";
warrior.Hit(goblin);

並且在使用上也沒有任何差錯，我們仍然能給予怪獸卡名字和敘述。

當然在實際的卡牌遊戲中，魔法卡還能細分出更多種類，因此魔法卡類別還能再被一些更細的分類，例如指向法術等等去繼承，形成如同樹狀的繼承關係，如同物種演化一般。

繼承的段落也快結束了，這邊再次叮嚀一番：除非你很確定，否則請不要使用繼承。

繼承帶來了相當大的好處，減少的重複程式碼量號稱三特性之冠；但同時他帶來的後果也是最嚴重的，堪稱三特性中的擊墜之王，鏖殺了數以萬計濫用和誤用的工程師…和維護他們系統的工程師，不可不慎。

但如果已經看到了這裡，還請你先記著繼承的概念，在不遠處的將來你將會遇到他那不太像又有點像的兄弟：介面。這邊就先打住。下一篇就讓我們繼續來看三特性的末席：多型吧。

本系列下一篇：菜雞與物件導向 (5): 多型

參考資料

同系列文章

菜雞與物件導向 (3): 封裝

Igouist (Igouist) — Sun, 12 Jul 2020 23:53:03 +0800

封裝包含了兩個重要的觀念：

控制物件和外部進行互動的出入口
隱藏物件內部的細節資訊

強者我同事整理的文章裡的例子就舉得不錯：當你按下鍵盤的Ａ鍵，螢幕隨即出現了Ａ，你不必知道中間發生了什麼事，你只需要知道怎麼操作和最後得到什麼就可以了。

其中鍵盤提供的按鍵，就是我們對電腦進行互動的出入口；而電腦實際上做了什麼事情，也被隱藏了起來，讓我們只需要關注結果就好。

此外我也看到過販賣機的例子，當你去販賣機買飲料，你也不需要知道裡面的構造，只要知道你選了飲料投了錢，飲料就會跑出來就行。

從上面的兩個例子，相信大家已經掌握到封裝的概念了：將物件視作一個整體，把內部的實作內容隱藏起來，讓使用者只需要知道怎麼使用這個物件即可。（相似的思路，我們後續的介面會再提到）

如果封裝做得夠好，除了可以將程式碼整理得井井有條以外，也能讓物件內部的修改不會直接影響到使用物件的地方，達成了降耦合的目標

並且也能讓物件的使用者直覺地知道如何使用物件提供的方法，如此使用者就可以專注在更高層次的抽象，而不用被物件內部的細節所干擾。

最後，從上面的敘述中我們可以察覺到要實現封裝，最重要的就是：對外的開放程度（存取範圍）的控制。或是套一句前輩的說法：給程式碼隱私的空間。

補充：如果想問「什麼是耦合？」的朋友，建議可以看看這篇：實務上的高內聚與低耦合

或是參照本系列後續的內聚與耦合

存取範圍與存取子

先讓我們從存取範圍開始說起吧，因為我個人慣用的是 C#，因此就介紹一下 C# 是怎麼控制存取範圍的。

在 C# 之中，類別裡控制可見度是使用修飾子來定義存取範圍，也就是當我們替類別宣告欄位時常看到的 Public 和 Private。

Public: 這是公開的，所有人都看得到
Private: 這是私有的，只有自己看得到

除了最常用的這兩個以外，還有其他的修飾子可以先知道一下：

Protected: 這是受到保護的，只有自己和繼承的孩子們看得到
internal: 這是內部的，只有身為同一個組件的朋友們看得到
Protected internal：組合上面兩個，也就是可以給同個組件的朋友們，或是其他組件繼承的孩子們看見

接下來的部分會以最常見的 Public 和 Private 來繼續說明，對存取範圍的這些修飾子有興趣的朋友，可以參照存取範圍層級的說明。

現在我們已經知道了有哪些修飾子可以用來控制存取範圍，但為什麼我們會需要宣告存取範圍的大小呢？其根本是為了將控制權掌握在物件本身。

就像大話設計模式比喻的：物件就像間房子，我們不希望被看光光，可以看見的 Public 就像門和窗，而不該看見的 Private 則是用牆壁隱藏起來，而對於這間房子而言，門窗是可以控制的。

對於這部分的範例，我覺得微軟文件的範例裡設定月份的區塊已經能很清楚表達了。但為了這篇文章的一致性，還是硬擠著一個範例出來：

某一天，我們突然決定讓使用者可以傳入卡牌敘述了，但是卡牌上能顯示的字數有限，只能顯示 30 個字，因此首先我們先把卡牌敘述改成私有的：

public class Card
{
    public string Name;
    public int Level;
    public int Attack;
    public int Health;
    private string _description; // 更改為私有的

    /* 一些其他方法 */
}

呃可能第一步就會讓人有些疑惑：「啊你要給人家傳東西進來還改私有？」但等等，且聽我娓娓道來：C# 中的屬性，是用 Set 和 Get 兩個方法去存取的，又稱做存取子。這兩個看門仔也就擔當了房屋的門窗、出入境時的海關、古代大戰中的關隘這類「控制進出通道」的角色。

現在讓我們試著規劃出我們的門和窗，在上面的例子中，我們想要當卡牌的敘述進來時，保持在 30 個字：

public class Card
{
    // 略
    private string _description;

    public string Description
    {
        set
        {
            if (value.Length > 0 && value.Length < 30)
            {
                this._description = value;
            }
            else
            {
                throw new System.Exception("就跟你說限 30 個字看不懂喔！");
            }
        }
        get
        {
            return this._description;
        }
    }
    /* 一些其他方法 */
}

如此一來我們就能對存取屬性時的行為進行管控囉。

那可能有些朋友會有疑惑：那為什麼我不能直接對外開放卡牌敘述，然後修改的時候檢查完再傳進來 set 就好了呢？這個就牽涉到一些「改太多地方了我要死啦」的悲情故事，這邊再舉個例子給大家體會一下。

例如說，我們的卡片現在加入了戰力指數系統，這個戰力是預先從卡片的各項資訊計算好，並存放在資料庫的。而且因為計算的關係可能有小數點後十位之類的，那我們拿出來的時候可能會長這樣：Power: 99.256256

而在建立類別的時候，也很自然地選用了 double 來處理，於是現在類別就長這樣：

public class Card
{
    public double Power;
}

這個系統上線運行了一段時間之後，突然上頭來了需求：請把所有顯示到卡片敘述的地方都改成小數點後兩位就好。

假設我們不能直接修改從資料表取出來時的數值（或是已經改了然後被前輩電）因為記 Log 或是什麼戰力對決(?)功能還會需要用到原本的戰力數值之類的理由，因此物件存放的戰力數值必須和資料表中的一致等等，總之不允許改資料

如果先前直接開放存取，那麼這下子要改的地方就變成「所有使用到這個屬性的地方」，再要是當場看到 Visual Studio 上面寫：99 個參考，那可能當場整個腦子就直接下班了。

但如果我們是使用 get 和 set 的方式去處理的話，那麼我們只需要修改 get 存取子的規則，讓它讀取的時候幫忙四捨五入到小數點第二位就好了：

public class Card
{   
    private double _power;
    
    public double Power 
    { 
        set { this._power = value; } 
        get { return Math.Round(this._power, 2);}
    }
}

這樣應該就能看出使用 get 和 set 去把攔位封裝起來的好處了，也就是：把「資料進出時加以處理的主導權」留在物件本身。

而在 C# 裡，如果你並沒有（或是說「還沒有」）要特別針對存取另做額外處理，可以直接使用自動實作：

public string Description { set; get; }

這樣實際上就會自動幫你建立一個私有屬性，並且只能經由這個公開屬性的 set 和 get 進行存取。

藉由自動實作來簡化寫法之後，例如唯讀就可以這樣寫：

public string Description { get; }

或是

public string Description { get; private set; }

使用自動實作時，若要加上預設值的話請這樣寫

public string Description { get; } = "這是一張卡牌。";

可以說是方便很多。將來如果要針對設值給值的地方進行修改，也會比較方便一點。

稍微了解了上面提到的存取範圍、存取子、自動實作這些工具之後，現在，我們就可以決定外部的使用者能看到物件的哪些部份了。

隱藏複雜度

當然，封裝的概念並不僅僅只是對屬性定義存取範圍如此而已，提高類別內的內聚性，降低對外的耦合性，隱藏複雜資訊才是最重要的方針。

也就是說，我們需要妥善地運用「把大的類別和方法切割成小的類別和方法」、「活用存取範圍，對外隱藏複雜資訊、對內切割成各個工作的私有方法」等等技巧，才能夠更接近完善的封裝一點。然而這只能在設計時，或是維護到頭痛才能親自體會了。

接續著上面的技巧來說：當你面對在一個公開方法中需要處理一長串的商業邏輯，以至於需要將他們切割成數個小函式時，將它們宣告成 Private 就是相當好的選擇。

例如說，我們有個連線到資料庫取得客戶資料的方法（可能是 UserRepository.Get(int UserId) 這種感覺），可能我們除了 Public 的 Get 方法以外，還有一些 Private 的 ConnectDB 等輔助方法。

這意味著這些工具僅讓你的物件內部使用，外面的人不應該直接調用其中的任何功能，同時又能幫助你的主要流程變得更簡潔，提升維護和修改時的速度。

同時以資料庫的例子來說：呼叫這個函式的使用端不需要知道這個函式是怎麼連線到資料庫的，又是怎麼搜尋出資料的，只需要知道呼叫了之後能拿到客戶資料就好。

兩個物件之間「知道」得越多，其耦合就越高。替換和修改時互相牽連的機會和規模也越大，因此封裝可以說是物件導向的基石也不為過。封裝的好或不好（亦即物件是否足夠內聚，其職責是否單一，暴露內部資訊的多寡等等），直接關係到整個架構的優劣，不可謂不慎。

補充：封裝的核心在於「隱藏複雜資訊」。而我們前段所提到需要注意的幾個部份：

「物件是否內聚」可以參照菜雞與物件導向 (8): 內聚、耦合

「職責是否單一」可以參照菜雞與物件導向 (10): 單一職責原則

這些概念之間彼此相扣，此處就先按下不表。

小結

封裝的部分就講到這裡，並不是很難理解，但是要封裝得好，或是說知道怎樣才算封裝得好，還是需要經驗，不是我這種菜雞一時半刻能理得白說得清的，之後有心得再和大家分享。

封裝、繼承、多型並稱物件導向三大特性，我們也會按照這個順序快速地介紹。接著我們就繼續來看繼承吧！

本系列下一篇：菜雞與物件導向 (4): 繼承

延伸閱讀：菜雞與物件導向 (15): 最少知識原則

參考資料

同系列文章

菜雞與物件導向 (2): 建構式、多載

Igouist (Igouist) — Sun, 12 Jul 2020 23:53:02 +0800

章節目錄

在上一篇類別與物件的文章裡，我們建立了卡片，但目前還執行不了。這是因為我們建立哥布林和戰士這兩張卡片的時候，根本就沒有給他們數值呀！

雖然可以先呼叫出來再賦值…

var goblin = new Card();
goblin.Name = "哥布林";
goblin.Attack = 3;
goblin.Health = 2;
/* ...其他賦值 */

這實在相當占空間，也有點奇怪。畢竟如果是阿福（狗），一出生的時候應該就確定了一些特徵才對，例如品種、血型、眼睛顏色這種。並不會出生後過一陣子，才突然決定這些東西，既然如此，我們在產生物件的時候，當然也會希望在建立的同時就先決定好一部份內容。

這時候我們就可以藉由建構式的方式，在建立物件時就進行一些我們想要的操作。

建構式

事實上，當我們呼叫 new Card() 的時候（不覺得這個 () 很有呼叫方法的感覺嗎？）我們就是正在調用 Card 的建構式。而當我們沒有特別去定義建構式的時候，就會直接使用內建的建構式去幫我們產生物件。

現在我們替 Card 新增一個建構式：

public class Card
{
    public Card (string name, int attack, int health)
    {
        this.Name = name;
        this.Attack = attack;
        this.Health = health;
    }
    /* ... 其他屬性和方法 */
}

在 C# 的時候，建構式必須和類別同名，且不需要定義回傳類型。當我們有了建構式，剛剛的例子就可以改寫成：

var goblin = new Card(name: "哥布林", attack: 3, health: 2);
var warrior = new Card(name: "戰士" , attack: 4, health: 3);
warrior.Hit(goblin);

建構式也就是建立這個物件時執行的函式，通常會用來進行初始化，也就是做一些建立物件必要的準備。例如傳遞必要屬性或是建構需要的其他物件、或是給予私有屬性初始值等等，例如說我們的卡牌一建立，就會需要知道它的名字和戰鬥力，這樣才有卡牌的感覺，而不該像一些壞決鬥者邊打牌邊偷偷印卡。

註：當然有建立時執行的，也就會有消滅時執行的。請參見解構式，由於較少用到，此處先按下不表。

多載

當然，有了建構式就會有更多問題。現在我們只有一個方法可以建立卡牌了，這無疑是相當不彈性的，例如說我希望預設的攻擊力和血量就是四呢？實際上我們經常會遇到需要用不同素材去建立一個物件的場合，這時候就必須得提到另一個要點：多載了。

多載指的就是可以有很多個同樣名字的方法，各自去接不同的參數。例如說我們的 Card 建構式就可以利用多載來改造一下：

public class Card
{
    public Card (string name, int attack, int health)
    {
        this.Name = name;
        this.Attack = attack;
        this.Health = health;
    }

    public Card (string name)
    {
        this.Name = name;
        this.Attack = this.Level;
        this.Health = this.Level;
    }

    public Card ()
    {
        this.Name = "Noname";
        this.Attack = this.Level;
        this.Health = this.Level;
    }
}

如此一來，我們在建立卡片的時候就能夠有更多選擇了，現在我們可以根據狀況給予需要的參數，剩下的就交給建構式去處理就好。

實務上，如果規則或是建立的步驟一致的話，為了能夠把規則集中到一個地方方便修改，並且減少多餘的程式碼。我們通常會試著讓其他的建構式去呼叫主要的建構式，在 C# 中，呼叫自己的建構式是使用 : this() 來進行的，例如：

public Card (string name, int attack, int health)
{
    this.Name = name;
    this.Attack = attack;
    this.Health = health;
}

// 會呼叫上面那個建構式
public Card (string name) : this(name: name, attack: 5, health: 5)
{
    // 呼叫完 Card(name, attack, health) 之後做的事
}

// 會呼叫上面那一個建構式
public Card () : this(name: "Noname") 
{
    // 呼叫完 Card(name) 之後做的事   
}

如此一來只要建構的方式有變更，我們只需要集中修改第一個建構式就好了。這部份的流程也可以參照 [C#.NET] 為建構子建立正確的初始化 - 余小章 @ 大內殿堂這篇的說明。

當然多載也不只是用在建構子，而是大多數時候都可以用的寫法。例如當你的函式雖然做同樣的事，但允許接收不同的參數來處理時，就請考慮使用多載。

例如說當你要記錄發生錯誤時的 Log ，就能允許只傳遞錯誤內容，或是傳遞錯誤內容和當時操作的參數，甚至是當下的環境資料等等。

又或者是查詢客戶資料（GetUser 之類的）的函式，提供使用客戶代號，或是訂單編號等不同的方式進行查詢時，就可以考慮多載的應用。

例如說 .net 中協助類別對映的名套件 AutoMapper，在轉換類別的 Map 方法就很漂亮地使用了多載：

註：看不到圖片的可以直接看 Github

當然隨著多載的應用越來越稀鬆平常，時至今日，我們只要使用選擇性參數就可以輕鬆達到一樣的效果囉：

public Card (string name = "Noname", int attack = 5, int health = 5)
{
    this.Name = name;
    this.Attack = attack;
    this.Health = health;
}

當有預設值的時候，該參數就會變成可選的，這時候就可以輕鬆決定要傳進來的內容了。當然，如果傳進來的並非只是數量上的差別，而是整個型別都不一樣的話，還是要回歸到多載的做法，建立兩個同名但不同傳入參數類型的方法，可讀性會比較高呦。

多載提供的好處在於：同個目標的函式可以根據傳入的參數不同做不一樣的處理。例如當我們寫了一個連線取資料的方法，可以分為

傳入連線的話，就使用連線取得資料
傳入連線字串的話，就先用連線字串開啟連線，再使用連線取得資料

等等，根據參數的場合來進行處理。

藉由傳入不同的參數類型和數量，就可以處理不同狀況的內容，既擴展了函式在使用上的彈性，同時也增加函式能派上用場的時機。

而最重要的是這將讓編寫程式的人員去思考：我設計的這個方法將能應用在什麼場景？ 這將會成為一個相當優良的習慣。

那麼這次就說到這裡，我們下篇見！

本系列下一篇：菜雞與物件導向 (3): 封裝

參考資料

同系列文章

菜雞與物件導向 (1): 類別、物件

Igouist (Igouist) — Sun, 12 Jul 2020 23:53:01 +0800

直覺上你當然知道什麼是物件；物件就在你的身邊。

汽車、iPhone、收音機、吐司機、廚房用具等等，你說得出來的都是。

　　——《深入淺出學會編寫程式》

什麼是物件？一切都是物件。

物件導向試圖讓抽象的程式碼，更貼近於我們的實際生活，其認為一切是由各式各樣的人事物互動所組成的，因此有了物件這個共通、最基本的概念。

假設現實世界存在一頭狗，叫做阿福。而我們想要在虛擬世界裡表達「有一隻叫做阿福的狗」這件事

這時候就要在系統裡有一個能代表「阿福（狗）」的東西存在，也就是「阿福」這個物件。

關於「把現實世界的物件，抽象化成程式世界裡的物件」的邏輯，可以參考一個語言如果不改變你的思考方式，就不值得學？談程式語言的本質這篇，尤其是選擇保留哪些資訊的部份我認為描述得很好。

現在我們知道，物件就是用來在虛擬世界中代表「某個特定的東西」，例如說叫做阿福的狗就是一個物件，阿福今天晚上要吃的飼料罐也是一個物件。

理解物件的概念是相當直覺且迅速的，畢竟你我身邊有著數不清的東西，它們都是一件一件的物件，但這樣的理解還不夠明確。

就像前文所引的談程式語言的本質文中所提到的，在抽象化的同時我們必然要選擇保留哪些資訊。

例如說阿福這隻狗，是一個物件；飼料罐也是一個物件

而這些物件之間還會彼此互動，例如說阿福是一隻狗，而我們觀察到狗都有吃東西這個動作，例如「阿福吃了飼料」

同時物件也會有一些專屬於它的特徵，例如說阿福是黑色的，我們就知道狗有毛色的差別。

那麼我們要怎麼表達「阿福」作為一隻「狗」擁有的那些動作和特徵呢？狗的毛色？狗可以吃飼料？

我們需要選擇怎麼去描述「狗」－－也就是阿福這隻狗，被我們抽象化後的樣子，我們需要將它用程式碼的方式定義出來。

這時候我們就會需要類別，來定義出我們觀察到同一類的物件該有哪些特徵和動作，也就是我們替物件「分門別類」後、篩選出特定資訊的抽象化結果

延續前面的例子，假設今天我們從阿福身上觀察到進食跟毛色兩個狗的重要資訊，我們就可以建立類別 Dog：

public class Dog
{
    public string color;
    public void Eat(IFood food) { /* 進食與消化之類的 */ };
}

藉由我們定義的類別，就可以從類別中實例化（＝建立）出物件。

也就是說，現在我們終於可以用「狗」這個類別，來表達出我們需要的「阿福」了：

Dog afu = new Dog(); // 阿福是一隻狗
Console.Write(afu.Color); // 阿福是黑色的
afu.Eat(food); // 阿福會吃食物

類別最常看到的比喻，就是物件的設計圖。我們藉由類別去定義我們要的物件有什麼特徵、有什麼功能，再從類別根據設計圖產生物件出來使用。

這個從類別中產生的物件，就等於是這個類別定義的一個實際的例子，所以我們也會把類別產生的物件叫做實例。而從類別產生物件的過程，就叫做實例化。

也就是說，類別實際上就是我們認知中對這個物件的定義，我們篩選出我們需要的、我們認為這個物件應該具有的這些特徵和功能，按照我們的認知去設計了類別

接著我們再利用這個類別告訴程式如何建立出我們認為的這個物件，最終我們才能在程式中使用我們需要的這個物件。

當我們定義了一個狗的類別，我們實際上是在描述我們眼中的、我們歸納出來的、我們需要的「狗」，我們認為狗就是會吃東西。

接著，我們再從我們設計好的這份定義，去實例化出我們需要的狗：阿福，於是阿福就有了吃東西的能力。

我們有了抽象化的設計圖之後，就可以利用這個設計圖去建立多個符合這個設計的物件。例如說前面的狗，我們就可以建立出黑色的阿福，黃色的阿黃等等。

在現實中，我們將阿福、阿黃等等歸類為狗這個概念，而到了程式裡，我們利用這個狗的概念定義出類別，進而產生阿福、阿黃。

從這邊也能察覺到：類別是一個歸納好的概念，這概念中包含許多獨立的個體，也就是物件，而這些物件之間的差異則從我們定義類別時選擇的特徵去區分。

因此，一個人設計的類別，和他使用物件的方式，反映了他對於這個物件的看法和他覺得需要的內容。

同時，使用物件導向也意味著：比起 EatFood(dog, food) 而言，我們認同 Dog.Eat(food) 更直覺和易於理解。

那麼這邊就讓我們以卡牌遊戲舉例，理所當然卡牌遊戲不能沒有卡牌。

對我來說卡牌通常都需要這些特徵，我們在物件裡稱為屬性：

卡片名稱
攻擊力
防禦力
卡牌描述

等等，另外卡牌也應該能作出某些動作，也就是這個物件的方法：

攻擊

我們確認了這些要素以後，就可以把它設計成一個類別 Card 如下

public class Card
{
    public string Name;
    public int Level;
    public int Attack;
    public int Health;
    public string Description;

    // 攻擊目標卡片
    public void Hit(Card target) 
    {
        target.damage(this.Attack)
    }

    // 被攻擊的時候扣血
    public void damage(int attack) 
    {
        this.Health -= attack;
        if (this.Health <= 0) 
        { 
            /* 可能呼叫死翹翹方法？ */ 
        }
    }
}

抱歉我菜，如果有真的設計卡牌遊戲的工程師經過拜託不要打我。

接著我們就能在需要的時候藉由這個類別來實例化我們的卡牌：

var goblin = new Card();
var warrior = new Card();
warrior.Hit(goblin);

再提醒一次：

類別是定義、是設計圖、是描述；物件是類別產生的實體、是實際上的執行者
類別是抽象化的資訊，例如「狗」
物件則是一個特定的實例，例如「一隻叫做阿福的狗」
承上，狗的類別用來告訴程式什麼是狗；而叫做阿福的物件，則是程式根據我們的指示，從類別建立出來的一條實際的狗

這邊推薦一下可以閱讀保哥的這篇物件導向基礎：何謂類別(Class)？何謂物件(Object)？，裡面除了對物件和類別有更易懂的介紹和舉例以外，還有十題概念題可以幫助你搞懂物件和類別的意義與差異，相當值得一看。看完上面這篇之後，推薦再閱讀這幾篇：

物件的部份由於是最初的概念，不免多廢話了一些。下一篇開始就讓我們快速看過物件導向的幾項功能和特性。

本系列下一篇：菜雞與物件導向 (2): 建構式、多載

2022.12.02 補充：感謝公司前輩簡潔有力的說明，修正了開頭時對物件的介紹

參考資料

同系列文章

菜雞與物件導向 (0): 前言

Igouist (Igouist) — Sun, 12 Jul 2020 23:53:00 +0800

在訂便當告一段落之後，其實就已經和同事約好要來整理公司新訓的筆記。但儘管已經到職快一年了，有些工具已經在專案碰過好幾次。但遇到需要跟朋友討論，或是聽前輩說明觀念的時候，還是不自主地會想「我真的懂嗎？」故一直是挺畏懼的。

但幸虧同事的鼓勵和以身作則，最終還是開啟了這個新系列，決定直接開坑把當初前輩新訓指導過的部分整理下來，也算是讓自己能趁著這機會好好複習一番，把自己的想法跟心得記錄下來。

另外，如果你是真心希望弄懂物件導向的朋友，這邊推薦《大話設計模式》的附錄，內容對物件導向的介紹清晰易懂且循序漸進，非常適合作為了解物件導向的起頭。

本篇的段落將會分成以下幾個部份，由於只是筆記一下，因此會附上一些知識點的參考資料，看見的時候可以先行閱讀；末尾也會附上有關的參考資料及文章，對於這類概念性的東西，一向是推薦多方閱讀以增強理解，就像保哥寫的：「如果你問 100 個人這個問題，可能會得到 200 個答案，所以你一定要有自己獨到、有自信、精闢的見解或描述方式。」如果有寫得不錯的文章想推薦給我，或是有地方需要補充和指證，還請不吝指教。共勉之。

最後，儘管這系列的篇幅會有點長，但我覺得仍做不到說明透徹，~~畢竟大部份也是只花一天壓線趕工出來的~~。因此往後如果有想到什麼地方必須修正，或是找到什麼更好的表達方式，還是會回來修改這系列文章，希望能逐漸修訂成讓我自己都能輕鬆看懂的物件導向入門文。

下一篇就直接從類別和物件開始囉。那麼，還請各位閱覽拙見，為此先道一聲感謝。

本系列下一篇：菜雞與物件導向 (1): 類別、物件

8/9 註記：和朋友們聊過之後，發現之前集中成一篇感覺太長了，更何況新訓的內容也是包山包海。因此將原先的內文拆解成多篇文章，做成系列文；由於一些大人的原因（例如不想打亂鼠年全馬、不想重註冊 URL 等等），本篇就留著作為目錄使用，以上。

AutoMapper —— 類別轉換超省力

Igouist (Igouist) — Sun, 05 Jul 2020 23:40:00 +0800

類別間的轉換幾乎是每個專案每個工程師都會碰到的動作，舉凡是分層架構每層之間的轉換，如 Dto 轉換成 ViewModel；或是接收到資料要塞進自定義的類別時也需要進行轉換。但在遠古時代，當我們要把一個類別的資料倒進另一個類別時，總免不了一番折騰。

例如一個卡片對戰遊戲的資料庫，光是要先把卡片資料讀取出來就需要：

有些時候也會看見用 Foreach 然後逐一傳值的場景，或是各種差不多的變種情況。同樣的是，光是將一個簡單的卡片資訊轉換成 ViewModel，就花了一大段在做對映的處理。這個過程本身枯燥乏味又占空間，更可怕的是，如果有個陳年資料表，動不動就上百個欄位，那這個轉換過程的恐怖程度可想而知。

幸好！天無絕人之路，這種時候就是本日的主角 —— AutoMapper 出場的時候了。

當 AutoMapper 一出手，轉換的過程瞬間就變成：

是不是精簡很多呢？接著就讓我們來看看怎麼開始使用吧！

章節目錄

安裝與使用

首先，當然要先到 NuGet 把 AutoMapper 給裝下來。

確認安裝之後，就開始基本的使用吧。

只需要先註冊好 Mapper 的設定內容，也就是哪些類別之間可以互相對映；再實體化 Mapper 出來使用就可以了。直接看程式碼應該就能理解：

public IEnumerable<CardViewModel> GetCard()
{
    var data = this.GetCardFromRepositoryMock();
    
    var config = new MapperConfiguration(cfg => 
        cfg.CreateMap<Card, CardViewModel>()); // 註冊Model間的對映
    var mapper = config.CreateMapper(); // 建立 Mapper
    var result = mapper.Map<IEnumerable<CardViewModel>>(data); // 轉換型別

    return result;
}

沒錯，只需要簡簡單單幾步， AutoMapper 會自動將指定類別間同樣名稱的屬性內容做轉換 ，因此能夠省下相當多的功夫，也能夠隱藏類別本身的內容，專心在處理功能本身。

註：網路上挺多 AutoMapper 的文章會直接使用 Mapper.CreateMap() 這類靜態方法，然而這些方法已經在 AutoMapper 5 的時候被廢除，改成現在由 MapperConfiguration 產生 Mapper 的方法。

然而整體的使用方式仍然大同小異，這些文章仍能稍微調整並使用，惟使用過程中需自己注意語法的差異和多加測試。

客製化轉換

但當然實際上我們並不一定每個欄位的名稱都是一模一樣的，總是會有遇到同個資料在不同層的 Model 裡名稱不一樣的時候，又或者是某個欄位是由兩三個欄位組成的時候。對於這種需要客製化的轉換，這時候我們就可以在註冊對映時對欄位內容的對映方式做指定：

var config = new MapperConfiguration(cfg =>
    cfg.CreateMap<Card, CardViewModel>()
        .ForMember(x => x.Id, y => y.MapFrom(o => o.CardId))
        .ForMember(x => x.Name, y => y.MapFrom(o => $"{o.Id}: {o.Name}"))
    ); // 註冊Model間的對映 建立設定檔

可以看到 我們能用 ForMember 去對類別成員做操作，並傳入目標的類別成員，以及該成員對應的操作，像這邊就使用 MapFrom 來指定目標類別成員的轉換來源，這樣就可以達到轉換時的客製化了。

註：對於欄位之間有使用 ForMember 來處理過內容再轉換的型別，建議在轉換型別時，也就是實際 mapper.Map() 的時候，稍做註解提醒一下。

尤其是會將 Mapper 的 Config 集中整理的架構裡更應該要對額外的操作做揭露，這樣對彼此都好。真的。

補充：AutoMapper 在轉換像是 IEnumerable<T> 這類的集合時，預設會將來源為 Null 的成員轉換成空集合（而非 Null）

如果希望 Null 就乖乖轉換成 Null 的朋友，可以在建立設定檔時用 cfg.AllowNullCollections = true; 來讓亂跑的空集合轉換對象都保持 Null

也能夠在 ForMember 的時候使用 AllowNull 來針對欄位指定規則。
例如 ForMember(x => x.Members, y => y.AllowNull())

需要更詳細說明的朋友，也可以參照官方文檔的 Handling null collections 一節

忽略指定的欄位

除了會有欄位名稱和來源的不同以外，最常遇到的應該就是兩個類別之間大多數欄位雖然對映，但某幾個欄位是沒有對映的。例如傳送給前端使用時，我們想要一併組裝多個來源的資料，所以資料由資料表取出時並沒有某些欄位，必須等後續的步驟去別的來源補上資料。

這時候如果直接使用 Map 來進行轉換，就會發生找不到對映欄位的錯誤。此時就可以先用 Ignore 來忽略掉指定的欄位。

var config = new MapperConfiguration(cfg =>
    cfg.CreateMap<Card, CardViewModel>()
       .ForMember(x => x.ImgUri, y => y.Ignore())
    );
}

如上述程式碼，可能卡片的圖像位置必須由別的方式取得，這種情況我們在 ForMember 的時候就可以將其指定為 Ignore 讓 AutoMapper 不要去嘗試轉換它。

除了 Ignore 以外，AutoMapper 還有 IgnoreAllPropertiesWithAnInaccessibleSetter 這種光方法名稱長度就有點強的大殺器，也還有像是 AllowNull 等更多對欄位操作的方法，這部份請各位在使用時按照需求自行摸索。

註(1)：上述舉的例子中有需要從多個來源轉換為一個類別的場合，可以參照 AutoMapper 兩個物件對映到一個類別 - mrkt 的程式學習筆記

註(2)：上面使用到的 Ignore 方法還是有些眉角需要注意，可以參照 [料理佳餚] AutoMapper 中不容忽視的 Ignore() Mapping 的順序 - 軟體主廚的程式料理廚房

註(3)：面對一些比較複雜的轉換時，也可以考慮使用 ConvertUsing

最後還要補充的一個方法是 ReverseMap ，它能夠反轉對映，建立一個反方向的對映表。當你的類別之間可能需要往回轉型，又或是想要忽略來源類別的欄位時，ReverseMap 就會顯得相當有用。通常為了避免轉來轉去轉出意外，建議註冊時還是補上一個 ReverseMap 為佳。

var config = new MapperConfiguration(cfg =>
    cfg.CreateMap<Card, CardViewModel>()
       .ForMember(x => x.Id, y => y.MapFrom(o => o.CardId))
       .ForMember(x => x.ImgUri, y => y.Ignore())
       .ReverseMap() // 反轉
    );

到目前為止，程式碼可能會變成如下：

public IEnumerable<CardViewModel> GetCard()
{
    var data = this.GetCardFromRepositoryMock();
    
    var config = new MapperConfiguration(cfg =>
        cfg.CreateMap<Card, CardViewModel>()
           .ForMember(x => x.Id, y => y.MapFrom(o => o.CardId))
           .ForMember(x => x.Name, y => y.MapFrom(o => $"{o.Id}: {o.Name}"))
           .ForMember(x => x.ImgUri, y => y.Ignore())
           .ReverseMap());

    var mapper = config.CreateMapper(); // 建立 Mapper
    var result = mapper.Map<IEnumerable<CardViewModel>>(data); // 轉換型別

    return result;
}

2021.06.09 補充：

在我們前面提到的欄位轉換時，要特別注意兩個欄位的型別是否能夠對應上。由於 AutoMapper 會貼心地幫我們進行轉換，但有些時候可能會產生問題，讓我們看看下面這個例子：
public class Boo
{
    public double Val { get; set; }
}

public class Foo
{
    public int Val { get; set; }
}

public Foo Sut()
{
    var boo = new Boo
    {
        Val = 2.65
    };

    var config = new MapperConfiguration(cfg =>
        cfg.CreateMap<Boo, Foo>());
    var mapper = config.CreateMapper();
    
    var foo = mapper.Map<Foo>(boo);
    return foo; // 3
}
可以看到上面這個例子中，我們可以把 double 的欄位直接 Mapping 到 int 的欄位上，因為 AutoMapper 的貼心，所以不會出錯，但過程中還是可能發生喪失精度的問題。

像是例子中的 2.65 就直接變成了 3，如果符合我們的需求（例如本來就打算轉型）倒是沒關係，但如果是因為不小心轉到的話，在找問題上可能就會比較麻煩。

因此在轉換的時候，還請特別留意一下轉換雙方的型別，測試一下轉換結果是不是自己要的結果會比較好呦。

簡化整理

可能看到這裡有些讀者就開始疑惑了：這好像跟一開始簡介不太一樣啊，詐欺？又或者是：我每個方法裡面都要重新建一個 Mapper？這不太對吧？

的確是這樣沒錯，AutoMapper 要達到更簡潔，還需要再做一些整理。例如使用 Profile 將對映關係集中起來，以及把 Mapper 的建構抽取出來。可能是在建構式建立共用的 Mapper ，或是以依賴注入 (Dependency Injection) 的方式來注入 Mapper 等等。以下就逐步進行介紹。

Profile

首先我們先建立一個用來放對映關係的 Profile。我個人習慣會另開一個 Mappings 資料夾，並按照轉換所在的分層 + Mappings 來命名。

public class ServiceMappings : Profile
{
    public ServiceMappings()
    {
        CreateMap<Card, CardViewModel>()
            .ForMember(x => x.Id, y => y.MapFrom(o => o.CardId))
            .ForMember(x => x.Name, y => y.MapFrom(o => $"{o.Id}: {o.Name}"))
            .ForMember(x => x.ImgUri, y => y.AllowNull())
            .ReverseMap(); 

        // ...其他的對映內容 (使用 CreateMap<> 建立下一組)
    }
}

從上面可以看到，我們繼承 AutoMapper 提供的 Profile 類，接著在建構式裡面將需要的轉換關係組都建立起來。接著當我們建立 Mapper 時，就可以直接用 AddProfile 和建立好的 Profile 來直接讀入對映關係：

public IEnumerable<CardViewModel> GetCard()
{
    var data = this.GetCardFromRepositoryMock();
    var config = new MapperConfiguration(cfg => cfg.AddProfile<ServiceMappings>());
    var mapper = config.CreateMapper(); // 用設定檔建立 Mapper
    var result = mapper.Map<IEnumerable<CardViewModel>>(data); // 轉換型別

    return result;
}

當然，在 MapperConfiguration 的時候是可以對 cfg 去做多次 AddProfile 的，既然可以載入多組對映關係，就代表可以按照實務上的運用去將對映關係做分類和整理。

這邊還是要再度提醒一下，將 CreateMap 都整理到 Profile 之後，若是有些類別之間的轉換有對欄位做額外的處理，例如 DateTime 去除時間只留下年月日，又或是某幾個欄位銜接成一個欄位等等，在實際進行類別轉換的時候需要註記一下，請後續的維護人員或團隊夥伴記得先確認過 Profile，避免造成一些隱藏重要資訊挖洞給人跳的問題。

整理到建構式

接著由於一個處理資料或商業邏輯的部分通常會有許多方法都用到 Mapper，因此將建立 Mapper 的過程取出來避免重複絕對是必要的。故整理的第一步就是將 Mapper 的建立拆分出來，不再等每次用到的時候才建，而是先建立好一個 Mapper，需要的時候再來使用它。

這邊就先嘗試將其挪到私有變數和建構式處理：

private IMapper _mapper;

public MapSimpleService() // 建構式
{
    var config = new MapperConfiguration(cfg => 
        cfg.AddProfile<ServiceMappings>());

    this._mapper = config.CreateMapper();
}

那麼我們實際上的方法就會變成：

public IEnumerable<CardViewModel> GetCard()
{
    var data = this.GetCardFromRepositoryMock();
    var result = this._mapper.Map<IEnumerable<CardViewModel>>(data);
    return result;
}

走向依賴注入

由於本篇篇幅無法說明好依賴注入（DI）的概念，相關的部份就留待在之後的文章中說明，這邊就以 .net Core 為示範來記錄一下步驟，提供給已經會 DI 的朋友參考。

在開始之前，我們會需要再前往 NuGet 安裝 AutoMapper DI 用的套件：

接著在 Startup.cs 裡的 ConfigureServices 加上 services.AddAutoMapper(typeof(Startup)) 來註冊我們的 Mapper：

public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers(); 

    // Demo 用的 Service
    services.AddScoped<IMapSimpleService, MapSimpleService>();

    // 註冊 Mapper
    services.AddAutoMapper(typeof(Startup)); 
}

可能有些人會有點疑惑：前面還需要 MapperConfiguration 怎麼這次不用了呢？那是因為 AddAutoMapper 的時候就會用反射去取得同組件中的 Profile 來載入，所以這部分就可以不用擔心，只要專心在使用上就好。

2021.04.23 補充：

感謝同事們的討論，這邊也補充給大家參考一下

當我們直接使用 services.AddAutoMapper(typeof(Startup)); 註冊的時候，AutoMapper 會去抓我們 typeof 的型別，並對該型別所在的 Assembly 進行反射找出所有的 Profile。

但如果你有用到多層的架構、或是不同的組件內都有 Profile 需要註冊，又或者只是想要逐個 Profile 進行註冊，方便進行控管的話，可以考慮使用 AddProfile 或 AddProfiles 的方式來進行註冊，例如：
services.AddAutoMapper(config =>
{
    config.AddProfile<ControllerProfile>();
    config.AddProfile<ServiceProfile>();
});
這樣的可讀性更好，也能讓維護的人迅速掌握當前的 Profile，有需要的朋友可以嘗試看看。

2021.08.27 補充：

感謝 Ray 大大提供的方法，這邊也補充給大家參考一下

我們前面有提到 AddAutoMapper 會對該型別所在的 Assembly 進行反射找出所有的 Profile，那麼我們也可以轉換一下思路：只要把全部的組件都丟到 AddAutoMapper 裡就好了！這種時候我們就可以利用反射來達到我們的目的：
services.AddAutoMapper(AppDomain.CurrentDomain.GetAssemblies());
相較於 AddProfile 這種逐一新增 Profile 的作法，利用反射會讓註冊顯得更乾淨，並且也更不容易有所遺漏。各位可以按照開發的場景選擇一下註冊的方式，有需要的朋友也可以都嘗試看看。

註冊好之後，我們就能將剛剛的示範部分更改為使用注入的方式來取得 Mapper：

private IMapper _mapper;

public MapSimpleService(IMapper mapper) // 建構式
{
    this._mapper = mapper;
}

執行之後就能確認確實有轉換到值囉！最後再來對照一下商業邏輯的部份：

－－瘦身前－－

public IEnumerable<CardViewModel> GetCard()
{
    var data = this.GetCardFromRepositoryMock();
    var result = data.Select(x =>
        new CardViewModel
        {
            Id = x.Id,
            Name = x.Name,
            Cost = x.Cost,
            Attack = x.Attack,
            Health = x.Health,
            Note = x.Note // ...etc
        });
    return result;
}

－－瘦身後－－

public IEnumerable<CardViewModel> GetCard()
{
    var data = this.GetCardFromRepositoryMock();
    var result = this._mapper.Map<IEnumerable<CardViewModel>>(data);
    return result;
}

結語

當我們把類別轉換的區段利用 AutoMapper 擷取出來，就能讓原本的程式碼更著重在該方法本身的邏輯和功能，而不會被冗長的轉換過程洗版，使用 Mapper 的方法只要知道這兩個類別能夠互相轉換即可。除了看起來更舒服、更能將焦點放在方法本身以外，也能夠讓維護時的修改更加直覺，若是轉換的過程需要修改，就去變更 Profile，不需要去變動實現商業邏輯的方法本身，這樣就能朝單一職責的目標更前進一點。

到這邊算是把 AutoMapper 基本的用法介紹過一遍了，當然還有很多進階的用法和需要注意的部分並沒有說明完全，但相信這樣的紀錄已經能夠幫助我在將來需要的時候回想起怎麼使用，和解決大部分需要做類別轉換的場景了。剩餘的延伸閱讀將會補充在參考資料裡，那麼下週見～

參考資料及延伸閱讀

Electron.net —— 把網頁包成桌面應用吧

Igouist (Igouist) — Sun, 28 Jun 2020 19:41:00 +0800

因緣際會下想要弄出一些單機小工具來跑，這時候正巧接觸到 Electron.net 這個神器，特別紀錄一下以免忘記。這是 Electron 搭配 .net Core 的框架， Electron 是用 Chromium 和 Node.js 將網頁封裝成桌面應用程式，像是 Visual Studio Code、Slack 也都有使用到 Electron。而 Electron.net 顧名思義就是 .net 用的 Electron 框架囉。

這邊記錄一下自己嘗試時載入套件和建置的流程，主要參考自黑大的用 ASP.NET Core 寫桌面 GUI 應用程式 - Electron.NET 和 Electron.NET API 快速巡覽這兩篇文章，以及官方的 API DEMO，特此感謝。

章節目錄

那麼首先從建立新專案開始，這邊用 .net Core MVC 來測試

安裝套件及環境設置

建立專案之後，前往 Nuget 先把 ElectronNET API 安裝下來

安裝完畢之後，開始做一些前置動作，首先：

Program.cs 的部分，加上 .UseElectron(args)

Startup.cs 的部分，加上 Task.Run(async () => await Electron.WindowManager.CreateWindowAsync()，讓專案啟動時一併啟動 Electron

接著打開命令提示字元或 Powershell ，輸入 dotnet tool install ElectronNET.CLI -g 安裝 ElectronNET 工具。如果有安裝成功應該會看到下圖的回傳。如果已經安裝，就可以直接進到下一步。

接著移動到專案資料夾，並輸入 electronize init 進行初始化，將會建立資料夾和必需檔案，這一步一定要確認成功並顯示 Everything done，否則後面怎麼跑也起不來。

補充：如果 electronize init 的時候跳出 “Path cannot be null on init” 的錯誤，請移動到 Startup.cs 或是 Program.cs 所在的目錄再試一次。

參考來源：Electron.NET

最後輸入 electronize start 就可以準備看專案 On 起來囉！

另外除了 electronize start，環境設置完畢後也可以直接從 Visual Studio 偵錯囉～

成功從桌面應用開起來了！

前後端傳值 (IpcMain, IpcRenderer)

在 Electron 中，會分成跑應用程式的主處理序 (main process)、和處理網頁畫面的渲染處理序 (renderer process)。而兩者之間的溝通則經由 Ipc 開啟頻道傳遞訊息來實現

這邊簡單嘗試一次，首先，我們先在 Views/Home/index.cshtml 加上一個簡單的按鈕

並且加上 JavaScript 發送訊息和接收訊息的方法

const { ipcRenderer } = require("electron");

// 發送訊息，這邊傳送一個 Hello
function sendMessageToServer() {
    ipcRenderer.send('channelToServer', 'Hello');
}

// 接收訊息
ipcRenderer.on('channelToClient', (event, arg) => {
    document.getElementById("Welcome").innerText = arg
});

接著到對應的 Controllers/HomeController 的 Index() 也加上接受到訊息之後加工並發出訊息的處理

public IActionResult Index()
{
    // 接收訊息
    Electron.IpcMain.On("channelToServer", (args) =>
    {
        // 傳送訊息，把接收到的訊息再加上 World
        var mainWindow = Electron.WindowManager.BrowserWindows.First(); // 現在只有一個視窗所以直接拿
        Electron.IpcMain.Send(mainWindow, "channelToClient", $"{args}, world!");
    });

    return View();
}

接著就讓我們執行看看，當我們按下按鈕…

這樣就能成功在前後端之間傳值了！但要注意，它是建立一個 Channel 來傳遞訊息，所以兩邊的 channel 名稱可不能錯了。

另外也有提供同步版本的 ipcRendered.sendSync() 與 Electron.IpcMain.OnSync() 等等方法，相關的操作可以參照官方的 API DEMO 中的 Controllers/IpcController.cs 及 Views/Ipc/Index.cshtml

而關於 IPC 的說明，可以參考這篇 [Electron] IPC 機制，以及官方文件：ipcMain、ipcRenderer

打包成執行檔（.exe）

既然是桌面軟體，當然是要包裝成 exe 直接執行囉。畢竟總不能做了個小工具分享給朋友，還要「欸你自己開專案建置一下」吧 XD

在專案資料夾下用命令列輸入指令 electronize build /target win ，其中 /target 除了 win 也可以指定 osx, liunx 等等

編譯需要一段時間，直到看見 done 就可以了

編出來的安裝包和執行檔會在 bin\Desktop 和 bin\Desktop\win-unpacked

稍微打開看看

可以正常執行！

後記

目前只做到專案成功跑起來和一些簡單的測試而已，幸虧黑大的文章跟網路上的一些教學相當完整，並沒有花費太多時間。但是畢竟約好了要玩玩看這個框架，且許多功能沒有試過，例如 Electron.NET API 快速巡覽提到的大多功能，~~因此還在煩惱後續的紀錄要集中在這一篇還是另外開成系列文，這部分等下週更新再說囉。~~

6/29 更新: 最後還是決定把最近嘗試的都集中在這一篇了，畢竟我還是挺懶的，這樣比較好找嘛～

另外有興趣自己試試的朋友，也可以參閱官方文檔其實相當完整。基本上只要會寫網頁，就能夠寫桌面 GUI，真是有夠賺。

最後要特別感謝一下，當我開 Visual Studio 預設的範本時，赫然發現只有 Angular 和 React 的模板可以直接用，竟然沒有 Vue！真是嚇傻我了，幸好最後有找到 VueJS with Asp.Net Core 3.1 Web API Template 才不致落得自造輪子的下場，感謝前輩們和社群的貢獻，南無南無。

參考資料

讀《黑馬思維》

Igouist (Igouist) — Sat, 20 Jun 2020 00:22:00 +0800

每個人都是天才。但如果你用爬樹能力來斷定一條魚有多少才幹，牠整個人生都會相信自己愚蠢不堪。

本篇整理一下這陣子讀《黑馬思維》這本書的筆記，以及一些個人心得。

章節目錄

本書的目的是研究那些橫空出世的黑馬。但在研究少數的黑馬之前，就必須先說明何謂多數，所以本書前段著重在介紹什麼是標準化。

從工業革命至今，為了能大量生產、品質穩定、降低成本、最終達到「一致、大量、簡單、有效」的效果，最直接且有效的做法就是制定流程和規定。不管是製造業，或者是教育，甚至是人生，群眾總是試圖找出一個固定的流程，鋪設一條筆直的道路，並且告訴大家：只要遵循這個路線，就能夠達到成功。

雖然比起更加以前的階級制而言，標準化的做法的確更加公平了。然而為了達到標準一致，勢必得要重視群體、忽視個人。標準化的做法將所有人一視同仁，如同工廠的機器，或是程式的流程，認為設定好的輸入，經過了制定好的流程，就該有期待的產出。為了達到標準，因此無法認為每個人是特別的，甚至那些過於特別的，反而對標準化而言是個麻煩。

標準化的成功很直接：跟別人做一樣的事，但做得更好，就是最佳路線。

但有一些人，並不遵循標準化建議的路線，仍然取得了成功，他們就是黑馬。在個人化崛起的這個時代，媒體、醫療、廣告，甚至教育都開始有了量身打造的選項，隨處可見精準投放，個人菜單，標準化漸漸被個人化取代，於是作者們提出了疑問：什麼是「個人化的成功」呢？他們開始研究這些黑馬。

直接結論：黑馬們的個性、背景和領域都不大一樣，然而他們有一部分是相似的。有些人說：我認為自己做的事情是值得的，有些人說他感覺到熱忱，也有人說這是他的天職。黑馬的共通點在於：他們都並非為了想要成功或是達到目標才努力前進，而是靠著追求自我實現而成就卓越。

Chase Excellence, Success will follow. - 3 Idiots

而對於這些黑馬如何追求自我實現，如何走出和標準化不同的路。本書提出以下四個重點：

知道你的微動力
清楚你的選擇
了解你的策略
忽略你的目的地

知道你的微動力

說起來很直接：嘗試去弄清楚：什麼對你最重要？你渴望什麼？不渴望什麼？

標準化提升動力的方式著重在整體，例如辦公室喜歡更換座位，班級有共同獎章等等，然而那並不等於個人的動力；標準化也常提出大方向的動力，例如成長。誰不想要成長呢？但並不是對所有人有效，只一昧喊著要成長要成長，既虛幻又遙遠。我們需要的是確實一點的動力。

因此，觀察自己對什麼有動力是相當重要的。書中舉了相當多例子，諸如喜歡整理實際空間，喜歡立體文物等等。微動力也可以分得很細，賞鳥就能分成喜歡看的和喜歡聽的。去觀察、找出自已的微動力，並思考如何應用它，讓生計結合天性，才能更有動力，也更加快樂。

但要觀察自己的動力是不容易的，因此書中提出了評判遊戲。稍微留意一下，你什麼時候會評判別人？當你評判別人的時候，為什麼會有這些感覺？

書中的例子如下：如果你評判說「追逐名利的人怎麼會快樂」，那可以知道名利對你可能不太重要；而如果評判「這傢伙只是個修沙發的，哪有可能多成功」則可以推論出地位跟讚揚可能對你很重要。微動力了解的越仔細越有幫助，掌握的越多越能夠有機會把他們互相結合

善加留意你自己的想法，去剖析自己，如此才能更了解自己。

而找出動力之後，令我最驚訝的部分是：書中並不建議單純遵循著自己的熱情行事。相反的，應該要打造自己的熱情。遵循熱情是很簡單的，然而，這些動力會隨著時間轉變。打造熱情就比較辛苦，必須主動地去整理、了解自己的動力，根據不同機會和要求去啟動不同的微動力，如此長久下來的報酬將會相當可觀，並且也更有彈性。

至少哪天你熱情燒盡不想幹了，你能知道你想做的其他動力，而不會茫然失措；而在你動力尚存時，你也能明白自己在做什麼，而能夠保持熱情。

清楚你的選擇

標準化的制度下，有許多看似選擇，實際上卻是被揀選的情況。例如我們的大考，似乎是你考了分數，然後你主動選擇了這些學校；但實際上，是這些學校先選好要不要錄取你，你只能從被決定好的選項之中挑一個。

選擇是一個主動的行為。你有選擇的自由，可以自己創造甚至沒有人考慮過的機會。

挑揀則是一個被動的行為。你挑揀一個別人給的選項，等於是別人替你真正做了選擇，你只是從他們替你準備的巧克力盒裡挑一顆來吃。 -《黑馬思維》

關於選擇和揀選的關係，我個人推薦這篇「佩迪特的共和主義 —— 一種對自由的理解」，內文中舉例的馬兒、不被阻擾及不被干涉的差別，我認為和選擇與揀選的差別是一致的。

當然，如同書中所述，有些人主張：如果選擇過多，就等於無法選擇。這是合理的，而書中的對應我認為相當精采易懂：

如果你是一隻鳥，你會選擇住哪？亞馬遜盆地的熱帶雨林？緯度很高的青藏高原？明尼蘇達州淒冷的湖邊？

選項這麼多，要做出選擇還真是非常棘手。不過如果你是一隻鳥，做選擇一點也不難：你是哪種鳥，就選哪種棲地。 -《黑馬思維》

按照你所了解的自己，你的特質、你的動力去做選擇就可以了。只要你足夠了解你自己，自然就能做出選擇，需要考量的問題只在於：你自身的微動力和這個選擇契不契合？

標準化著重於成功的機率，而這是整體的機率，不是你的。你應該衡量你自己，考量你的動力，著重於你自己。掌握你自己，就能清楚你的選擇。

了解你的策略

有在玩遊戲的人，不論是槍戰、棋類甚至動作遊戲，應該都很清楚一個道理：沒有最佳策略，只有當下最適合的策略；大方向儘管一致，但細節決定勝負。對於黑馬來說，當下最好的策略就是找出最適合你的策略。

書中舉了相當多例子來展示策略的多樣性，例如魔術方塊的解法，品酒師對酒類的記憶法等等。這是相當合理的，要前往一個地方的路線本來就不只一種，最大的問題在於：我要怎麼知道哪個路線適合我？

黑馬思維的答案是：嘗試。

強項對我們而言是很模糊的，我們能知道想不想看電影，卻很難知道我們某個領域有多強。譬如說：你要怎麼知道你天生多會騎河馬？

強項關乎情境，且持續變動。我們必須嘗試，才能了解我們大致上的水平。比對標準化要求的策略大多是堅持到底，黑馬要求多加嘗試。只有經由嘗試，才能掌握現有的狀況，也才能逐步修正策略。就我來說，這和迭代開發有著異曲同工之妙。

忽略你的目的地

本書認為目的地對自我實現是有害的，對於標準化來說，提供一個目的地有助於一致性，但對個人而言卻不一定如此。

設定好的目的地會令人要求預計時間、要求進度、要求妥善規劃。然而現在的社會變動迅速，人生過程變數太多，每個人做同樣的事花費時間又不同，因此目的地的飄忽不定，反倒是一種束縛，綁死了你策略上的彈性，和可選擇的道路。

與其決定成為某個行業，再去蒐集那些行業的特質，然後花費一個預期的時間前進；不如先確定自己的特質，再逐步前進，看自己的特質和策略能到達哪裡。後者無疑更量身訂造。

然而要注意！目的地和目標是不同的，我們用遠近，或是可不可見的界線去區分它。目標是你個人的選擇，相當具體，能夠採取行動；目的地則是大家口中的目標，難以預測，相當遙遠，兩者其實在直覺上相當好區分：在截稿日前寫完，是目標；得到諾貝爾文學獎，則是目的地。

其實我個人覺得這個概念很好接受，在前進的路上，你並不會挑個目的地然後就筆直撞過去，而是會朝某個大方向，一步一步地前進。書中用梯度上升法來舉例，每一步都選更高的方向前進，那麼就能夠走到山頂。（雖然在這邊看到這詞時總感覺有點妙就是了）

本段其實是呼應最一開始的「他們並非為了達到卓越才實現自我，而是靠著追求自我實現而成就卓越」，從了解自己的動力，到不斷嘗試和修正策略。因此，如果能理解前面章節的內容，忽略目的地也是順其自然就會發生的事而已了。

黑馬或是標準化

書的後半篇幅多用於描述黑馬和標準化的差異，以及對現存制度的探討。儘管黑馬看起來人人都可以嘗試，但並不代表黑馬就得取代標準化，有些人在標準化的制度中更能取得優勢，那也是一種選擇。

本書的重點在於了解，甚至接受每個人都可以有選擇：你可以為自己負責，你可以選擇體制或是黑馬甚至是更多的路線，你能發掘自身的動力，你能夠追求自我實現。如同書中所引的，每個人都有追求幸福的權利。

心得

本來只想大略介紹一段，想不到翻著翻著就越寫越多，弄得書的介紹比心得還長上幾倍。儘管如此，我仍覺得我無法精準或是完整地表達黑馬思維所要傳達的意思，因此如果有興趣的話，還是非常推薦親自讀過一遍，自己讀過一次勝過閱讀十篇心得。

黑馬思維的結構非常明確：掌握（自己的）各項情報、選定方向、建立選擇時的準則、制定遇到狀況的做法、逐步調整、並且在當下行動。我覺得這並不是太特別的邏輯，甚至可以說是決策的通則。舉凡卡牌和戰略遊戲、行程規劃、開發專案或是各種領域，大抵都可以按照這個步驟去處理。

以我之前喜歡的卡牌或爬塔遊戲為例：你得先了解你有哪些牌能用，你有越多的牌，能做的選擇和搭配就越多。接著就是分清楚，哪些牌值得使用、哪些牌可以組合使用、又該在什麼場合使用？這些牌所組成的目標牌組，主要的策略是什麼？正好與微動力、選擇和策略不謀而合。

然而過程中的每一步能做到多少、能否判斷出最合適的選擇、策略是否經得起狀況的考驗，就是真正的差別。如果不去瞭解，你不會知道你的動力在哪；如果不去嘗試，你不會知道你的策略多可靠。

之前聽過一句話：你個人就是一個品牌，你要把自己當成品牌去經營。那麼，你就得要知道自己的優勢、知道自己的劣勢，知道其他人用的策略並不一定適合你，去嘗試分析適合你自己的模式。如此一來，才談得上是在經營自己。因此，誠摯地推薦可以嘗試去閱讀過這本黑馬思維，也許能因此找到新的路線也說不定呢。

當然，我在看這本書的時候也不是沒有疑惑。例如說，研究那些已經成功的黑馬，算不算是一種倖存者偏差呢？後來終於想通，本書更多的是在於宣導一種理念，是希望每個人都能從中找到自己的動力，因此對於實踐的方式著墨甚少，例如我該如何打造我自己的熱情？或是我該如何掌握並提升我的強項？這些都是可以進一步討論的部分。但整體來說，黑馬思維值得一讀，也許之後還會再整理相關的心得吧！下次見。

C#: 位元旗標 (Bit flag) 與列舉

Igouist (Igouist) — Sun, 14 Jun 2020 21:27:00 +0800

章節目錄

前陣子碰到個資料表儲存方式，因為這種位元運算的方式也常用在權限管理等地方，這邊就順手紀錄一下。

平常遇到二元的情形（例如開／關、有／沒有），我們會直接宣告個 Boolean 來處理。例如 bool isNice = false。

但這次遇到的是同時有多組「有／沒有」的狀況，而我遇到的程式碼並沒有分成多個 Bool 去做處理，而是直接儲存成一個數值。

這是因為「有／沒有」只佔據一個位元，那麼將多個狀況按照位元順序排列的話，就只需要一個數字就可以紀錄並傳遞給其他系統了。

例如最常見的權限系統：假設我們有「讀」、「寫」、「執行」的權限，接著就可以按照這個順序，用 1 和 0 來代表「有／沒有」來排列位元，

也就是說，如果權限是 讀＝可、寫＝不可、執行＝可 的時候，就記做 101 = 5。

這種直接用一組位元來表示狀態的方式，就叫做位元旗標（Bit flag）

1 讀   = 可
0 寫   = 不可
1 執行 = 可

/* 橫放 */
=> 101 (2進位) 
=> 5

Enum & Flags

假使某天老闆靈光一現，決定接下來的新人員工都要記錄他們會的程式語言，並且他們報到的時候就會發一張公司列好的程式語言清單請他們勾選。這時候要怎麼做呢？

在 C# 中已經有方便的工具可以處理位元旗標，我們可以建一組叫做 SkillEnum 的列舉（Enum），並且按照上面說明的，將老闆提到的每個技能各自用一個位元來表示。

[Flags]
public enum SkillEnum
{
    C = 1,     // 0001
    PHP = 2,   // 0010
    SQL = 4,   // 0100
    Java = 8,  // 1000
}

註：[Flags]的標籤是指 C# 專門提供給位元旗標使用的 Enum，請參見 FlagsAttribute。

只要在 enum 上加上 Flags 的屬性，除了自動按照 2 的次元增加以外，在使用 ToString() 也能更方便看見旗標內容

有了這個列舉之後，我們就可以表達不同排列組合的狀況了。例如：

* C: C
* P: PHP
* S: SQL
* J: Java
===========
J S P C
0 0 0 0 => 什麼都不會
0 0 0 1 => 只會 C
0 0 1 1 => 同時會 C 和 PHP
1 0 1 0 => 同時 PHP 和 Java
1 1 1 1 => 全部都會

查詢 => AND

那麼假使今天來的新人 Bob，他會 C, PHP 兩種語言，那現在他的資料欄位，就會是這兩種語言對應的位置為 1，其餘為 0，也就是 0011 = 3

var BobSkills = 3;
// var BobSkills = 0b_0011; // C + PHP

當查詢的時候，就將 Bob 的數值和目標數值做 AND 運算。例如說我們想知道 Bob 會不會 C，就可以將 3（二進位 0011）和代表 C 的 1 （二進位 0001）做 &，即可知道 Bob 會不會 C。

    J S P C
    0 0 1 1 Bob
AND 0 0 0 1 SkillEnum.C
-----------
    0 0 0 1 => 1 > 0 => True

    J S P C
    0 0 1 1 Bob
AND 1 0 0 0 SkillEnum.Java
-----------
    0 0 0 0 => 0 => False

也就是必須要 同個位置的值都是 1，在這邊就是指 Bob 的技能中 Java 的欄位，和 SkillEnum 中對應的欄位都要是 1 的時候，才會有數值。否則就會是 0：

var BobSkills = 3;
// var BobSkills = 0b_0011; // C + PHP

// 確認是否有某個 Flag，使用 And(&)
var isBobKnowC = BobSkills & (int)SkillEnum.C;
$"Bob 會使用 C 嗎？{Convert.ToBoolean(isBobKnowC)}".Dump(); // True

var isBobKnowJava = BobSkills & (int)SkillEnum.Java;
$"Bob 會使用 Java 嗎？{Convert.ToBoolean(isBobKnowJava)}".Dump(); // False

賦予 => OR

那假設 Bob 經過一番苦練，又掌握了 SQL 這門語言呢？當我們要賦予的時候，就需要用 OR。

也就是當 兩者之間任一為 1 的時候，在這邊也就是當 Bob 的技能和我們要求給他的 SkillEnum 同位置只要有一個是 1，那就會有數值：

    J S P C
    0 0 1 1 Bob
 OR 0 1 0 0 SkillEnum.SQL
-----------
    0 1 1 1 => New Bob

例如說原本 Bob 不會 SQL，所以 SQL 那一欄就會是 0 。而我們把它和 SkillEnum.SQL（也就是只有 SQL 那一欄是 1 ）做 OR 運算後，接著我們只要將運算好的結果再賦值給 Bob，這樣 Bob 的 SQL 欄位就會變成 1 了，同時也不會影響到其他欄位。

現在我們就可以用 OR 把 SQL 的技能傳授給 Bob：

var isBobKnowSQL = BobSkills & (int)SkillEnum.SQL;
$"Bob 會使用 SQL 嗎？{Convert.ToBoolean(isBobKnowSQL)}".Dump(); // False

// 賦予某個 Flag，使用 OR (|)
BobSkills = BobSkills | (int)SkillEnum.SQL;
$"（Bob 學習 SQL 中）".Dump();

isBobKnowSQL = BobSkills & (int)SkillEnum.SQL;
$"Bob 會使用 SQL 嗎？{Convert.ToBoolean(isBobKnowSQL)}".Dump(); // True

移除 => XOR

經過了很久很久以後，Bob 已經忘記當年學的 SQL 怎麼寫了。我們又要怎麼把他的 SQL 這項技能給拿掉呢？

當我們要移除某一項旗標的時候，只需要使用 XOR 就行了。XOR 是指互斥，就像磁碟兩極一樣。當兩者不同為 1，若相同時則為 0。

因此當 Bob 代表 SQL 的欄位為 1 的時候，我們再將 SQL 為 1 的的數值丟進去做 XOR，就可以把兩者同時為 1 的欄位給變回 0，並且讓原本為 1 的欄位持續為 1，原本為 0 的欄位持續為 0，達到移除指定目標的效果。

但在使用上要注意，必須先確認目標欄位的確有數值，也就是 Bob 是真的已經會 SQL，否則若原本不會 (0) 的將不小心學會 (0 XOR 1 => 1)。

    J S P C
    0 1 1 1 Bob
XOR 0 1 0 0 SkillEnum.SQL
-----------
    0 0 1 1 => New Bob

// 警告：使用 XOR 之前一定要先檢查，若原本是關閉 (0) 的將會被打開 (0 XOR 1 => 1)

現在我們就讓 Bob 忘記他曾經學過的 SQL：

isBobKnowSQL = BobSkills & (int)SkillEnum.SQL;
$"Bob 會使用 SQL 嗎？{Convert.ToBoolean(isBobKnowSQL)}".Dump(); // True

// 挪除某個 Flag，使用 XOR (^)
BobSkills = BobSkills ^ (int)SkillEnum.SQL;
$"（Bob ... 忘記了SQL！）".Dump();

isBobKnowSQL = BobSkills & (int)SkillEnum.SQL;
$"Bob 會使用 SQL 嗎？{Convert.ToBoolean(isBobKnowSQL)}".Dump(); // False

多項賦予 => OR, OR, OR

隨著 Bob 逐漸老去，公司也招來了新員工。如今換成 Bob 來幫他維護技能表了，那我們要怎麼用 SkillEnum 給這個菜雞預設值呢？

聰明的你應該能猜出其實這也就是賦值！只要把有的項目全部 OR 起來就可以了，這位新菜雞他會 C, SQL, Java：

    J S P C
    0 0 0 0 Newbie
 OR 0 0 0 1 SkillEnum.C
 OR 0 1 0 0 SkillEnum.SQL
 OR 1 0 0 0 SkillEnum.Java
-----------
    1 1 0 1 => 13 => Newbie's Skills

那麼現在就讓我們用 C# 實作：

// 賦與多個值 ＝ 一路 OR 下去
var NewbieSkills =    
    (int)SkillEnum.C |   
    (int)SkillEnum.SQL |     
    (int)SkillEnum.Java; 

$"Bob 技能欄的十進位為：{NewbieSkills}".Dump(); // 13
$"Bob 技能欄的二進位為：{Convert.ToString(NewbieSkills, 2)}".Dump(); // 1101

列出內容 => Foreach, Flags

那如果我想要確認現在有哪些欄位是開啟的呢？例如說，當我們要確認 Bob 會哪些程式語言的時候怎麼做呢？

既然用 AND 可以查詢其中一個位置，那麼只要將列舉和位元用迴圈逐一 AND 出來，就可以還原 Bob 的列表囉

var enumCount = Enum.GetNames(typeof(SkillEnum)).Count();
var NewbieSkillsList = new List<string>();

for (var i = 0; i < enumCount; i++)
    if(Convert.ToBoolean(Bob2Skills & (int)Math.Pow(2, i))) // AND 運算
        NewbieSkillsList.Add(((SkillEnum)Math.Pow(2, i)).ToString());
$"Newbie 會的語言有：{String.Join(", ", NewbieSkillsList)}".Dump();
// C, SQL, Java

不過上面這個依序列印的方式還是太麻煩了。如果有像前半段提到的，替 Enum 加上 [Flags] 標籤的話，用起來就更簡單了：

$"Newbie 掌握的技能為：{(SkillEnum)NewbieSkills}".Dump(); 
// C, SQL, Java

最後再總結一下：

檢查的時候用 AND 找出目標的位置是否為 1
賦予內容時則用 OR 讓指定的位置變成 1
移除的時候則用 XOR 讓目標位置的 1 抵銷為 0

整理來說概念並不困難，只是一個位元對應一個對象，再視情況進行運算而已。但能應用的範圍相當廣泛，除了最常用的權限管理，其他諸如活動月份、門鎖狀況等等只要符合條件的情形都可以借這個方法來處理。這邊稍作紀錄，希望以後能派上用場。

延伸閱讀及參考資料

WakaTime —— 我 Coding 了多久？

Igouist (Igouist) — Sun, 07 Jun 2020 22:10:00 +0800

這一周又是 ~~偷懶週~~ 繁忙週，因此就跟大家分享一個有趣的網站：WakaTime

WakaTime 能夠幫你自動記錄寫程式的時間、常用語言及專案，只要簡單地在常用的 IDE 設定好擴充套件就可以達成。 WakaTime 支援的 IDE 可以參閱 WakaTime - Plugin

註冊相當簡單，此處就不贅述。稍微介紹一下儀表板的各區塊的功能：

左上會有最近的專案及花費時間，每個色塊都是一個專案，滑鼠移上去就會顯示專案名稱。

點擊其中一天更會顯示當天的時間軸，可說是無所遁形。至於它判斷專案名稱的方法是看你編輯的檔案所在的資料夾名稱。

右上是編寫和測試的所佔時間，不過我在使用的時候常常抓不到測試和建置的時間，因此沒在意過。

正左則是當天的時間軸和某幾段時間正在處理的專案，可以清楚看到大概哪個時段在認真 Coding（因為都是公司專案，這邊就先碼一下）

正右則是達到目標的比例，WakaTime 可以到左側選單的 Goal 設定個人目標，例如每週幾個小時，就可以在這邊看自己當天的達成率如何。

左下則是最近常使用的語言和比例，主要是抓取編輯中檔案的副檔名自動判定。另外也能到 Settings -> Custom Rules 去設定個人化的規則，例如我個人就會將 .ipynb 計時到 Python 中。

右下就很直覺，就是紀錄常用的 IDE 的時間，像我個人挺偏食的，就不常看到這裡。不過一些用瀏覽器的 Coding 方式就不太適用，像我常用的 Jupyter notebook 基本上就是抓不到，許願希望之後的 Chrome 能支援。

除了上面這些區塊，往下拉也可以看到最近的專案耗費的時間，可以看看最近耗費比較多的專案有哪些。

環境設定

WakaTime 主打的就是輕便、自動計時。因此設定步驟也相當簡單，各 IDE 的設定步驟可以從 WakaTime - Plugin 裡點選自己用的 IDE 進去看安裝介紹。這邊就以我最常用的 Visual Studio 做示範。

首先點選 Wakatime 右上角的個人頭像，進入 Settings，確認左側在 Account，這時應該能看到自己的 API Key，點選顯示之後先複製下來。

之後打開你的 Visual Studio，上方工具列點選 延伸模組 -> 管理延伸模組，開啟模組管理員之後選擇線上，搜尋 Wakatime 並安裝。

重啟 Visual studio 並安裝完畢後，再度打開時應該會自動跳出設定畫面；如果沒有跳出來，也可以從上方工具列點選 工具 -> WakaTime -> Settings 進入設定畫面

設定畫面如下，將剛剛複製的 API Key 貼上。如果是在公司或是有需要設定 Proxy 的地方記得也順便填一下

這樣就設定完囉！是不是很簡單呢？之後當使用 Visual Studio 寫程式的時候，就會自動記下時間、程式類型、資料夾名稱並傳到 Wakatime 做統計囉

當然，對於背景紀錄資料有疑慮的朋友，也可以直接翻 WakaTime 的 Github。這個套件是完全開源的。如果嫌使用擴充太無聊或是想自己開發個比較好看的儀表板的朋友，也可以參閱 Wakatime 的開發者頁面呦。

最後關於紀錄的部分，之前有看到實測說單純掛網走人是不會算時數的。不過會這樣做的人，本來也就沒什麼動機去用這類時間記錄的工具吧！

後記

要注意，免費用戶只能看最近 14 天的紀錄，要看完整紀錄就必須付費，我個人因為是看心情愉快的，因此免費版已經很符合我的需求。若是使用多個 IDE 或想當成時數管理的朋友，又或者是想戰排行榜的朋友，可以使用一陣子再考慮囉。但要強調，紀錄時間只是做為參考使用，並非工作的標準喲！畢竟弄文件跟查 Bug 更花時間嘛。

雖然又水了一篇，不過也是挺想把這東西介紹給大家用用看。雖然我個人做時間紀錄大多是使用 Toggl 來計時，不過偶而開 WakaTime 看看自己最近花多少時間在 Coding？都在寫什麼？專案之間的時間分配得如何？就有種更能掌握自己最近都在忙些什麼的感覺。有時看到柱狀圖一排高聳，或是連續幾周達成目標，就會更有戰鬥力的感覺；若是發現最近時數低落，也會心虛想要彌補一點。如此也是挺有一番趣味，共勉之。

我要訂便當 (5): Heroku 填坑小記

Igouist (Igouist) — Sun, 31 May 2020 23:24:00 +0800

在上一集的將 Python 腳本部署上 Heroku 中，記錄了將 Python 腳本放上 Heroku 的過程，但仍然沒有將我們的訂便當小幫手給放上去。之前有稍微提到是因為過程中遇到了一些問題，最後決定將這些問題和找到的前人解決文記錄在這一篇，將來再遇到的時候就可以參考。

SQLite 要改成用 PostgreSQL
在 Heroku 上執行 Selenium

一、SQLite 要改成用 PostgreSQL

在之前的我要訂便當(2) —— 用 Python + Sqlite 儲存訂單中，為了方便及簡單性，選擇了較輕便的 SQLite 來儲存我們爬回來的訂單資訊。然而，SQLite 將資料儲存在小檔案以便於攜帶的做法，在 Heroku 上將會遭遇像是各個 dyno 的資料不同步等許多問題，因此 Heroku 是不建議使用 SQLite 的。

在 Heroku 的開發文件中的 SQLite on Heroku 有關於這部分的詳細說明，並直接提到「If you were to use SQLite on Heroku, you would lose your entire database at least once every 24 hours.」同時，官方也提供了他們的建議：PostgreSQL。相較於輕便但只能同時單一寫入而且還會在 dyno 炸掉的 SQLite，PostgreSQL 的完整性更符合 Heroku 對服務的要求。

關於在 Heroku 上使用 PostgreSQL 的做法，這篇佈署 Python Flask 網站留言板應用程式到 Heroku + PostgreSQL 資料庫系統說明得相當詳細。

這邊簡述一下操作過程（當然，還是建議進入上面推薦的網頁直接照圖操作）

首先，先進到專案的頁面，選擇 Resources 分頁並往下到 Add-on，擴充套件基本上都從這裡開始安裝，事實上遇到的許多問題都會到這裡用擴充套件解決。在此就先輸入 Postgres 並安裝 Heroku Postgres，並且選擇免費方案。

安裝完畢之後，可以點選 Heroku Postgres 進入擴充套件管理的頁面，這邊進去 Setting 就可以進行相關的設定，也能從這邊取得帳號、密碼及資料庫URL。

Heroku 部分設定完畢之後，就要回來改我們便當的程式碼。相對於當初 SQLite 時使用的 sqlite3 包，這次要操作 PostgreSQL 則是要使用 python-psycopg2 這個包。

相關的操作可以參考 Gitbook.net 的這篇 PostgreSQL 連接 Python。可以發現整體的操作方式和之前使用 sqlite3 並沒有什麼太大的不同，因此略做修改之後就可以使用囉。

本區段的參考資料

二、在 Heroku 上執行 Selenium

前面的我要訂便當(1) —— 用 Python + Selenium 控制瀏覽器取得訂單中，能取得訂單內容主要都是依賴於 Selenium 控 chrome 上。然而我們丟上 Heroku 後… 哪來的瀏覽器啊！因此遭遇到了這整個專案最大的存在危機（？）

幸好後來有找到這篇 Running ChromeDriver with Python Selenium on Heroku，裡面有說明如何順利在 Heroku 上跑 Selenium，實在是相當感謝，這邊也記錄一下。

我們在前面我要訂便當(4-1) —— 將 Python 腳本部署上 Heroku 有提到，Heroku 有建置包這東西來協助建置專案，也提到 Python 是 heroku-buildpack-python。這邊就是建置包去建出 webdriver，因此使用 heroku buildpacks:add 的指令去加入 heroku-buildpack-chromedriver heroku buildpa 這個建置包。

加入完畢之後，要設定 heroku 的 config 去指定 chrome 和 chrome driver 的路徑

heroku config:set GOOGLE_CHROME_BIN=/app/.apt/usr/bin/google_chrome
heroku config:set CHROMEDRIVER_PATH=/app/.chromedriver/bin/chromedriver

最後只要修改程式就可以囉，一樣先指定好路徑

GOOGLE_CHROME_PATH = '/app/.apt/usr/bin/google_chrome'
CHROMEDRIVER_PATH = '/app/.chromedriver/bin/chromedriver'

並且在設定 selenium 的部份加上一些 chrome 的參數

chrome_options.add_argument('--disable-gpu')
chrome_options.add_argument('--no-sandbox')
chrome_options.binary_location = GOOGLE_CHROME_PATH

在初始化 webdriver.Chrome 一併傳入就可以囉！說起來之前 chrome 被我改壞時，也是靠 -no-sandbox 才開起來的，關於 sandbox ，可以看 Google 的這篇漫畫，或是這篇 Inside 的簡單介紹。

本區段的參考資料

結語

訂便當系列到這邊也告一段落了。事實上到了中後期，為了配合公司環境已經把爬蟲放在公司跑，並改成拿去接公司指定的通訊軟體，Line notify 這邊就比較少繼續碰了。中間遇到的一些問題也是有空加減解的程度，因此暫時沒有繼續更新訂便當的打算了。

但 Heroku 實在是挺方便，之後應該還是會嘗試把其他東西丟上來跑看看，也因此還是覺得要把這些小問題記錄下來，之後如果遇到別的相關問題，也比較方便集中起來，因此就有了這兩篇的紀錄。

那麼本週就到這裡，之後還會找新的坑來跳，畢竟菜雞就是不斷地踩坑嘛！感謝收看～

我要訂便當系列

Json View —— 用 Chrome 打開 Json 的正確方式

Igouist (Igouist) — Sun, 17 May 2020 15:39:00 +0800

本來這週已經沒梗了，不過同學來問了個接 API 的問題還附了照片，頓時決定順手推一下好用的瀏覽器插件：Json View。

Json View 是一款 Chrome 的擴充套件，能把 Json 格式的資料重新排版，保護妳我的眼睛。

備註：關於 JSON 可以參閱 JSON精要讀書紀錄

照慣例來張效果圖鎮樓

該同學傳來的圖片是長這樣的（示意圖，非當事 API，用 UBike 開放資源臨演）

突然還以為咱們要玩威利在哪裡，這不是欺負我眼睛不好嘛。

但畢竟只是小問題，不能開口就要人家給 Swagger 或用個 Postman（API 測試神器，之後也來推薦一篇），用圖片描述也是無可厚非，但還是必須顧眼睛。因此現場直接就推薦同學安裝這款 chrome 插件：Json View

安裝之後再度使用瀏覽器打開 API，就會是長這樣的：

經過自動排版之後，這不是好看多了！

這邊真心推薦用 Chrome 的朋友，就先裝下來吧；至於火狐似乎原本就會幫忙整理排版了；用 IE 的話，就當我沒說。另外也要感謝親愛的同學，~~又讓我水了一篇~~

ps: 最後效果跟鎮樓圖有差別？因為我是黑色主題的愛好者，所以這就再推一個擴充套件囉：Dark Reader。謝謝觀看，咱們下次見～

Carbon —— 把程式碼片段截成有質感的圖片吧

Igouist (Igouist) — Sun, 10 May 2020 23:57:00 +0800

開始挑戰每週寫文之後，發現最大的敵人根本不是寫文這件事，而是自己的惰性啊。像這次母親節假期過太爽，差點兒就忘記發文…… 所以這週就還是偷懶工具介紹囉。

今天要分享的是 Carbon 這個工具，它能夠將貼上的程式碼輸出成圖片，並且支援程式碼上色，還可以自選字型、背景色等等，產出的圖可以說相當有質感。

當傳送圖片比較快或排版比較好的場合（例如Line, Facebook..），或是在部落格和文件中想直接放漂亮圖片，以及需要示範給對方看可是又不想要對方直接複製貼上的時候可謂是相當實用。

先來一張成果圖鎮樓：

Carbon 的操作相當直覺且簡單，進入 Carbon 的頁面後，中央的程式碼區塊可以自由編輯，通常會直接將要做成圖片的程式碼貼於此處。

而程式碼區塊的上方的兩個下拉選單分別是程式碼區塊的配色主題和程式語言，主要的樣式（例如程式碼上色）會以這兩個為主。

接著的調色盤則是背景色，即程式碼區塊外的顏色，也支援透明度。像我要將圖片放在部落格時，就可以讓背景色和部落格一致，使中央的程式碼區塊更強烈。

最後的齒輪則是設定，字型和陰影等都可以從裡面做調整。不過選項挺多的，建議可以自己都調看看，像我個人就固定會把上方的狀態列關閉。

而右側就是匯出的部分了，有發推特（真的有人會這樣發？我很懷疑）以及下載的選項，下載可以直接點選，或是下拉式輸入檔名和變更圖片大小格式等等。

這邊就直接拿上一篇的 Line Notify 範例的程式碼來試試吧。

而製作出來的效果就會像這樣子：

這工具對我個人來說挺喜歡的，有時候要傳程式碼給同學都會直接截圖，有了這個之後就可以傳得優雅一點（對我就是想叫你自己打）

但還沒有用在部落格的打算，畢竟我身邊問過的人都表示：如果他們找到的網頁不給複製就會直接關掉。這… 我選擇妥協。

那麼今天的工具推薦就到這邊，歡迎立馬用你的同學 or 同事來試試看，保證能促進友誼、增加互動呦！

參考資料

其他相似工具

我要訂便當 (4): 將 Python 腳本部署上 Heroku

Igouist (Igouist) — Sun, 03 May 2020 23:55:00 +0800

2024.10 更新: Line Notify 將於 2025 年 3 月停止服務（LINE Notify 結束服務公告），有看到這篇的朋朋請選擇一組新的通知服務來串吧 QQ

目標：紀錄一下如何將 Python 寫好的東西丟上 Heroku

在先前的訂便當系列中已經建立了一個替我們去爬便當網並通知我們的小工具，但還存在一個相當大的問題：要在哪跑？總不能就只放在家裡電腦有開機就跑、沒開機就算了吧？因此我們必須找個主機把它放上去。而在上一篇做 Line Notify 的時候所參考的如何快速建置一個 LINE Notify 的服務中提到了將服務放上 Heroku 的部分，因此馬上嘗試看看。

結果過程中碰了不少壁，因此特地紀錄下來。

Heroku 是一個雲端平台，讓使用者可以把服務丟上去跑，~~同時最讚的部分是，免費用戶就提供了每月 450 小時可以使用（但有每半小時會進入休眠的限制）~~，詳情可以參閱 Heroku 的計費頁面。

更新：Heroku 已經改為收費方案了 QQ

本系列最後一階段的目標就是要將訂便當爬蟲整套丟上去雲端上運行，達到被動接收通知的效果。但由於訂便當爬蟲還牽涉到用 Selenium 開瀏覽器互動，以及使用 Sqlite 儲存的部分，轉移到 Heroku 的環境上還需要進行一些調整。因此這一階段將會分成兩篇（或以上）文章進行，上篇會先簡單地紀錄如何將服務放上 Heroku，下篇開始則著重於紀錄將訂便當系統放上 Heroku 時遇到的問題和解決過程。

本篇主要的參考來源來自於搭配 Git 在 Heroku 上部署網站的手把手教學、發布網站到 Heroku 以及網站部署（使用 Heroku）這幾篇，其餘參考將附於文末，感謝各位前人大大留下的優質文。

註冊及安裝

Heroku 的註冊相當簡單，這邊就略過不提，需要說明可以參考這篇。

註冊完畢就會回到個人頁面，底部有 Heroku Dev Center，也能選自己慣用的程式語言進去教學說明，有興趣的可以逛個一圈。

這邊我們就先新增一個應用程式，點選畫面中間左側的 Create a new app

接著輸入應用程式名稱，注意只能使用小寫，並且不能重複。如果已經使用後續會提到的 CLI 的朋友，也可以直接使用 heroku create 的指令來建立應用程式。

建立完成之後就會進到專案的頁面：

可以看見 Heroku 提供了幾種方法來將應用程式推送到 Heroku 上，例如連接到 Github。我們這邊用 Heroku CLI 試試，頁面上也已經提供了步驟說明。

Heroku CLI 的安裝說明頁面，在這邊挑選自己的系統下載並安裝。

安裝過程也相當簡易，會有將 Heroku 加到環境變數和路徑等選項，一路下一步即可。

裝完之後，打開命令列輸入 Heroku，如果有跳出指令列表就代表安裝已經成功

連接至 Heroku

備註：由於 Heroku 傳送檔案的方式是使用 Git 進行，因此在後續的操作之前，必須先確保電腦中已經安裝 Git

接著我們就按照上面 Heroku CLI 說明頁面的步驟開始操作。

首先要先登入，輸入 heroku login 之後，便會開啟瀏覽器進行登入驗證，如果成功會看見登入訊息

接著就可以移到專案的資料夾，將專案和 Heroku 做連接

# 先移動到專案的資料夾
$ cd my-project/

# Git 初始化
$ git init

# 和 Heroku 專案連接
$ heroku git:remote -a Heroku的APP名稱

環境設定及測試

這邊由於前面提到訂便當系統有部分要調整的關係，因此只使用我要訂便當(3) 的 Lint Notify 測試版的 Line Notify 上去試試看。上一集的簡單 Line Notify 程式碼如下，這邊命名為 myApp.py：

import requests

def lineNotifyMessage(token, msg):
    headers = {
        "Authorization": "Bearer " + token,
        "Content-Type": "application/x-www-form-urlencoded"
    }

    payload = {'message': msg}
    r = requests.post(
        "https://notify-api.line.me/api/notify",
        headers=headers,
        params=payload)
    return r.status_code


message = 'Line Notify + Heroku 測試'
token = 'YOUR TOKEN'
result = lineNotifyMessage(token, message)

接著除了主要的 py 檔以外，還需要一些檔案去告訴 Heroku 怎麼處理我們的服務。

事實上我第一次是直接就把 py 傳上去 Heroku 然後建置大失敗，還好 Google 了一陣有前人指點，這邊的設定部份參照自如何使用 Heroku 部屬一個 Web App 網頁應用程式，特此感謝。

不過 Heroku 還不知道怎麼建我們的服務，因此這邊還需要新增幾個設定的檔案：

Procfile

用來告訴 Heroku 怎麼運行我們的服務

worker: python myApp.py

這行的意思是：worker 的運行方式是 python myApp.py 這行命令，Heroku 會根據這個文件的內容去建 dynos 容器來運行我們的應用服務。

像上面的參考文章在建置 Flask 時，就將運行 web 的命令設定為 gunicorn flask_app:app 讓 Gunicorn 去起網站來跑。

由於這次的示範組只是個小腳本，因此我們宣告個 worker 而不是網站方便之後處理。當宣告的運行是 web 時，Heroku 還會幫忙接 HTTP 的內容，當然想包裝成 Web APP 的朋友，也可以參考上面的文章將腳本包裝成簡單的 Flask。

關於 Procfile 和 dynos，可以參見 Heroku 運行類別、 Procfile、常用指令筆記以及 Heroku 官方的 Dynos (app containers)

這邊另外要注意的地方有兩個：這個檔案是不需要副檔名的，而且大小寫請正確。我在碰壁的過程中有遇到本機測試可以但推送上去就不行的情況，後來發現是打成全小寫了，改成字首大寫就正常，因此這邊提醒一下大家。

requirements.txt

用來標示需要安裝的套件，逐行列出套件即可，也可以用 套件名稱==版本號 的方式指定套件版本。由於測試的程式碼只用到 requests，因此這邊列上 requests 就可以了。

requests

runtime.txt

用來標示 Python 的版本，這篇文當下的版本為

python-3.7.6

本機測試

到目前為止沒意外的話應該會包含這些東西

這邊可以嘗試在本機測試看看，打開命令列輸入 heroku local worker 就可以在 localhost Run 起來看看囉。注意這是在本機啟動 worker 這個 dynos 的意思，所以如果前面的 Procfile 是使用 web 的朋友，這邊就要輸入 heroku local web 囉。

想要全面啟動，可以直接輸入 heroku local；想要指定 Port 的也可使用 heroku local -p 7000 等等，可以參見 Heroku 運行類別、 Procfile、常用指令筆記的啟動段落有比較常用的用法。

如果一切安好，就可以開始嘗試部署囉

部署至 Heroku

Heroku 的部署只需要用 Git 推送上去就可以了，也就是只需要

# 把所有檔案都加到這次變更
$ git add .

# Commit 所有變動（記得標註解，養成好習慣）
$ git commit -am "這是Commit註解"

# 推送
$ git push heroku master

就可以發到 Heroku 進行部署了，推送時也能看見建置的過程，如安裝的包和建置是否成功等資訊都會顯示

如果前面架上去的是網站，也就是 Procfile 使用 Web 的朋友，Heroku 應該會幫忙把服務建起來。而像我是另外定義 worker 的朋友，這邊還需要多一個把 dynos 建起來的動作

命令列中輸入 heroku ps 就可以看到現在正在運行的服務，如果沒有任何服務運行，或是想擴展服務，可以使用 heroku ps:scale Procfile裡定義的服務=服務數 來操作。

例如我是使用 worker，這邊就輸入 heroku ps:scale worker=1 就會開啟一個 worker 來運行；反過來說，輸入 heroku ps:scale worker=0 就可以停止 worker 的服務囉。

如果這邊部屬和運行有問題的朋友，可以查看 Heroku 的 Log：在命令列輸入 Heroku log 就會顯示了（建議搭配 --tail 等方法使用，詳請可見官方文檔）

此外，若是跟我初嘗試一樣跑出 Couldn't find that process type 請參照這篇，我個人是修改 Procfile 檔名的大小寫就解決了

若是建置時無法成功的朋友，可能是沒抓到你的服務的語言（例如 Python），需要自己去拉一下 buildpacks，例如 Python 的建置包就是 heroku-buildpack-python

最後我們回來看一下 Heroku 的 APP 頁面

Activity 可以看見最近的活動，例如部署失敗也會顯示在這；而 Settings 則是一些專案設定，例如名稱和建置包都要到這裡調整

其中可以從 Domains 這裡連到你的服務，如果你放的是網頁或 API 的話就可以從這裡進入。不過更快進入自己服務的方法，是在命令列中直接下 Heroku open 就行啦。

後記

其實原本打算部署的部分一篇解決的，沒想到牆就這樣撞了上來，將便當放到 Heroku 上時實在遇到挺多問題，例如第一次使用時直接把整坨檔案直接推上去也沒設定結果建置失敗，或是發現 Heroku 不給用 Sqlite，或是 Selenium 要另外找建置包等等，因此最後決定切成兩篇，一篇好好記 Heroku 的流程，剩下的部份再按照問題做紀錄。

同時因為原本的訂便當已經在家裡電腦跑著了，部屬上雲似乎是額外再戰的部份。待到剩下問題解決了，抓緊下班時間再寫上來記著，希望以後能派上用場吧。