石頭閒語 :: Programming

網頁UI元件 - LimitedCheckbox，複選但有限項目的表單元件

Wed, 18 Jun 2025 00:00:00 +0000

當網頁表單需要提供使用者可複選的選項時，我們會用 Select (配上 multiple) 或 Checkbox 元件。但若想進一步限制可勾選的項目數量，例如五項中最多選三項又或是最少選兩項，則目前的內建行為做不到。我們要自己寫程式控制。

我根據我碰到的需求情境，設計了一個允許使用者複選但有限項目的表單元件。因為這個元件是基於 Checkbox ，所以取名 LimitedCheckbox。

我不用 Select 設計這個複選元件的原因，在於 Select 需要配合鍵盤按住 ctrl 或 shift 才可複選。但現在很多人不知道這種鍵盤搭配滑鼠的操作技巧。隨著成長於手機世代的使用者愈來愈多，不知道的人會更多。而 Checkbox 的操作方式則符合現代使用者的「日常經驗」，所以選它。

LimitedCheckbox 的設計與運作

首先，要將 Checkbox 包進 Fieldset 。或說用 Fieldset 劃分 Checkbox 群組。

Select 元件會將選項包起來形成群組。但 Checkbox 元件本身是獨立的，基本上各不相干。若要滿足可以五項中最多選三項，又或是最少選二項此類設計需求，我就需要把原本獨立的 Checkbox 分組。分了組，我的程式才能做出「這五個是同組，限制最多選三個」或者「這幾個是一組，至少要勾兩個」等等判斷。我用 Fieldset 做這件事。

Fieldset 用 id 對應 Checkbox 的 name。並自定 maxlenth 和 minlength 兩個屬性。 maxlength 定義最多勾選項目的限制條件。minlength 定義最少勾選項目的限制條件。兩個限制條件可同時存在。
呼叫 LimitedCheckbox.initial() 初始化。它會傾聽 document.change 和 document.submit 事件。
當使用者勾選項目後，呼叫 LimitedCheckbox.updateStatus() 檢查 maxlength 限制。它根據 Fieldset 的 maxlength 決定同組 Checkbox 元件的狀態。當已勾選的項目數量等於 maxlength 時，就變更未勾選 Checkbox 屬性為 disabled，讓使用者不能勾選更多項目。
使用者送出表單時，呼叫 LimitedCheckbox.checkValidity() 檢查 minlength 限制。若已勾選的項目數量少於 minlength 便中斷送出動作，並觸發 invalid 事件。

LimitedCheckbox 的源碼: limited-checkbox.js」。

HTML 範例

說到 Fieldset，這是一個幾乎被人遺忘的東西。但它確實是 HTML 規範中，用於表單元素分組的東西。然而它除了一個框起來的視覺效果之外便沒有其他用處，致使它長期被遺忘。

例如我一開始問 Copilot AI 給個可多選項目的範例時，連 Copilot 都沒有用 Fieldset 分組。並且 Copilot 把所有複選限制條件都直接寫在 JavaScript 程式內，而不是透過元件屬性注入程式。這使得程式碼難以重用。

我思考之後，決定用 Fieldset 分組，並把複選限制條件綁在 Fieldset 的屬性上。我的程式去讀 Fieldset 的屬性，就可得知每個組別的最多可勾項目和最少可勾項目的限制條件。

按照上述設計要點， LimitedCheckbox 的 HTML 範例如下。

<fieldset id="A組[]" maxlength="3">
    <legend>A組：最多三項</legend>

    <input type="checkbox" id="A組-項目1" name="A組[]" value="A001" form="form">
    <label for="A組-項目1">A項目1</label><br>

    <input type="checkbox" id="A組-項目2" name="A組[]" value="A002" form="form">
    <label for="A組-項目2">A項目2</label><br>

    <input type="checkbox" id="A組-項目3" name="A組[]" value="A003" form="form">
    <label for="A組-項目3">A項目3</label><br>

    <input type="checkbox" id="A組-項目4" name="A組[]" value="A004" form="form">
    <label for="A組-項目4">A項目4</label><br>

    <input type="checkbox" id="A組-項目5" name="A組[]" value="A005" form="form">
    <label for="A組-項目5">A項目5</label><br>
</fieldset>

更多範例請見範例網頁源碼」。

我的後端是 PHP。回送給 PHP 的表單項目若是複數資料，那麼的 name 的內容必須後綴 `[]` 才會解析成包含複數資料的陣列。

JavaScript 的部份

網頁載入後，需要呼叫 LimitedCheckbox.initial() 啟用 LimitedCheckbox。

LimitedCheckbox.initial() 有兩個可選的回呼函數參數，讓設計者處理不合限制時的外觀效果。

valid_callback - 當一組複選元件的勾選結果符合限制時，呼叫此函數。
invalid_callback - 當一組複選元件的勾選結果不符合限制時，呼叫此函數。

這兩個參數對應屬性 LimitedCheckbox.validCallback 和 LimitedCheckbox.invalidCallback。

基本上，只需要寫一行 LimitedCheckbox.initial() 就行了。但實際上，還是會指定 validCallback 和 invalidCallback 處理外觀效果。畢竟我們不能讓使用者看不出為什麼表單送不出去。

啟用 LimitedCheckbox 的範例如下:

<script>
window.addEventListener('load', () => {
    LimitedCheckbox.initial(
        valid_set   => valid_set.querySelector('legend').classList.remove('bg-warning'),
        invalid_set => invalid_set.querySelector('legend').classList.add('bg-warning')
    );
    // LimitedCheckbox.validCallback =   valid_set   => valid_set.querySelector('legend').classList.remove('bg-warning');
    // LimitedCheckbox.invalidCallback = invalid_set => invalid_set.querySelector('legend').classList.add('bg-warning');

    document.addEventListener('invalid', ev => {
        console.log('invalid event', ev.target, ev.message);
    });

});
</script>

不合限制時，將複選表單元件組的標題 (legend) 背景色變為 bg-warning。合於限制時，移除背景色。

不指定 invalidCallback 時，也可以透過 invalid 事件處理不合限制的狀況。

雖然實作中出現了 checkValidity() 方法和 invalid 事件，但我並沒有實作整套 Constraint Validation API。也還不想按照 Web Component 訂一個新的網頁元件。

因為整套弄起來太複雜，超出我需要的功能。我用不到的功能，就不會使用測試。不測試，就不能保證這些功能的程式碼的可用性。那還是別寫了。

網頁UI元件 - 如何使用新式UI Dialog 和 Modal

Sat, 14 Jun 2025 00:00:00 +0000

Dialog 是 WHATWG 規範的 HTML 對話框元件。只要各家瀏覽器按照規範內容實作，就可以保證在不同瀏覽器與前端工具之間仍有相同的行為。按 Mozilla MDN 文件所述，在 2022 年 3 月之後的瀏覽器皆已實作此元件。在此之前，這類 UI 元件是由前端工具 - 如 bootstrap - 利用 CSS 和 JavaScript 自行設計。但不同前端工具定義的對話框行為並不相同。

注意，本文使用「對話框」一詞時，是一般概念。使用 Dialog 一詞時，專指 HTML 規範的對話框元件。

專案開發者手上的舊專案仍可繼續使用前端工具自定的對話框元件。但新建專案，則建議使用 Dialog 元件。因為它有標準化的好處。 A 前端工具的對話框元件和 B 前端工具的對話框元件一定不同，如果你們中途變更前端工具，那就要修改對話框元件的程式碼。而 Dialog 不與前端工具綁定，不受前端工具更迭影響。

Dialog 標準行為

具有方法: show(), showModal() 和 close()。事件: close。屬性: open、returnValue。
預設不顯現，即屬性 open 為 false。
有兩種行為型態: 一般型態和互動型態 (Modal)。這兩種行為區別是由顯現方法決定。呼叫 show() 方法顯現時，為一般型態；呼叫 showModal() 方法則為互動型態。
一般型態只會浮現在畫面上層，但不阻礙使用者和其他元件互動，使用者可以忽視它。
互動型態 (Modal) 則強制使用者必須與其互動，不能忽視它。互動型態 Dialog 顯現時會阻擋使用者和其他元件互動，使用者必須優先處理 Dialog 內容並關閉它。
一般型態 Dialog 顯現時只會水平置中於可視區域。而互動型態 Dialog 則是水平與垂直置中。
Dialog 可透過其內部表單 (Form) 關閉。透過表單關閉時，觸發 close 事件，並改變 returnValue 屬性之值。
有標準的鍵盤互動方式。互動型態 Dialog 可以按鍵盤的 Esc 鍵關閉它。

基本設計組合

Dialog 的 HTML 基本內容通常搭配一個觸發其顯現的按鈕。其內部則安排一個表單與使用者互動，例如讓使用者選擇動作。內部表單的 method 應為 dialog，安排至少一個呈送按鈕 (submit)。點擊呈送按鈕後關閉對話框，依呈送按鈕的 value 設定 Dialog 的 returnValue 屬性，並觸發 close 事件。

範例如下:

<button onclick="document.getElementById('myDialog1').show()">
    Open Dialog
</button>

<dialog id="myDialog1" onclose="alert(`點擊 ${this.returnValue}`)">
    <div>
        Hello Dialog!
    </div>
    <hr>
    <div>
        <form method="dialog">
            <button type="submit" value="Yes">
                是
            </button>
            <button type="submit" value="No">
                否
            </button>
        </form>
    </div>
</dialog>

Dialog 外觀

設計者可用 CSS 宣告 Dialog 外觀。主要設計 Dialog 的視窗寬度和邊框樣式。瀏覽器會按 HTML 規範將 Dialog 置中，所以不必宣告 Dialog 位置。

對於互動型態 Dialog，則有虛擬元素 backdrop 可設計背景外觀 (被其阻擋的畫面區域)。通常我們會宣告背景色和透明度。

CSS 範例如下:

<style>
dialog {
    min-width: 25%;
    border: solid 3px #fd7e14;
    padding: 1.5rem;
    border-radius: 10px;
}

dialog::backdrop {
    background: rgba(0, 0, 0, 0.5);
    /* backdrop-filter: blur(1px); */
}
</style>

外觀如下圖:

打造自己的 Dialog

接下來我要結合 HTML 元件自定屬性和 JavaScript 配合，簡化 dialog 的程式編寫工作。

自定屬性:

rock-dialog: 對應 Dialog 的 id。點擊有此屬性的元件便呼叫 show() 顯現指定的 Dialog。
rock-dialog-modal: 若有此屬性，則呼叫 showModal() 顯現互動型態 Dialog。
rock-dialog-message: 此值將傳給 Dialog，為其顯示的訊息內容。
rock-dialog-label: 如果 Dialog 內部有一個連結元件 (anchor/a)，此屬性將是該連結的顯示文字。
rock-dialog-action: 如果 Dialog 內部有一個連結元件 (anchor/a)，此屬性將是該連結的跳轉 URL。

自定類別:

dialog-close: 點擊任何位在 Dialog 內部且有 dialog-close 類別的元件，都可關閉其所在的 Dialog。

下列為實作這些內容的 JavaScript 程式碼:

<script>

function confirmDialogChangeContent(trigger, dialog)
{
    const message = dialog.querySelector('.dialog-body');
    if (message == null) {
        return;
    }

    message.innerHTML = decodeURIComponent(
        trigger.getAttribute('rock-dialog-message'));

    const link_btn = dialog.querySelector('a');
    
    link_btn.innerText = trigger.getAttribute('rock-dialog-label');
    link_btn.href = trigger.getAttribute('rock-dialog-action');
}

window.addEventListener('click', ev => {
    // 點擊任何具有 rock-dialog 屬性的元件，都可顯現指定的 Dialog
    // 若點擊的元件同時帶有 rock-dialog-modal 屬性， Dialog 將以 modal 模式顯現。
    const dialogId = ev.target.getAttribute('rock-dialog');
    if (dialogId) {
        const dialog = document.getElementById(dialogId);
        if (dialog.open) {
            return;
        }
        
        confirmDialogChangeContent(ev.target, dialog);

        if (ev.target.getAttribute('rock-dialog-modal') != null) {
            dialog.showModal();
        }
        else {
            dialog.show();
        }
        return;
    }

    // 點擊任何具有 dialog-close 類別的元件，都可關閉其所在的 Dialog
    // PS. 這個元件必須位在 Dialog 內部
    if (ev.target.classList.contains('dialog-close')) {
        ev.target.closest('dialog').close();
    }
});
</script>

以下為自訂內容的使用範例。此範例也用了 bootstrap5 設計元件外觀。

<button rock-dialog="myDialog1" class="btn btn-primary">Open Dialog</button>

<button rock-dialog="myDialog1" rock-dialog-modal class="btn btn-primary">Open Modal</button>

<dialog id="myDialog1">
    <div>
        <p>這是對話框。</p>
        <p>利用內部表單的 submit 按鈕關閉。表單的 method 必須指定 "dialog"。</p>
    </div>

    <div class="d-flex justify-content-center gap-2 m-3">
        <form method="dialog">
            <button type="submit" class="btn btn-primary">關閉</button>
        </form>
    </div>
</dialog>

<button rock-dialog="confirmDialog" rock-dialog-modal class="btn btn-warning"
        rock-dialog-message="前往石頭閒語"
        rock-dialog-label="跳吧"
        rock-dialog-action="https://rocksaying.tw/">
    跳到石頭閒語
</button>

<dialog id="confirmDialog">
    <div class="dialog-body">
        $message
    </div>
    
    <hr>
    <div class="d-flex justify-content-center gap-2 m-3">
        <a href="$action" class="btn btn-primary">
            $label
        </a>

        <button class="btn btn-secondary dialog-close">
            關閉(close())
        </button>
        
        <form method="dialog">
            <button class="btn btn-secondary">
                關閉(form)
            </button>
        </form>
    </div>
</dialog>

此例的執行效果如下圖:

專案開發者手上的舊專案仍可繼續使用前端工具自定的對話框元件。但新建專案，則建議使用 Dialog 元件。因為它有標準化的好處。不與前端工具綁定，不受前端工具更迭影響。

網頁UI元件 - NumberInputElement，自訂增減值按鈕，以及用滑鼠滾輪修改數字

Sun, 23 Feb 2025 00:00:00 +0000

當設計師碰到限定輸入數值的輸入欄位時，可以用 NumberInputElement 網頁 UI 元件讓輸入框呈現更美觀的增加數值按鈕與減少數值按鈕。這是目前流行的數值輸入形式。

NumberInputElement 元件具備以下特性：

只綁定型態為 number 的 input 控制項 (input type=”number”)。
加入使用滑鼠滾輪改變數值的行為。上滾增值，下滾減值。
擴充 label 控制項的行為，使其具備對關聯控制項的增值行為或減值行為。使用 type 屬性定義點擊 label 時的行為， inc 表示增值，dec 表示減值。
若不想用 label 改變 input 控制項的值，也可自行定義控制項的選擇器。例如用 button 控制項處理增值或減值。
增值與減值行為都會參考 input 控制項的 max, min, step 三項標準屬性。

這個元件不會主動在 input 控制項旁邊增加控制按鈕，而是交給設計師決定。如果設計師沒有放上代表增值或減值的按鈕／控制項，將只有滑鼠滾輪的擴充行為生效。

NumberInputElement 儲放在我的 non-jquery-ui 源碼庫: 「取得 NumberInputElement」。

沒想到時至今日還有機會寫這種網頁 UI 。我本來以為是我目前用的前端框架太輕量簡化，所以沒有這種 UI。但網路上搜了一遍，才發現功能更複雜的前端框架也經常忽視這種 UI 的使用需求。設計師往往要自己額外去找 UI 元件拼湊。

先說明一點，在手機或平板等觸控式操作環境中，瀏覽器已經針對數值型態的 input 控制項提供明顯特化的輸入介面，讓使用者輕鬆輸入數字。所以在這類環境下，不需要使用這個 UI 元件。但這個元件的擴充內容也不會干涉內建行為。

在 PC 環境下，瀏覽器似乎就沒有那麼用心了。像 Edge 或 Firefox 的電腦版碰到數值型態的 input 控制項，只是在輸入框邊緣加上兩個很小的上下箭頭 (如範例圖所示)，讓只用滑鼠的使用者點擊箭頭調整數值。但這兩個小箭頭實在小到很難點擊，所以主流的設計方式就是自己加兩個更大的按鈕來做這件事。

喔，對了。針對鍵盤使用者，瀏覽器電腦版還為數值型態 input 控制項加了按上下方向鍵調整數值的操作行為。既然可以按方向鍵調整數值，那是不是也該讓滑鼠滾輪這麼做？

NumberInputElement 元件就要滿足上述兩項需求。

滑鼠滾輪調整輸入數值

首先對應觸控式操作環境使用上下滑動調整數值的操作習慣，必須加上滾動滑鼠滾輪調整數值的操作行為。這一點只需要傾聴代表滑鼠滾輪滾動的 wheel 事件，然後根據 deltaY 判斷滾輪是上滾或下滾調整數值。上滾增值，下滾減值。程式碼實作內容摘錄於下：

    document.querySelectorAll('input[type="number"]').forEach(elm => {
        elm.addEventListener('wheel', NumberInputElement.wheelHandler);
    });
    
    static wheelHandler(ev)
    {
        ev.preventDefault();
        const input = ev.target;
        const delta = ev.deltaY;
        if (delta > 0) {
            // console.log('wheel down');
            NumberInputElement.change(input, 'dec');
        } else {
            // console.log('wheel up');
            NumberInputElement.change(input, 'inc');
        }
    }

增加數值按鈕與減少數值按鈕

至於增加兩個大按鈕分別負責增值與減值的部份，我的設計考量是讓設計師決定按鈕外觀和位置，而不是 NumberInputElement 自己生成按鈕。設計師只要讓 NumberInputElement 知道是哪些按鈕，然後 NumberInputElement 負責綁定增值和減值的擴充行為。

為了讓 UI 行為一致，我決定用 label 作為增值按鈕與減值按鈕的基底，而不用 button。因為增值按鈕與減值按鈕要像內建的兩個小箭頭一樣關聯 input 控制項，而且點擊時要改變輸入焦點到 input 控制項(輸入框內)，而不是把焦點放在按鈕上。label 本身就具有這些特性。

Label 的 for 標準屬性可以指定關聯控制項。我再另外添加 type 屬性指定 label 負責的調整行為。若 type 為 inc 表示增值，dec 表示減值。

具體來說，就是像下列的 HTML 碼：

<label for="input1">數值欄位: </label>
<label for="input1" type="inc">➕</label>
<input type="number" id="input1" max="10" min="-15">
<label for="input1" type="Dec">➖</label>

這個 HTML 就是範例圖呈現的第一組數值型態輸入元件。

第一個 label 沒有添加 type 屬性，所以它只觸發原本的行為，亦即改變輸入焦點到輸入框。

第二個 label 添加了 type=”inc” 屬性，點擊時除了改變輸入焦點，還會增加數值一步。第三個 label 添加了 type=”dec” 屬性，所以點擊就減少數值一步。一步的量由 input 的標準屬性 step 決定，預設一步為 1 。程式碼實作內容摘錄於下：

    document.querySelectorAll('input[type="number"]').forEach(elm => {
        const labels = document.querySelectorAll(`label[for="${elm.id}"]`);

        // 擴展 label 控制項的行為(若其具有 type 屬性)
        labels.forEach(elm => {
            if (!elm.getAttribute('type')) {
                return;
            }
            // label 的 click 事件觸發兩次 (在 mousedown 與 mouseup 後各一次)
            // 所以看 mouseup ，不看 click
            elm.addEventListener('mouseup', NumberInputElement.labelHandler);
        });
    });
    
    static labelHandler(ev)
    {
        const label = ev.target;
        const labelType = label.getAttribute('type');
        const input = label.control; // 只有 label 控制項有此屬性
        if (!input || !labelType) {
            return;
        }

        NumberInputElement.change(input, labelType);
        input.focus();
    }

不論是 label 的 for 還是 input 的 step, min, max 等屬性，都是 HTML 規範的標準屬性。我的設計思路都是按照 HTML 規範原則擴充操作行為，從而保持 UI 行為一致。

控制項的事件傳遞

在瀏覽器的原始環境下，操作者手動點擊輸入控制項旁的小箭頭改變數值的動作，將會觸發控制項的 input 事件。前端設計師經常會傾聴這個事件，以便處理使用者的輸入內容。

然而透過程式手段改變數值的動作，亦即用 JavaScript 程式碼設置控制項的 value 屬性，則不會觸發控制項的 input 事件。這使前端設計師佈置的 input 事件處理方法不起作用。從擴展元件行為並保持行為一致性的設計原則來看，這算是 BUG 。所以當 NumberInputElement 擴展的操作行為改變控制項的 value 屬性時，也應擲出該控制項的 input 事件，讓其他傾聽此控制項事件的人可以接著處理數值改變的事。

要做到這件事，首先需要產生一個 Event 實例，其事件值為 ‘input’。然後將它交給控制項的 dispatchEvent() 方法，即可派出 input 事件，讓其他處理函數接著做事。程式碼實作內容摘錄於下：

    static change(input, act)
    {

        input.value = computedValue;
        input.dispatchEvent(new Event('input', {bubbles: true}));
    }

開始使用

上述實作內容都已整合在 NumberInputElement。當設計師寫好 HTML 碼之後，只需載入 number-input-element.js ，然後呼叫 NumberInputElement.initial(); 就可生效。

<label for="input1" type="inc">➕</label>
<input id="input1"  type="number" max="10" min="-15">
<label for="input1" type="Dec">➖</label>

<script src="number-input-element.js"></script>

<script>
window.addEventListener('load', function(){
    NumberInputElement.initial();
}, false);
</script>

NumberInputElement 在 Firefox 和 MS Edge 瀏覽器電腦版內完成開發及測試工作。本文範例沒有套用任何 CSS，所以 label, input 或 button 控制項都是預設外觀。設計師應自己套用 bootstrap 這些 CSS 工具，美化外觀。

基本上，我的設計目標到此就實現了。不過說到自訂點擊行為，大家通常都是用 button。所以我又為 NumberInputElement.initial() 加入 labelSelector 函數參數，讓設計師自己決定綁定增值行為與減值行為的控制項。

自訂選擇器

下例混用 label 和 button 設計增值按鈕與減值按鈕。為了突顯自訂性，我還特意讓兩組數值輸入控制項的按鈕位置不一樣。第一組把兩個按鈕分放兩邊，第二組則都放右側。

本例為了讓作為增值按鈕與減值按鈕的 button 控制項被選中，在呼叫 NumberInputElement.initial() 時，傳入了自訂選擇器的 callback 函數參數。

<div>
    <label for="input1">數值欄位: </label>
    <label for="input1" type="inc">➕</label>
    <input type="number" id="input1" max="10" min="-15">
    <label for="input1" type="Dec">➖</label>
</div>
<br/>
<div>
    <input type="number" id="input2">
    <button for="input2" type="dec">➖</button>
    <button for="input2" type="inc">➕</button>
</div>

<script src="number-input-element.js"></script>

<script>
window.addEventListener('load', function(){
    NumberInputElement.initial(id => {
        return document.querySelectorAll(`[for="${id}"]`);
    });
}, false);
</script>

如果設計師不想用 for 屬性指定關聯控制項，而想用別的屬性也行。下例就是用 NumberInputElement.relatedAttribute 屬性指定用 target 屬性名稱。

<div>
    <button target="input3" type="dec">➖</button>
    <input type="number" id="input3">
    <button target="input3" type="inc">➕</button>
</div>

<script src="number-input-element.js"></script>

<script>
window.addEventListener('load', function(){
    NumberInputElement.relatedAttribute = 'target';
    NumberInputElement.initial(id => {
        return document.querySelectorAll(`button[target="${id}"]`);
    });
}, false);
</script>

整合前端框架

目前前端框架的主流設計方式，不是分別在控制項上綁處理函數，而是直接在 document 綁定處理函數，然後在處理函數內根據事件主體判斷分流。

如果設計師要把 NumberInputElement 整合到採用這種設計原則的框架內，則不要呼叫 NumberInputElement.initial()，而須分別使用 NumberInputElement.wheelHandler() 和 NumberInputElement.labelHandler()。

HTML 規範參考

NumberInputElement 儲放在我的 non-jquery-ui 源碼庫: 「取得 NumberInputElement」。

PHP框架 - CommonGateway - 用 URL 重寫規則隱藏 CGF

Sat, 30 Nov 2024 00:00:00 +0000

Common Gateway Framework (CGF) 設計的所有服務 (RESTful API 或網頁) 都是透過主程式 index.php 轉發使用者的請求給控制項。因此正常的 URL 總是會包含 index.php。

但有些客戶並不希望在 URL 中看到 index.php 這個字眼。他們可能想要改善 SEO 的搜尋結果，又或是不想暴露低層的運作軟體。我們可以利用 URL 改寫規則實現此目的。

有些功能龐大的框架會內建一套 URL 規則，例如 Laravel。這類框架請照它們的規則來做。

修改主程式檔名

改變 URL 結構形式最簡單的方式是修改主程式檔名。

CGF 的 URL 結構形式正常如下:

https://your_server/api/index.php/Item
https://your_server/shop/index.php/Item/123

你可以按你的喜好修改 index.php 檔名，這不會影響 CGF 運作。例如你可以改名為 router.php，或者是 main.php。此時你的服務 URL 形式就變成:

https://your_server/api/router.php/Item
https://your_server/shop/main.php/Item/123

若想更進一步隱藏 CGF 主程式，不讓使用者看到 URL 內容中有 index.php 或 main.php。則需要借助網站服務程式的 URL 重寫規則 (rewrite rule)。

URL 重寫規則

這個方法不僅適用 CGF，也適用其他框架。例如 CodeIgniter 框架也用 URL 重寫規則移除 URL 中的 index.php: CodeIgniter URLs。

常見的網站服務程式，如 Apache, Nginx 甚至 IIS，都提供了 URL 重寫規則 (rewrite rule) 功能。但每家的用法不一樣。底下以 Apache 2.4 為例說明 URL 重寫規則。

舉例來說，你想將 RESTful API 的 URL 結構變成 https://your_server/api/Item 。

你可以選擇將 URL 重寫規則寫在 .htaccess。重寫規則如下:

# .htaccess
RewriteEngine on

RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule "(.*)" "index.php/$1" [PT,L]

.htaccess 應該放在 CGF 程式根目錄，和 index.php 在一起。而且你的 Directory 組態至少要設 AllowOverride FileInfo 才能使 .htaccess 生效。

這個 URL 重寫規則使用 PT (Pass through) 旗標， URL 只會在伺服器內部轉換。使用者端不會改變。

.htaccess 用法僅應用於軟體開發與測試階段。基於執行效率的考量，正式運作階段建議將 URL 重寫規則寫在 VirtualHost 或 Directory 區段中。只是寫在 VirtualHost 或 Directory 區段時，要再考慮目錄位置。例如:

<Directory>
    RewriteEngine on

    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteRule "^api/(.*)" "api/index.php/$1" [PT,L]
</Directory>

若你的程式只提供 RESTful API，那你做到這一步就夠了。但若你是用 CGF 設計網站，那你還需要在 Apache 組態中加入環境變數 CGF_REQUEST_ROOT，指示 URL 重寫規則的根點 (root)。

CGF_REQUEST_ROOT

當你用 CGF 設計網站時，勢必要在網頁中提供連結指向不同功能網頁(控制項)。 CGF 為此提供了函數 \cg\html\request_url() 產生控制項的正確 URL。但這個函數是按正常規則產生 URL。也就是 https://your_server/api/index.php/Item 或 https://your_server/shop/main.php/Item/123 這種形式。

當你使用 URL 重寫規則後，就會分出使用者看到的外顯 URL 和伺服器內部轉換後的真實 URL。你必須用環境變數 CGF_REQUEST_ROOT 讓 request_url() 知道外顯 URL 的根點，它才能產生控制項的外顯 URL。未指定 CGF_REQUEST_ROOT 時，cg\request_url() 將產生真實 URL，而不是你想要的。

如果你的外顯 URL 結構像是 https://your_server/shop/Item/123 ，則應設 CGF_REQUEST_ROOT 為 /shop 。

Apache2:

SetEnv CGF_REQUEST_ROOT /shop

Nginx:

fastcgi_param CGF_REQUEST_ROOT /shop

設計說明

CGF 的設計原則是「零組態」。我希望能夠從現有資源中找出 URL 的 root。

使用 apache2 時，符合 rewrite 規則的結果會加上 $_SERVER[‘REDIRECT_URL’] 項目。但 nginx 時沒這項目。查了 CGI 規範，並沒有 REDIRECT_URL。所以這是 Apache2 特有項目。

轉念一想，既然 rewrite 規則必須寫在 web server 的組態中，那乾脆順便在 web server 組態裡加一個自定環境變數 CGF_REQUEST_ROOT，指定 URL 的 root。 PHP 執行時會將環境變數的內容放入 $_SERVER，那麼 CGF 就可以從外部得到這個參數。至少不用修改 index.php 本身。

學習 ECMAScript/JavaScript 6 - Module 在瀏覽器環境的使用說明

Wed, 04 Oct 2023 00:00:00 +0000

JavaScript 的 module (模組) 概念，整體上與其他程式語言沒有差別。但是 JavaScript 主流用途是作為瀏覽器的嵌入式語言，在瀏覽器環境使用 module 就帶來一些特殊的問題。此為本文重點。

本文不會詳細介紹 module (模組) 功能的程式語法。語法細節推薦看 Mozilla 開發者文件的「Modules Guide」。

module 特性

首先，module (模組) 視為獨立的活動空間 (space or scope) 。所以本文會一直用「模組空間」這個稱呼。

JavaScript 的模組空間具有下列特性:

每一個 js 檔案都視為獨立的模組空間。
在 HTML 內的每一段 script type=”module” 標籤區塊，也視為獨立的模組空間。
模組空間的內容預設不公開 (private)。
變數、函式、類別、迭代器等內容，都可以用 export 敘述宣告公開給外界使用 (public)。
要使用其他模組空間的公開內容，必須先用 import 敘述匯入。
export/import 兩語法只能用於模組空間，且必須寫在空間頂層，不能寫在函式與類別內。
模組空間可以存取全域空間的內容，但全域空間不能存取模組空間內容。

第 2 點是瀏覽器環境才有的特性。

我寫了幾組 html 試驗我上面說的特性，並作為本文的程式範例。完整源碼請看「rocksources: javascript-module-example」。

script type 的影響

初學 module (模組) 功能會撞牆的點，就是不知道 script 標籤的 type 屬性值決定你能否用 import/export 敘述。明明都照語法寫 import/export 啊，為什麼瀏覽器會說語法錯誤？ 因為外面沒宣告 type=”module”。早說啊，為什麼不早說？

所以我把這件事放在開頭講。一但知道這件事後， JavaScript 的模組功能用起來就和其他程式語言的模組化功能差不多，毋需多言。

在瀏覽器內，我們透過 HTML 的 script 標籤執行 JavaScript。可以直接在 script 標籤區塊內寫程式碼，也可以透過 src 屬性載入 js 檔案。在過去很長一段時間裡，由於 script 標籤使用的型態內容只有一種，就是 text/javascript ，所以我們通常都省略不寫 type 屬性。然而瀏覽器加入模組功能時，它便要求 script 標籤的 type 屬性指定為 module 的內容才視為模組空間。至於 script type=”text/javascript” 的內容則不屬於任何模組空間。本文為了方便稱呼，這些不在模組空間的內容，都會說它們位在全域空間。

在說明模組空間和全域空間的區分後，接著談實務上有什麼影響。

JavaScript 的模組功能有兩個關鍵字，即 export 和 import。export 負責宣告模組有哪些內容公開給外界用；import 將其他模組的內容匯入本地模組空間。而本文列舉的第 6 點特性強調「export/import 只能在模組空間內使用」。這句話看似沒什麼問題，但其實在瀏覽器環境有些複雜。

我們過去寫的那一堆沒有 type 屬性的 script 標籤內容都算全域空間。由於全域空間不是模組空間，所以不能用 import 敘述，也就不能存取任何模組的內容。

那為每個 script 標籤加上 type=”module” 就行了嗎？

否。每個 script 標籤的模組空間也是各自獨立，所以想把 script type 從 “text/javascript” 直接改成 “module” 也不行。原有的程式如果想要導入模組功能，那一定要大改程式碼的撰寫結構。並非在每一個 script 加個 import xxx 敘述就行了。想在原有的 Web 應用導入模組功能的話，通常第一件事就是在原來的 index.html 內，加一個 script type=”module” 的進入點。

Node.js 也有類似的要求。作為模組的 js 檔案要在 package.json 宣告其 type 為 module；又或者用副檔名 .mjs 表示這是一個模組。不同的 JavaScript 宿體會有不同的要求。

我們來看看實際怎麼寫。

先看沒有模組之前的傳統用法。

<script type="text/javascript">
function abc() {
    console.log("say ABC");
}

// script type 為 text/javascript 的程式碼，不能用 export 敘述
// export { abc };
console.log("abc module loaded");
</script>

要用模組的話，則要指定 type=”module” 。就是要求 JavaScript 解譯器將裡面的內容放在模組空間中處理。同時也自動宣告 strict mode。

<script type="module">
function abc() {
    console.log("say ABC");
}

// script type 為 module 的程式碼，才能用 export 敘述
export { abc };
console.log("abc module loaded");
</script>

上例直接在 script 標籤區塊內寫 export ，但這其實沒有意義。因為這個區塊沒有名字，其他模組不知道怎麼 import 它的內容。

只看 JavaScript 內容的話，這兩個檔案基本沒有差異。但一個不能寫 export ，另一個可以。差一行 export 的原因便是外部宣告的 type 不同。

我們可以把寫在 script 標籤內的程式碼分離出來，另外儲放在單獨的 js 檔案，再用 src 屬性讓瀏覽器載入。但是 script 標籤的 type 屬性依然影響 js 檔案的對待方式。宣告 module 的才能用 export 敘述；未宣告的不行。

傳統載入 js 的方式

傳統用法將程式碼分離到 js 檔案，如下所示：

// abc-script-type-javascript.js
function abc() {
    console.log("say ABC");
}

// 因為載入的 script type 為 text/javascript ，故不能用 export 敘述
// export { abc };
console.log("abc module loaded");

HTML 中用 script src 讓瀏覽器載入它。

<script type="text/javascript" src="modules/abc-script-type-javascript.js">
</script>

<script type="text/javascript">
window.addEventListener('load', _=>{
    abc();
});
</script>

傳統方式，所有程式碼定義的內容都在全域空間。故載入 abc-script-type-javascript.js 後，我們可以在任何地方呼叫 abc()。但因為瀏覽器的載入工作並非同步進行，所以會等 window.load 事件後才呼叫。

範例: index-without-module.html。

用模組的方式

使用模組的話，如下所示：

// abc-script-type-module.js
function abc() {
    console.log("say ABC");
}

// script type 為 module 的程式碼，才能用 export 敘述
export { abc };
console.log("abc module loaded");

導入模組後， HTML 中每個 script type=”module” 標籤的內容都是分別獨立的模組空間。所以這些 script 區塊或 js 檔案內，在呼叫 abc() 之前都得先寫上 import {abc} from './modules/abc-script-type-module.js'。敘述相對路徑時，要加前綴 ./。如下所示：

<script type="module">
import { abc } from './modules/abc-script-type-module.js';

abc();

</script>

範例: index-with-module.html。

從上圖的網路資源載入狀態中，可以看出 import 敘述也會促使瀏覽器從伺服器取回 js 檔案。此時我們不必像傳統方式為所有需要的 js 檔案都寫一行 script src 。控制其他 js 檔案下傳行為的點在模組內部，而不是模組外部的 HTML 。傳統方式使用第三方函式庫時，我們必須先查清楚它需要載入哪些 js ，並在每個 HTML 檔案中寫上一排 script src 。函式庫用得愈多，依賴維護工作就愈麻煩。 JavaScript 的模組功能則不必如此，減少依賴維護工作的成本。

主程式進入點

傳統上，我們在全域空間定義一個 window.load 事件作為主程式進入點。但是全域空間的函式不能呼叫模組空間的內容。故一但你用了模組，就不適合將位於全域空間的 window.load 事件作為主程式進入點。你必須把程式進入點也放在模組空間。當然模組空間內還是可以定義 window.load 事件。

最後，我們可以把 index.html 內的 module 程式碼，也放在另一個 js 檔案。因為這是主程式進入點，習慣上將這個檔案取名為 main.js 。

<script type="module" src="main.js">
</script>

範例: index-with-module-2.html。

避免名稱衝突

模組兼有避免名稱衝突的功用，可以視為簡化的 namespace。我們將不同模組的內容匯入本地模組空間時，可用 import ... as 避免不同模組的內容撞名。

常見的 import ... as 用法有兩種:

import * as name from "module";
為整個模組冠名。存取已冠名的模組內容時，要帶上名稱，如 MyModule.abc() 。
import { export1 as alias1 } from "module";
為匯入項目單獨取別名。

範例: index-different-import-modules.html。

學習 ECMAScript/JavaScript 6 - Async Function 問答指南

Tue, 19 Sep 2023 00:00:00 +0000

注意，本文說的 async function 專指 JavaScript 的定義。

關於 async function (非同步函式)的使用入門，我想只需要回答三個問題就足夠了。

最後補充關於 async 帶來的 color of function 的影響。

各家 JavaScript 引擎並不是同時實現 Promise 和 async 兩個功能。基本上是先實現 Promise ，之後才實現 async 。主流三大家引擎，最晚到 2018 年就都實現了。所以 2019 年之前寫的程式碼，可能還停留在 Promise 而沒用 async 。當然現在用 async 不太需要擔心瀏覽器不支援的事了。

第一問，如何設計與使用 async function (非同步函式)？

答：你要會用 Promise 。

答案很精簡。因為可將 async function (非同步函式) 視為 Promise 的語法糖衣。你懂 Promise 就會用非同步函式。關於 Promise 可參考我的 Promise 學習六步。

第二問，我已經有使用 Promise 設計的函式了，如何改為非同步函式？

答：async function (非同步函式)的基本要求是回傳 Promise 個體。反過來說，任何函式只要是回傳 Promise 個體，那麼直接在函式定義加上 async 修飾詞，就可宣告為非同步函式。

一個回傳 Promise 的函式，其涵義就是「我不能現在告訴你結果，但我承諾待會給你」。這就是一個隱性的非同步函式，當然可以加上 async 修飾詞變成顯性的非同步函式。

例如我在 Promise 實際範例這篇的 Until() 函式，直接加上 async ，其他地方一字不改，跑起來一模一樣。

// 這個函式回傳 Promise ，故只要定義前加上 async 就變顯性的非同步函式
async function Until(expr, timeout)
{
    let _timeout = timeout ? timeout * 10 : undefined;

    let promise = new Promise((resolve, reject) => {
        let count = 0;
        let it = setInterval(() => {
            if (expr()) {
                clearInterval(it);
                resolve(count/10); // elapsed seconds
                return;
            }

            ++count;
            if (_timeout && count > _timeout) { // wait n seconds
                clearInterval(it);
                reject();
                return;
            }
        }, 100) // 0.1 second interval.
    });

    return promise;
}

Until(_ => true, 3)
.then(_ => {
    console.log('ok')
})
.catch(_ => {
    console.log('timeout')
});

第三問，隱性的非同步函式改成顯性宣告(加上 async)有什麼好處？

答：

函式內部可以用 await 表達式簡化「非同步工作」同步化的程式碼。
非同步函式默認回傳值是 Promise 實體。如果回傳值不是 Promise 實體，解譯器將自動擴展成一個 Promise 。
幫助 IDE 工具提醒使用者(你)正在呼叫非同步函式。

傳統上使用 Promise 設計的非同步工作若要同步化，會用 then() 串接起來。具體內容請看 Promise 學習六步第四步：串接實現非同步工作的同步化。但加上 async 宣告後，函式內部就可以用 await 簡化為易讀的形式。

例如:

async function AFunc1a(i)
{
    return  Promise1(i)
            .then(x => Promise2(x))
            .then(y => Promise3(y));
}

// 可用 await 簡化成下列易讀的形式:
async function AFunc1b(i)
{
    let x = await Promise1(i);
    let y = await Promise2(x);
    return Promise3(y);
}

再說回傳值。非同步函式的回傳值如果不是 Promise ，那會自動擴展成一個 Promise ，回傳值包在 resolve()。這也是一個簡化程式碼的效果。

例如:

async function AFunc2a(i)
{
    return new Promise(resolve =>{
        resolve(i+1);
        // 此例不可用後置 ++ ，可以前置 ++ 或 +1
    });
}

async function AFunc2b(i)
{
    // 當此函式宣告為非同步函式時，下列的表達式會自動擴展成上例的 Promise 程式碼。
    return i+1;
}

AFunc2a(1).then(v => console.log('afunc2a result:', v));

AFunc2b(2).then(v => console.log('afunc2b result:', v));

$ node afunc2.js
afunc2b result: 3
afunc2a result: 2

還有，在非同步函式裡出現的 throw 表達式，它的擲出物會包進 reject() 。

例如:

async function AFunc3b(i)
{
    throw i;
    return i+1;
}
// 等於:
async function AFunc3a(i)
{
    return new Promise((resolve, reject) => {
        reject(i);      // throw
        resolve(i+1);   // return
    });
}

AFunc3a(1).then().catch(v => console.log('afunc3a throw:', v));

AFunc3b(2).then().catch(v => console.log('afunc3b throw:', v));

color of function

color of function 指的是在程式碼中使用 async ，會染色你的程式碼。

以我在 C# 語言中使用 async 的經驗，例如我的 A 函式要呼叫第三方類別的 B 函式，但 B 函式已經宣告 async 了。那麼我的 A 函式也要宣告 async 。接著任何呼叫 A 函式的函式，也要跟著宣告 async 。一層層回溯，最後連代表程式起點的 main() 也要宣告 async 。這還只是剛開始。在你的傳統程式碼中添加一個 async ，結果就像是朝一碗清水倒入一滴墨水。當然不想染色也有解法，就是用 Task/Result 變成同步工作。我在 .NET/C# 設計 MQTT 用戶端程式就這麼做了。

這個現象不只出現在 C# ，Java 也有。事實上，每個程式語言在加入 async 語法時，都不能避免染色現象。 JavaScript 在這方面的影響算是比較輕的吧。當然你要真不想用 async ，你依然可以用 Promise 。

MDN - async function
石頭閒語: ECMAScript/JavaScript 6 - Promise 學習六步
石頭閒語: ECMAScript/JavaScript 6 - Promise 實際範例

.NET 筆記 - System.Threading.Timer 和 System.Timers.Timer 兩種計時器的差異

Sat, 03 Jun 2023 00:00:00 +0000

本文內容以 .NET 6 或更新版本為目標平台。我不用 .NET Framework ，不保證適用。

在 .NET 平台上，有兩種主要的計時器類別(Timer)，分別是：

在一些 .NET Framework 文件中，還會提到其他種類的計時器類別，例如 System.Windows.Forms.Timer 。但看名字就知道，那些計時器類別綁定在 UI 庫或 Windows 系統上。而本文提到的這兩種計時器則具有普遍性，不會妨礙 .NET 程式的跨平台運行能力。

對於 Unix/Linux 的開發人員來說， System.Timers.Timer 是傳統意義的計時器實作方式，也就是為每一個定期反覆執行的工作各自配置一個執行緒 (thread) 負責。

System.Threading.Timer 自然也是用執行緒實作，但差別在執行緒的管理方式不一樣。 System.Threading.Timer 會預先配置一組執行緒，稱之為 Thread pool 。由 Thread pool 自己管理執行緒和分派工作。使用者再以事件委派方式，將定期反覆的工作交給 Thread pool 處理。

用實際物品作譬喻的話，System.Timers.Timer 是你兩手空空出門工作。碰到需要計時處理的工作時，才跑去商店買一個鬧鐘來用。而且每件不同的計時工作，各自用一個鬧鐘來計時。

至於 System.Threading.Timer 則是你出門工作時，口袋裡就已經放了兩、三個鬧鐘 (Thead pool)。所以碰到需要計時處理的工作時，直接從口袋裡掏出鬧鐘就行了。節省跑去買鬧鐘的時間。

System.Timers.Timer

在先前的譬喻中說過 System.Timers.Timer 是為每個定期工作各自配置一個執行緒。所以它的使用情境，主要用於伴隨主要工作程式同時存在的支線工作。例如在主線工作執行期間，同時持續回報系統狀態的支線工作就很適合用 System.Timers.Timer 。這些支線工作基本上會和主線工作存在時間一樣久。

一般來說，服務程式內存在許多這種情境。故 .NET 文件對此類別的說明是 The class is intended for use as a server-based or service component。

下列範例是一個 HeartBeat 計時器。每隔一秒就在畫面上印一個 . ，讓使用者知道這個程式還活著。

System.Timers.Timer HeartBeatTimer;

/*
計時器設置:
1. 建立後立即計時: 接著呼叫 Start()
2. 計時後1秒執行內容: interval = 1000
3. 定期重複執行: AutoReset = true
*/
HeartBeatTimer =  new System.Timers.Timer(1000)
{
    AutoReset = true
};
HeartBeatTimer.Elapsed += (s, e)=>{
    Console.WriteLine(".");
};
HeartBeatTimer.Start();

Console.ReadKey();

本文範例完整源碼在 Server-based timer example。

在完整源碼中，還示範了另外兩種情境的用法，即需要計時一次的情境 (TriggerOnce)，或者先擱置、等要用時才呼叫的情境 (Standby)。但那兩種情境的計時工作更適合用 System.Threading.Timer 來做。我只是為了比較兩種計時器的程式寫法才寫出來。在此就不列出程式碼了。有興趣者自己深入看吧。

System.Threading.Timer

System.Threading.Timer 的實作機制是由 .NET 配置並管理一組用於計時工作的執行緒 (Thread pool)，所以程式碼寫法是使用者以事件委派方式，委派工作給 Thread pool 。它適合用來處理需要計時一次的情境 (TriggerOnce)，或者先擱置、等要用時才呼叫的情境 (Standby)。

System.Threading.Timer 可以回收使用執行緒，而不是要用時才配置執行緒、工作完就銷毀。當你的程式中有大量突發性的計時工作需求時，這種機制可以為作業系統節省許多執行緒管理成本。故 .NET 文件對此類別的說明是 a simple, lightweight timer。

下列範例是一個 TriggerOnce 計時器。當你開始某件事，並希望在固定時間時回報時，可以用這種計時器。

/*
計時器設置:
1. 建立後先擱置: dueTime = Infinite, period = Infinite
2. 計時後3秒執行內容: dueTime = 3000
3. 只執行一次: period = Infinite
*/
var TriggerOnceTimer = new System.Threading.Timer((state)=>{
    Console.WriteLine($"計時器1結束 {DateTime.Now}");
}, null, Timeout.Infinite, Timeout.Infinite);

while (true)
{
    Console.WriteLine("按 1 啟動計時器1，其他鍵則結束程式.");
    var ckey = Console.ReadKey();
    if (ckey.KeyChar == '1')
    {
        // 計時器1是靜態實體，重複按1只會啟動同一個計時器
        // 當計時器已經啟動時，再次呼叫 Start() 不會做任何事。
        Console.WriteLine("啟動計時器1 (3秒後)。");
        TriggerOnceTimer.Change(3000, Timeout.Infinite);
    }
    else
    {
        break;
    }
}

上述範例重複按 1 不會啟動複數的計時器。如果想要同時存在多個相同的計時器，那可以改用下列寫法。

static void StartOnceTimer()
{
    /*
    計時器設置:
    1. 建立後立即計時: dueTime is not Infinite
    2. 計時後2秒執行內容: dueTime = 2000
    3. 只執行一次: period = Infinite
    */
    var onceTimer = new System.Threading.Timer((state)=>{
        Console.WriteLine($"計時器2結束 {DateTime.Now}");
    }, null, 2000, Timeout.Infinite);
}

while (true)
{
    Console.WriteLine("按 1 啟動計時器1，其他鍵則結束程式.");
    var ckey = Console.ReadKey();
    if (ckey.KeyChar == '1')
    {
        StartOnceTimer();
    }
    else
    {
        break;
    }
}

本文範例完整源碼在 Thread pool timer example。

在完整源碼中，還示範 HeartBeat 情境的寫法。以及在計時器中再設置另一個計時器的寫法。

另外一提，在多工環境或即時環境中，這種計時器就是取代 sleep 的工具。 Thead.Sleep() 方法會擱置該執行緒的動作，設計不當就會發生程式停止而不能同時回應使用者的狀況。這就是為什麼 WindowsForm 這類 GUI 程式中都不應該使用 Sleep() 方法的原因。

有 JavaScript 設計經驗的程式人員可以這麼想， Sleep 就是 setTimeout()；而此處示範的 TriggerOnce Timer 相當於 setInterval()。

就算在寫 WindowsForm 程式，我個人習慣也不用 System.Windows.Forms.Timer ，而是用 System.Threading.Timer。

.NET 筆記 - 處理程式終止事件 (kill SIGTERM/SIGINT)

Sat, 15 Apr 2023 00:00:00 +0000

本文內容以 .NET 6 或更新版本為目標平台。我不用 .NET Framework ，不保證適用。

我們有很多種方法可以結束一個執行中的程式。例如一個在指令列執行的程式，可以按下 Ctrl + C 打斷它。又或者是「工作管理員」這類的工具，也會提供「結束工作」按鈕讓使用者終止指定的程式。 Linux 用戶熟悉的 kill 指令也是一個用外部工具終止程式的方法。

在 Unix/Linux/BSD/macOS 系統，上述操作都統一在 signal 訊號機制。例如 Ctrl + C 實際上觸發 SIGINT 訊號； kill 默認發出 SIGTERM 訊號；強制終止程式觸發 SIGKILL 訊號。具體列表請見 GNU libc manual - Termination Signals。在 Windows 系統上其實也有類似的方法，不過本文重點是 .NET 平台。

當 .NET Core 從 Windows 走向跨作業系統時，它也必須支持這些操作。但 .NET 沒有增加 signal 類別，而是將 SIGTERM, SIGINT, SIGQUIT 這些訊號設計成事件(event)，打散在不同類別中。

SIGINT/SIGQUIT => Console.CancelKeyPress
SIGTERM => AppDomain.CurrentDomain.ProcessExit

SIGINT 和 CancelKeyPress

// 在終端機按下 Ctrl+C 就等於 kill -SIGINT
Console.CancelKeyPress += (sender, e) =>
{
    System.Console.WriteLine("Cancel Key (SIGINT) received");
    // 等程序跑完事件處理程序後，作業系統就會結束程序。
    // 不需要程序自行呼叫exit。
};

這個事件屬於 Console 類別，所以 winforms 型態的視窗應用程式不會觸發這個事件。

如果你的 .NET 程式作為 Windows 服務執行，那麼從工作管理員終止服務時，也會觸發這個事件。參考我用 nssm 執行 Python 程式的經驗：使Python程式作為Windows服務。

SIGTERM 和 ProcessExit

AppDomain.CurrentDomain.ProcessExit += (s, ev) =>
{
    System.Console.WriteLine("SIGTERM received");
};

注意， ProcessExit 事件在程序正常終止的情形下也會觸發。例如 Main() 結束或呼叫 Environment.Exit() 。

winfroms 型態的視窗應用程式會觸發這個事件。

本文範例完整源碼在 sigterm-handler。

二、三十年前，我們在寫 Unix/Linux 程式時，必須要處理 SIGTERM/SIGINT 這些訊號，以保證我們可以在終止程序之前釋放程序使用的資源。現在的作業系統在資源回收這部份已經不太需要程式設計者關心了。不過我們還是有用到這些事件的場合，例如在程式終止時記錄終止時間，或是發出提示訊息給系統管理者。

.NET 筆記 - NamedPipe 與 Unix Domain Socket (.NET 6)

Sat, 29 Oct 2022 00:00:00 +0000

本文內容以 .NET 6 或更新版本為目標平台。我不用 .NET Framework ，不保證適用。

Named pipe (具名管道) 在 .NET 上不是新玩意，早在 .NET Framework 3.5 時就已提供 NamedPipeServerStream / NamedPipeClientStream。但是自 .NET 6 起，它的底層實作技術改變了。如果你想讓其他程式語言開發的程式 (非 .NET 平台) 和 NamedPipeServerStream / NamedPipeClientStream 程式溝通，必須知道這件事。

我有一個用 .NET Core 3 寫的具名管道服務程式，前陣子想用 .NET 6 發佈到 Linux 跑。結果原先用 FIFO 寫的客戶端程式接不上。一番研究後，才知道 .NET 6 改了具名管道的底層實作技術。

傳統上，Unix 嫡系 UNIX System V 使用 FIFO 檔案實作 named pipe (具名管道)； BSD 家族則是從 socket 中衍生出 Unix Domain Socket ，作為具名管道。Linux 這個私生子同時提供 FIFO 和 Unix Domain Socket ，但因為它的風格偏向 System V ，所以選擇用 FIFO 實作具名管道。在類Unix體系的作業系統上， FIFO 和 Unix Domain Socket 就是替代品關係。真要說兩者有何不同的話，那就是 FIFO 是 kernel module ，而 Unix Domain Socket 則是 library function 。

了解這段技術歷史後，就會知道透過具名管道通訊之前，要先搞清楚對方所說的「具名管道」到底是用哪種技術。特別是在不同程式語言的程式之間。

由於 Windows 系統早先並不提供 Unix Domain Socket ，所以 .NET Framework 用 FIFO 實作 NamedPipeServerStream / NamedPipeClientStream 。但 Windwos 10 Insider Build 17063 (我記得被包含進 18H3) 開始提供 Unix Domain Socket ，所以稍後公開的 .NET 6 也隨之將 NamedPipe 底層實作技術從 FIFO 改成 Unix Domain Socket 。至於改變原因，我猜測是基於可攜性考量。由於 Linux 和 macOS (BSD family) 都提供 Unix Domain Socket ，故 .NET 6 的 NamedPipe 類別自此具備在 Linux, macOS, Windows 10 作業系統之間的可攜性。

本文一方面提供 .NET NamedPipeServerStream 的服務程式範例；另一方面，則是驗證不同程式語言的程式現在該透過何種途徑與 .NET 6 的具名管道溝通。我選擇用 PHP 寫一個使用 unix domain socket 的客戶端程式。

本文範例完整源碼在 named-pipe-server。

服務端與客戶端程式到上述連結查看，就不貼出了。

客戶端程式 (pipe-test.php) 用 PHP 撰寫，透過 unix domain socket 連接服務程式。
因為 Windows 建置版本的 PHP 不支援 unix domain socket ，所以示範工作在 Linux (Debian 11) 上進行。
服務端程式用 .NET 6 建置，在 Debian 11 上執行。
兩端執行時都要指定具名管道的路徑。本文範例是 /tmp/test-named-pipe 。
示範服務程式的工作是將客戶端送來的字串內容，轉成大寫字母後回轉。

執行範例如下圖所示：

這個範例證明 .NET 6 的 NamedPipeServerStream 確實是用 Unix Domain Socket 技術實作。

注意! 不論是 FIFO 或是 Unix Domain Socket 都被視為一種檔案。所以使用時要注意讀寫權限。

在 Linux/macOS 平台，建立 unix domain socket 時，讀寫權限預設是 644 (srw–r–r–)，這表示不同 UID 的程序不能開啟這個 socket 。然而 .NET 對於讀寫權限的設置修改這事，目前還沒有跨平台性的方法。所以 .NET 沒有方法在程式中設置具名管道的讀寫權限。

我目前的做法有三種，提供各位參考。

讓服務端和客戶端都用同一個使用者身份執行。這是通用做法。提醒 Windows 使用者，如果你想把具名管道的服務端程式設為系統服務啟動的話，那不能用預設的 SystemService 身份。
如果是在 Linux/macOS 上跑，用指令 chmod 修改 socket 的讀寫權限為 664 (ug+w) 或 666 (a+w)。
如果是在 Linux/macOS 上跑，執行程式前，先用指令 umask 改變預設權限遮罩。例如 umask 011 就會改變該程式空間新建檔案的讀寫權限為 666 。這會降低安全性，如果不懂 umask 就別用。

.NET MQTT 用戶端訂閱方法使用時的陷阱，關於 MaximumQualityOfService

Wed, 24 Aug 2022 00:00:00 +0000

我有個用 .NET Core 開發的案子，需要透過 MQTT 取得設備狀態後顯示在螢幕上。最近在新增可用設備後，遭客戶回報主程式顯示設備未回應，但指定設備實際上還在運作的狀況。我仔細分析了程式工作期間的 log 內容，發現是主程式訂閱的訊息中途失聯了。主程式剛開始都有收到設備發佈的狀態，一段時間後就收不到了。而執行緒仍然活著好好的，顯然不是程式錯誤。

在解決過程中，我才發現被 System.Net.Mqtt 套件坑了。它有一個不知該說是臭蟲、或是陷阱的特性。若沒有正確設置 MqttConfiguration 的 MaximumQualityOfService 屬性，則訂閱者收到 20 次訂閱訊息後，就不再通知訂閱者新的訊息。

最初我的程式使用 .NET MQTT 套件時，沒有指定訊息的 qos ，採用預設組態。

配置 MqttClient 時，其 MqttConfiguration 省略 MaximumQualityOfService 屬性；此時預設值是 AtMostOne (0)。
調用 SubscribeSync() 訂閱主題時省略 qos 參數；此時 qos 預設值也是 AtMostOne (0)。
設備發佈的訊息，它則明確指定 qos 為 AtLeastOne (1)。

在這種條件下，程式跑起來都很正常，訂閱者擺著幾小時仍然持續收到訊息。

但是我更新程式時，手癢把 SubscribeSync() 加上 qos 參數，指定為 ExactlyOne 。跑幾次單元測試都沒問題，就部署到客戶端。第二天，客戶就回報狀況了。

為了重現狀況，我寫了兩個測試程式，分別負責訂閱者和發佈者的工作。

發佈者程式碼。
訂閱者程式碼。

這兩個程式是用 .NET 6 寫的。取回程式碼後，執行 dotnet run 就能跑了。

發佈者的參數

發佈者程式碼使用 MQTT 參數節錄於下，這部份在測試過程中不動。

var configuration = new MqttConfiguration 
{
    MaximumQualityOfService = MqttQualityOfService.AtMostOnce
};

mqClient.PublishAsync(msg, MqttQualityOfService.AtLeastOnce);

注意 MqttConfiguration 的 MaximumQualityOfService 為 AtMostOne ，而發佈時的 qos 是 AtLeastOnce 。儘管兩者不匹配，但對發佈工作沒有任何影響。

訂閱者的 qos 與 MaximumQualityOfService 符合時

訂閱者先測試 MQTT 套件預設值的情形。其程式碼的 MQTT 參數節錄於下。

var configuration = new MqttConfiguration 
{
    MaximumQualityOfService = MqttQualityOfService.AtMostOnce
};

mqClient.SubscribeAsync(topic);
// 省略 qos 參數時採用預設值 AtMostOne

我分別開兩個視窗，一個跑訂閱者，一個跑執行者。觀察執行結果一小時都很正常。

訂閱者的 qos 與 MaximumQualityOfService 不相符時

接著，來看看只有 SubscribeAsync() 的 qos 參數指定為 ExactlyOne 的情形。

MQTT 參數節錄於下。

var configuration = new MqttConfiguration 
{
    MaximumQualityOfService = MqttQualityOfService.AtMostOnce
};

mqClient.SubscribeAsync(topic, MqttQualityOfService.ExactlyOnce);

然後我就看到訂閱者收到 20 次訊息後，就不再收到新訊息了。如圖:

我本來猜測是不是跟連線時間有關。接著調整了發佈者發佈訊息的時間間隔，看看時間有無影響。而結果不論是隔 10 秒、 20 秒、甚至隔 1 分鐘。訂閱者都是收到 20 次訊息。

面對這個結果，我心中只想著這是不是在惡整人啊？

但只要把 MaximumQualityOfService 也配合調整為 ExactlyOnce ，那麼訂閱者又正常了。

結論

首先，對發佈者來說， PublishAsync() 的 qos 參數不受 MaximumQualityOfService 影響。

而對訂閱者來說， SubscribeAsync() 的 qos 參數必須小於或等於 MaximumQualityOfService 。否則的話，訂閱者最多可收到 20 次訊息。超過就會失效。

因為我的 MQTT 服務端是用 mosquitto，所以後來查了一下 issue ，找到固定 20 次失效的原因。 20 次是 mosquitto 組態項目 max_inflight_messages 的預設值。 mosquitto 預設服務端和訂閱者之間最多允許 20 筆處於遞送過程的訊息，超過這數目就不再發送訊息給訂閱者。但在本文的案例，訂閱者已經收到訊息了，為什麼訊息仍然被認定為「遞送中」？那是因為訂閱者沒有按照 qos 傳送回執 (PUBREL) 給服務端。參考「Mosquitto broker stop publishing on subscribed topics」。(2022-09-06補充)

儘管找到固定 20 次失效的原因，但問題還是在 System.Net.Mqtt 。它不按照訊息的 qos 完成回執，反而受到 MaximumQualityOfService 參數限制，累積大量「收到訊息卻不回報」的欠條，最後就失去訂閱內容了。

我不知道 System.Net.Mqtt 為何如此設計，也不知道為何不擲出例外。這真是令人困惱的特性。難以歸類是臭蟲還是陷阱。

我的實際案例使用的設備，回報狀態的週期最少是 2 分鐘以上。這表示至少前 40 分鐘都會正常運作。而我在做單元測試時，可不會測到 40 分鐘後才出現的錯誤狀況啊。著實被它耍了一把。

MQTT用戶端入門 - 五、.NET/C# 用戶端程式設計

石頭閒語 :: Programming

網頁UI元件 - LimitedCheckbox，複選但有限項目的表單元件

LimitedCheckbox 的設計與運作

HTML 範例

JavaScript 的部份

相關資源

網頁UI元件 - 如何使用新式UI Dialog 和 Modal

Dialog 標準行為

基本設計組合

Dialog 外觀

打造自己的 Dialog

網頁UI元件 - NumberInputElement，自訂增減值按鈕，以及用滑鼠滾輪修改數字

滑鼠滾輪調整輸入數值

增加數值按鈕與減少數值按鈕

控制項的事件傳遞

開始使用

自訂選擇器

整合前端框架

HTML 規範參考

PHP框架 - CommonGateway - 用 URL 重寫規則隱藏 CGF

修改主程式檔名

URL 重寫規則

CGF_REQUEST_ROOT

設計說明

相關文章

學習 ECMAScript/JavaScript 6 - Module 在瀏覽器環境的使用說明

module 特性

script type 的影響

傳統載入 js 的方式

用模組的方式

主程式進入點

避免名稱衝突

學習 ECMAScript/JavaScript 6 - Async Function 問答指南

第一問，如何設計與使用 async function (非同步函式)？

第二問，我已經有使用 Promise 設計的函式了，如何改為非同步函式？

第三問，隱性的非同步函式改成顯性宣告(加上 async)有什麼好處？

color of function

相關文章

.NET 筆記 - System.Threading.Timer 和 System.Timers.Timer 兩種計時器的差異

System.Timers.Timer

System.Threading.Timer

.NET 筆記 - 處理程式終止事件 (kill SIGTERM/SIGINT)

SIGINT 和 CancelKeyPress

SIGTERM 和 ProcessExit

.NET 筆記 - NamedPipe 與 Unix Domain Socket (.NET 6)

.NET MQTT 用戶端訂閱方法使用時的陷阱，關於 MaximumQualityOfService

發佈者的參數

訂閱者的 qos 與 MaximumQualityOfService 符合時

訂閱者的 qos 與 MaximumQualityOfService 不相符時

結論

相關文章