JEP 467 Markdown Documentation Comments

自 JDK 23 開始，javadoc 支援在每一行 javadoc 中，以 /// 開頭的方式，標記為markdown 格式的 javadoc，這種方式取代舊的 /** **/ ，並支援 markdown 語法。

markdown 是簡化的 html，以往在 javadoc，需要用大量的 html tag，標記為

,

, ，現在支援 markdown 語法的 標題、列表、代碼塊、連結、粗體/斜體，讓 javadoc 的內容更精簡。

新舊兩種註解寫法是同時支援的。新的 markdown，除了比較簡潔以外，解決了傳統的 javadoc 使用 html，太難寫，需要寫很多 html tag 的問題，在查看 code 裡面的註解時，markdown 的可讀性明顯比 html 高。

支援的 markdown 語法

• 粗體，斜體文字

• 段落與換行

• 有序及無序的列表 list

• 程式碼

• 標題

• 連結

• 表格

markdown javadoc 範例

    /// 這是使用 Markdown 格式的註釋。
    ///
    /// # 範例功能
    /// * 使用 **Highlight** 語法。
    ///
    /// # 程式區塊：
    /// ```java
    /// test("param");
    /// ```
    ///
    /// # 列表
    /// 1. 項目1
    /// 2. 項目2
    /// 3. 項目3
    ///
    /// # 連結 [google]("https://www.google.com")
    /// * 連結
    /// - 模組 [java.base/]
    /// - 套件 [java.util]
    /// - 類別 [String]
    /// - 欄位 [String#CASE_INSENSITIVE_ORDER]
    /// - 方法 [String#chars()]
    /// - 同一類別其他方法: [equals][#equals(Object)]
    ///
    /// # 表格
    ///
    /// | Latin | Greek |
    /// |-------|-------|
    /// | a     | alpha |
    /// | b     | beta  |
    /// | c     | gamma |
    ///
    /// @param param1 參數
    /// @return 回傳值

SSOT Single Source of Truth

單一真理來源、唯一事實來源。資訊系統架構中的一個核心概念。其核心目標在於確保組織內的每個人、每個系統，在需要特定數據時，都參考同一個來源，從而避免數據不一致導致的決策錯誤。

這樣做可以確保：

• 所有資訊的一致性和準確性

• 減少重複數據和資訊衝突

• 方便查找與更新

• 簡化備份、遷移和共享流程

• 促進團隊協作與溝通

SSOT 並不是指將「所有數據」都存在同一個資料庫中，而是指對於某個特定的數據點（例如：客戶地址、產品價格、庫存數量），在整個系統中只有一個權威的來源（Master Copy）。

在 IT 領域的應用意義

1. 確保數據一致性 (Data Consistency)

在大型 IT 架構中，多個系統（如 ERP、CRM、電商網站）往往會共用相同的數據。若沒有 SSOT，當客戶修改地址時，若只更新了 CRM 而沒更新 ERP，就會導致出貨錯誤。實施 SSOT 後，所有系統都會向「客戶主資料庫」看齊。

2. 降低數據冗餘與維護成本

重複的數據存儲不僅浪費空間，更增加了維護難度。透過 SSOT，開發人員不需要編寫複雜的邏輯來比對多個資料庫之間的差異，簡化了系統整合的複雜度。

3. 提升決策與分析的準確性

對於商業智慧（BI）與大數據分析而言，SSOT 是基礎。如果財務部門和銷售部門提供的營收報表數據對不起來（可能因為計算邏輯或數據來源不同），管理層將難以做出正確判斷。SSOT 確保了「數據來源一致」。

4. 加速開發與自動化

在 DevOps 或現代軟體開發中，SSOT 的概念也被應用於：

• Infrastructure as Code (IaC): 例如 Git 就是基礎設施配置的 SSOT。

• API 驅動架構: 透過統一的 API 接口存取權威數據，避免直接對原始資料庫進行多點讀寫。

實施 SSOT 的挑戰

雖然 SSOT 理想上很完美，但在實際運作中常遇到以下困難：

• 跨部門溝通: 定義「誰才是權威來源」往往涉及組織權責分配。

• 系統效能: 若所有系統都即時請求同一個數據源，可能造成效能瓶頸（通常透過緩存同步機制解決）。

• 舊系統轉型: 整合缺乏標準接口的舊有系統（Legacy Systems）需要極大成本。