<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom"><channel><title>概念 on Davish.Sendr</title><link>https://davidchen617.github.io/Davish.Sendr/zh-tw/concepts/</link><description>Recent content in 概念 on Davish.Sendr</description><generator>Hugo</generator><language>zh-TW</language><atom:link href="https://davidchen617.github.io/Davish.Sendr/zh-tw/concepts/index.xml" rel="self" type="application/rss+xml"/><item><title>分派模型</title><link>https://davidchen617.github.io/Davish.Sendr/zh-tw/concepts/dispatch-model/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://davidchen617.github.io/Davish.Sendr/zh-tw/concepts/dispatch-model/</guid><description>&lt;h2 id="三種獨立的訊息分類"&gt;三種獨立的訊息分類&lt;a class="anchor" href="#%e4%b8%89%e7%a8%ae%e7%8d%a8%e7%ab%8b%e7%9a%84%e8%a8%8a%e6%81%af%e5%88%86%e9%a1%9e"&gt;&lt;/a&gt;&lt;/h2&gt;&#10;&lt;p&gt;Davish.Sendr 把訊息合約分成三種，全部透過 &lt;code&gt;ISender&lt;/code&gt; 分派：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;&lt;code&gt;IRequest&lt;/code&gt; / &lt;code&gt;IRequest&amp;lt;TResponse&amp;gt;&lt;/code&gt; — 一般的 request/response。&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;ICommand&lt;/code&gt; / &lt;code&gt;ICommand&amp;lt;TResponse&amp;gt;&lt;/code&gt; — 明確的 CQRS command 合約。&lt;/li&gt;&#10;&lt;li&gt;&lt;code&gt;IQuery&amp;lt;TResponse&amp;gt;&lt;/code&gt; — 明確的 CQRS query 合約。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;&lt;code&gt;ICommand&lt;/code&gt;/&lt;code&gt;IQuery&lt;/code&gt; 與 &lt;code&gt;IRequest&lt;/code&gt; 互相獨立：command 的 handler 實作 &lt;code&gt;ICommandHandler&lt;/code&gt;，&#10;不是 &lt;code&gt;IRequestHandler&lt;/code&gt;。每一種都有自己的 handler 介面、&lt;code&gt;ISender.SendAsync&lt;/code&gt; 多載、&#10;註冊方法（&lt;code&gt;AddRequestHandler&lt;/code&gt;/&lt;code&gt;AddCommandHandler&lt;/code&gt;/&lt;code&gt;AddQueryHandler&lt;/code&gt;），以及 decorator&#10;介面。在呼叫端，&lt;code&gt;ISender.SendAsync&lt;/code&gt; 會依引數的靜態型別自動選對多載，呼叫端不需要知道&#10;某個訊息屬於哪一種。&lt;/p&gt;&#10;&lt;p&gt;&lt;code&gt;IStreamRequest&amp;lt;TResponse&amp;gt;&lt;/code&gt; / &lt;code&gt;IStreamRequestHandler&amp;lt;TRequest, TResponse&amp;gt;&lt;/code&gt; 是第四種，&#10;透過 &lt;code&gt;IStreamSender&lt;/code&gt;（&lt;code&gt;ISender&lt;/code&gt; 也實作了這個介面）分派，回傳的是&#10;&lt;code&gt;IAsyncEnumerable&amp;lt;TResponse&amp;gt;&lt;/code&gt;，而不是 &lt;code&gt;Task&lt;/code&gt;/&lt;code&gt;Task&amp;lt;TResponse&amp;gt;&lt;/code&gt;。&lt;/p&gt;&#10;&lt;p&gt;四種放在一起看：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;"&gt;&lt;code class="language-csharp" data-lang="csharp"&gt;&lt;span style="display:flex;"&gt;&lt;span&gt;&lt;span style="color:#66d9ef"&gt;public&lt;/span&gt; &lt;span style="color:#66d9ef"&gt;sealed&lt;/span&gt; &lt;span style="color:#66d9ef"&gt;record&lt;/span&gt; &lt;span style="color:#a6e22e"&gt;CreateOrder&lt;/span&gt;(Guid Id) : IRequest; &lt;span style="color:#75715e"&gt;// 無回應值&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span style="display:flex;"&gt;&lt;span&gt;&lt;span style="color:#66d9ef"&gt;public&lt;/span&gt; &lt;span style="color:#66d9ef"&gt;sealed&lt;/span&gt; &lt;span style="color:#66d9ef"&gt;record&lt;/span&gt; &lt;span style="color:#a6e22e"&gt;PlaceOrder&lt;/span&gt;(Guid Id) : ICommand; &lt;span style="color:#75715e"&gt;// 無回應值，CQRS&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span style="display:flex;"&gt;&lt;span&gt;&lt;span style="color:#66d9ef"&gt;public&lt;/span&gt; &lt;span style="color:#66d9ef"&gt;sealed&lt;/span&gt; &lt;span style="color:#66d9ef"&gt;record&lt;/span&gt; &lt;span style="color:#a6e22e"&gt;GetOrder&lt;/span&gt;(Guid Id) : IQuery&amp;lt;OrderDto&amp;gt;; &lt;span style="color:#75715e"&gt;// CQRS，有回應值&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span style="display:flex;"&gt;&lt;span&gt;&lt;span style="color:#66d9ef"&gt;public&lt;/span&gt; &lt;span style="color:#66d9ef"&gt;sealed&lt;/span&gt; &lt;span style="color:#66d9ef"&gt;record&lt;/span&gt; &lt;span style="color:#a6e22e"&gt;ListOrders&lt;/span&gt; : IStreamRequest&amp;lt;OrderDto&amp;gt;; &lt;span style="color:#75715e"&gt;// async stream&lt;/span&gt;&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;h2 id="每個-requestresponse-組合只能有一個-handler"&gt;每個 request/response 組合只能有一個 handler&lt;a class="anchor" href="#%e6%af%8f%e5%80%8b-requestresponse-%e7%b5%84%e5%90%88%e5%8f%aa%e8%83%bd%e6%9c%89%e4%b8%80%e5%80%8b-handler"&gt;&lt;/a&gt;&lt;/h2&gt;&#10;&lt;p&gt;&lt;code&gt;IRequest&lt;/code&gt;、&lt;code&gt;ICommand&lt;/code&gt;、&lt;code&gt;IQuery&lt;/code&gt;、&lt;code&gt;IStreamRequest&lt;/code&gt; 這四種，每個 request 型別（對於&#10;泛型形式，則是每個 request/response 型別組合）都只允許註冊恰好一個 handler。為同一組合&#10;註冊第二個 handler，會在註冊時就丟出 &lt;code&gt;InvalidOperationException&lt;/code&gt;。分派一個沒有註冊&#10;handler 的 request，同樣會丟出 &lt;code&gt;InvalidOperationException&lt;/code&gt;。詳細訊息見&#10;&lt;a href="https://davidchen617.github.io/Davish.Sendr/zh-tw/reference/exceptions-and-diagnostics/"&gt;例外與診斷&lt;/a&gt;。對 stream 來說，這件事發生在&#10;開始列舉（enumerate）時，而不是呼叫 &lt;code&gt;SendStream&lt;/code&gt; 時，因為處理本身就是從列舉開始才啟動&#10;（見下方說明）。&lt;/p&gt;</description></item><item><title>Decorator pipeline</title><link>https://davidchen617.github.io/Davish.Sendr/zh-tw/concepts/decorator-pipeline/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://davidchen617.github.io/Davish.Sendr/zh-tw/concepts/decorator-pipeline/</guid><description>&lt;p&gt;Decorator 是一個非泛型的 pipeline 行為，用來包裝 handler 的執行，像是記錄&#10;（logging）、交易（transaction）、驗證等橫切關注點。「非泛型」的意思是：一個&#10;decorator 類別可以包裝任意數量、彼此無關的 request/command/query/stream/notification&#10;型別，這點跟 handler 不同：handler 是針對某一個特定訊息型別寫的。&lt;/p&gt;&#10;&lt;h2 id="每種訊息各自一個介面外加一個有回應值的變體"&gt;每種訊息各自一個介面，外加一個有回應值的變體&lt;a class="anchor" href="#%e6%af%8f%e7%a8%ae%e8%a8%8a%e6%81%af%e5%90%84%e8%87%aa%e4%b8%80%e5%80%8b%e4%bb%8b%e9%9d%a2%e5%a4%96%e5%8a%a0%e4%b8%80%e5%80%8b%e6%9c%89%e5%9b%9e%e6%87%89%e5%80%bc%e7%9a%84%e8%ae%8a%e9%ab%94"&gt;&lt;/a&gt;&lt;/h2&gt;&#10;&lt;table&gt;&#10;&#9;&lt;thead&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;訊息種類&lt;/th&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;th&gt;Decorator 介面&lt;/th&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/thead&gt;&#10;&#9;&lt;tbody&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;IRequest&lt;/code&gt;（無回應值）&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;IRequestDecorator&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;IRequest&amp;lt;TResponse&amp;gt;&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;IRequestDecorator.WithResponse&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;ICommand&lt;/code&gt;（無回應值）&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;ICommandDecorator&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;ICommand&amp;lt;TResponse&amp;gt;&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;ICommandDecorator.WithResponse&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;IQuery&amp;lt;TResponse&amp;gt;&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;IQueryDecorator&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;IStreamRequest&amp;lt;TResponse&amp;gt;&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;IStreamRequestDecorator&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&#9;&#9;&lt;tr&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;INotification&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&#9;&#9;&lt;td&gt;&lt;code&gt;INotificationDecorator&lt;/code&gt;&lt;/td&gt;&#10;&#9;&#9;&#9;&lt;/tr&gt;&#10;&#9;&lt;/tbody&gt;&#10;&lt;/table&gt;&#10;&lt;p&gt;一個類別可以同時實作某一種訊息的無回應值版本與 &lt;code&gt;WithResponse&lt;/code&gt; 版本（README 裡的&#10;&lt;code&gt;LoggingDecorator&lt;/code&gt; 範例就同時實作了 &lt;code&gt;IRequestDecorator&lt;/code&gt; 與&#10;&lt;code&gt;IRequestDecorator.WithResponse&lt;/code&gt;），讓一個 decorator 就能包裝這種訊息的所有形式。&lt;/p&gt;&#10;&lt;p&gt;以 &lt;code&gt;IRequestDecorator&lt;/code&gt; 為例，介面本身不是泛型，但 &lt;code&gt;HandleAsync&lt;/code&gt; 方法是泛型的，這就是&#10;一個 decorator 能包裝任意 request 型別的原因：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;"&gt;&lt;code class="language-csharp" data-lang="csharp"&gt;&lt;span style="display:flex;"&gt;&lt;span&gt;&lt;span style="color:#66d9ef"&gt;public&lt;/span&gt; &lt;span style="color:#66d9ef"&gt;interface&lt;/span&gt; &lt;span style="color:#a6e22e"&gt;IRequestDecorator&lt;/span&gt;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span style="display:flex;"&gt;&lt;span&gt;{&#10;&lt;/span&gt;&lt;/span&gt;&lt;span style="display:flex;"&gt;&lt;span&gt; Task HandleAsync&amp;lt;TRequest&amp;gt;(TRequest request, RequestHandlerDelegate next,&#10;&lt;/span&gt;&lt;/span&gt;&lt;span style="display:flex;"&gt;&lt;span&gt; CancellationToken cancellationToken) &lt;span style="color:#66d9ef"&gt;where&lt;/span&gt; TRequest : IRequest;&#10;&lt;/span&gt;&lt;/span&gt;&lt;span style="display:flex;"&gt;&lt;span&gt;}&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;h2 id="順序依宣告順序由外到內"&gt;順序：依宣告順序，由外到內&lt;a class="anchor" href="#%e9%a0%86%e5%ba%8f%e4%be%9d%e5%ae%a3%e5%91%8a%e9%a0%86%e5%ba%8f%e7%94%b1%e5%a4%96%e5%88%b0%e5%85%a7"&gt;&lt;/a&gt;&lt;/h2&gt;&#10;&lt;p&gt;無論是透過 &lt;code&gt;x.Decorator.With&amp;lt;T&amp;gt;()&lt;/code&gt;（手動註冊），還是 &lt;code&gt;[DecorateWith&amp;lt;T1, T2, ...&amp;gt;]&lt;/code&gt;&#10;（產生出來的註冊），把 decorator 附加到 handler 上時，第一個列出的就是最外層，會最先&#10;執行、最後結束。之後每一個都巢狀包在前一個裡面。&lt;/p&gt;</description></item><item><title>Notification 模型</title><link>https://davidchen617.github.io/Davish.Sendr/zh-tw/concepts/notification-model/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://davidchen617.github.io/Davish.Sendr/zh-tw/concepts/notification-model/</guid><description>&lt;h2 id="零個或多個-handler分成兩個群組"&gt;零個或多個 handler，分成兩個群組&lt;a class="anchor" href="#%e9%9b%b6%e5%80%8b%e6%88%96%e5%a4%9a%e5%80%8b-handler%e5%88%86%e6%88%90%e5%85%a9%e5%80%8b%e7%be%a4%e7%b5%84"&gt;&lt;/a&gt;&lt;/h2&gt;&#10;&lt;p&gt;跟 request/command/query（恰好一個 handler）不同，&lt;code&gt;INotification&lt;/code&gt; 可以有任意數量的&#10;handler，包括零個。若 &lt;code&gt;IPublisher.PublishAsync&lt;/code&gt; 發佈的 notification 型別沒有任何已註冊&#10;的 handler，這就是一個 no-op（什麼都不會發生）。&lt;/p&gt;&#10;&lt;p&gt;某個 notification 型別的 handler 會被組織成兩個命名群組：&lt;/p&gt;&#10;&lt;ul&gt;&#10;&lt;li&gt;&lt;strong&gt;Sequence（序列）&lt;/strong&gt; — 依註冊順序，一次執行一個 handler。某個 handler 丟出例外，&#10;不會阻止 Sequence 群組裡剩下的 handler 繼續執行。&lt;/li&gt;&#10;&lt;li&gt;&lt;strong&gt;Parallel（平行）&lt;/strong&gt; — 群組內所有 handler 同時啟動。&lt;/li&gt;&#10;&lt;/ul&gt;&#10;&lt;p&gt;Sequence 群組與 Parallel 群組彼此是&lt;strong&gt;同時&lt;/strong&gt;執行的。Parallel 的 handler 不會等&#10;Sequence 群組跑完才開始，反過來也一樣：&lt;/p&gt;&#10;&lt;pre class="mermaid"&gt;sequenceDiagram&#10; participant Caller&#10; participant Sequence as Sequence 群組&#10; participant Parallel as Parallel 群組&#10; par Sequence（依序執行）&#10; Caller-&amp;gt;&amp;gt;Sequence: Handler 1&#10; Sequence-&amp;gt;&amp;gt;Sequence: Handler 2&#10; and Parallel（同時啟動）&#10; Caller-&amp;gt;&amp;gt;Parallel: Handler 3&#10; Caller-&amp;gt;&amp;gt;Parallel: Handler 4&#10; end&#10; Sequence--&amp;gt;&amp;gt;Caller: 完成&#10; Parallel--&amp;gt;&amp;gt;Caller: 完成&lt;/pre&gt;&lt;p&gt;&lt;code&gt;AddNotificationHandler&amp;lt;TNotification&amp;gt;&lt;/code&gt; 對同一個 notification 型別只能呼叫一次，該&#10;型別所有的 handler 都要在那一次呼叫裡一起宣告，這樣 Sequence 的順序才會一眼可見。&#10;第二次呼叫會丟出例外。跟這個函式庫其他地方的 handler 註冊一樣，設定會被立即擷取下來；&#10;之後修改傳給 &lt;code&gt;configure&lt;/code&gt; 的物件不會有任何效果。&lt;/p&gt;</description></item><item><title>編譯期發現</title><link>https://davidchen617.github.io/Davish.Sendr/zh-tw/concepts/compile-time-discovery/</link><pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate><guid>https://davidchen617.github.io/Davish.Sendr/zh-tw/concepts/compile-time-discovery/</guid><description>&lt;p&gt;&lt;code&gt;Davish.Sendr.Generators&lt;/code&gt; 是一個 Roslyn incremental source generator。它會在編譯期發現&#10;handler 的實作，並產生出 reflection-free 的 &lt;code&gt;ISender&lt;/code&gt;/&lt;code&gt;IStreamSender&lt;/code&gt;（以及另外，給&#10;notification 用的 reflection-free &lt;code&gt;IPublisher&lt;/code&gt;），同時避開執行期 assembly 掃描與&#10;反射式呼叫這兩件事。手動註冊（見&lt;a href="https://davidchen617.github.io/Davish.Sendr/zh-tw/concepts/dispatch-model/"&gt;分派模型&lt;/a&gt;）雖然也不會掃描&#10;assembly，但在分派時仍是以反射方式解析並呼叫 handler；source generator 進一步把這個&#10;反射也拿掉了。&lt;/p&gt;&#10;&lt;h2 id="如何啟用"&gt;如何啟用&lt;a class="anchor" href="#%e5%a6%82%e4%bd%95%e5%95%9f%e7%94%a8"&gt;&lt;/a&gt;&lt;/h2&gt;&#10;&lt;p&gt;&lt;code&gt;AddSendr(o =&amp;gt; o.UseGenerators())&lt;/code&gt; 會安裝產生出來的 sender；單純呼叫 &lt;code&gt;AddSendr()&lt;/code&gt; 則&#10;維持預設的反射式 sender。這兩者互斥，一旦 &lt;code&gt;UseGenerators()&lt;/code&gt; 生效，手動呼叫的&#10;&lt;code&gt;AddRequestHandler&lt;/code&gt;/&lt;code&gt;AddCommandHandler&lt;/code&gt;/&lt;code&gt;AddQueryHandler&lt;/code&gt;/&lt;code&gt;AddStreamRequestHandler&lt;/code&gt; 就不會&#10;擴充產生出來的分派表。Notification 這邊也是同樣的關係，獨立運作：透過&#10;&lt;code&gt;AddSendrNotification(o =&amp;gt; o.UseGenerators())&lt;/code&gt;。&lt;/p&gt;&#10;&lt;p&gt;分派表是以訊息型別、以及（若適用）回應型別為 key 產生的字典。&lt;/p&gt;&#10;&lt;h2 id="發現的範圍"&gt;發現的範圍&lt;a class="anchor" href="#%e7%99%bc%e7%8f%be%e7%9a%84%e7%af%84%e5%9c%8d"&gt;&lt;/a&gt;&lt;/h2&gt;&#10;&lt;p&gt;預設情況下，source generator 只會發現呼叫 &lt;code&gt;UseGenerators()&lt;/code&gt; 那個專案自己宣告的&#10;handler。如果 handler 位於某個被參照的專案或 NuGet 套件裡，需要明確宣告：&lt;/p&gt;&#10;&lt;div class="highlight"&gt;&lt;pre tabindex="0" style="color:#f8f8f2;background-color:#272822;-moz-tab-size:4;-o-tab-size:4;tab-size:4;-webkit-text-size-adjust:none;"&gt;&lt;code class="language-csharp" data-lang="csharp"&gt;&lt;span style="display:flex;"&gt;&lt;span&gt;o.UseGenerators(g =&amp;gt; g.IncludeAssemblyOf&amp;lt;ApplicationAssemblyMarker&amp;gt;());&lt;/span&gt;&lt;/span&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/div&gt;&lt;p&gt;&lt;code&gt;ApplicationAssemblyMarker&lt;/code&gt; 可以是那個 assembly 裡任何一個型別，它不需要實作任何特定&#10;介面，只是用來識別要納入的 assembly。&lt;code&gt;IncludeAssemblyOf&amp;lt;TMarker&amp;gt;()&lt;/code&gt; 可以串接，納入不只&#10;一個 assembly。這裡的「發現」只包含以這種方式指名的 assembly，不包含它們的間接依賴。&#10;目前這個專案永遠會自動被包含，所以再指名自己的 assembly 一次並不會出錯。&lt;/p&gt;</description></item></channel></rss>