Serilog 源碼解析——解析字元串模板

大家好啊，上一篇中我們談到 Serilog 是如何決定日誌記錄的目的地的，那麼從這篇開始，我們著重於 Serilog 是向 Sinks 中記錄什麼的，這個大功能比較複雜，我嘗試再將其再拆分成幾個小塊方便大家理解。（系列目錄）

本篇要解決什麼

之前提到，在Logger類中構造對應的LogEvent對象之前，日誌記錄器通過MessageTemplateProcessor類對象的Process方法處理字元串模板和傳入進來的數據資訊。這個方法內部只是做了兩件事：

  1. 解析消息模板，分析哪些是字元串字面值哪些是需要轉換的屬性值
  2. 構造相關的數據對象
public void Process(string messageTemplate, object[] messageTemplateParameters, out MessageTemplate parsedTemplate, out EventProperty[] properties)
{
    parsedTemplate = _parser.Parse(messageTemplate);  // 第一件事
    properties = _propertyBinder.ConstructProperties(parsedTemplate, messageTemplateParameters);  // 第二件事
}

這篇文章主要分析第一件事的處理方法。之後將對應的數據與模板資訊綁定內容則放在下一篇中。

MessageTemplate類

在分析如何處理之前，需要弄明白這個功能函數的輸入是什麼，輸出是什麼，在對生成什麼東西有一定了解後，才能更加方便了解其運行機理。這裡，在第一行程式碼可以發現，輸入是一個字元串，而輸出則是一個MessageTemplate類對象。因此，有必要對MessageTemplate類深入研究。MessageTemplate類保存在 Core 文件夾下，和LogEvent類一樣，都是保存數據而用。這也就說明，MessageTemplate也是LogEvent中的一個屬性，表明它是日誌事件數據中的一部分。

MessageTemplate類中有很多的屬性和方法，這裡僅考慮一些較為重要的屬性。

public class MessageTemplate
{
    public string Text { get; }
    readonly MessageTemplateToken[] _tokens;
    internal ProertyToken[] NamedProperties { get; }
    internal ProertyToken[] PositionalProerties { get; }
    ...
}

Text屬性不用多說，該值為傳入的字元串模板數據。接下來是MessageTemplateToken對象，該對象描述的是模板解析的結果，主要包含兩類 Token，一個是文本 Token，即TextToken類，它描述的是模板中的文本資訊，另一個是屬性 Token，即PropertyToken類，描述的是模板內需要替換的屬性數據名。這些類均是描述解析後的結果資訊，且類文件均位於在 Parsing 文件夾中，且都繼承於MessageTemplateToken類。在MessageTemplate類中，通過引用MessageTemplateToken數組來達到保有模板解析的結果資訊。從變數名上可以發現，MessageTemplate類對象內所擁有的NameProperties和PositionProperties均描述一組屬性 Token，二者的區別在於：前者描述的是具名的屬性Token，該Token在字元串中具有具體的名字；後者描述的是位置的屬性Token，即它在字元串模板中以位置數據出現。

舉個例子，如果字元串模板為版本{version}，那麼其中版本就是文本 Token，version是具名屬性 Token；如果字元串模板為版本{0}，那麼0則是位置的屬性Token，它表示使用後續第一個值作為它的數據。

MessageTemplateToken類及其繼承類

前面提到了 Token 這一描述結果的類型，接下來就是看描述這些 Token 是如何實現自己的功能的。

作為描述字元串解析結果的基類MessageTemplateToken，它主要包含兩大屬性，StartIndex描述該Token在字元串模板中的起始位置，Length描述該Token的長度。另外，這個類是一個抽象類，不允許直接實例化該類。

public abstract class MessageTemplateToken
{
    public int StartIndex { get; }
    public abstract int Length { get; }
}

接下來是文本 Token，即TextToken類。這個類非常簡單，既然文本 Token 只描述模板中的文本部分，它只需要包含描述文本的Text屬性，其長度也就被設置為文本的長度。

public sealed class TextToken : MessageTemplateToken
{
    public string Text { get; }
    public override int Length => Text.Length;
}

之後是屬性 Token，即PropertyToken類。

public sealed class PropertyToken : MessageTemplateToken
{
    readonly string _rawText;
    readonly int? _position;
    public override int Length => _rawText.Length;
    public string PropertyName { get; }
    public Destructuring Destructuring { get; }
    public string Format { get; }
    public Alignment? Alignment { get; }
    public bool IsPositional => _position.HasValue;
}

從上面的程式碼可以看出來，該類要比TextToken複雜。這裡一個個來分析：_rawText變數顧名思義，表示字元串模板中屬性字元串，通常為花括弧所括起來的部分。position作為一個可空int型數據，描述該屬性Token的位置，這裡只有位置的屬性Token才有該值，具名的屬性Token該值為空，二者的從IsPositional屬性來區分。Length表示原始字元串的長度。PropertyName屬性記錄的是屬性 Token 的名字。而Destructuring屬性指明該屬性值應該如何渲染（模板中的變數採用$還是@渲染，即採用數據本身類的ToString方法還是將數據對象解構再渲染），Format指明輸出的格式化字元串，Alignment屬性指明對其的方式，默認左對齊，通過設置可以讓日誌右對齊。舉個例子，比如字元串模板為{version: 000}，那麼其_rawText值為{version: 000}， _position為null， Length為14，PropertyName為version，Destructuring值為Default，Format值為000，Alignment為默認值null，IsPositional為false。

總的來說，MessageTemplate類描述字元串模板解析後的數據，自然也是LogEvent類中的一個重要屬性。在MessageTemplate中，維護一組經解析後的MessageTemplateToken數組，不同的 Token 用不同的類來描述，即描述文本資訊的TextToken以及描述屬性資訊的PropertyToken。

MessageTemplateCache類

在了解完數據的存儲部分後，接下來需要弄清楚的就是處理生成這些數據類的行為類。在MessageTemplateProcessor類的Process函數中，負責處理字元串模板解析的是_parser欄位，它屬於MessageTemplateCache類。那麼首先看下其內部的結構。

interface IMessageTemplateParser
{
    MessageTemplate Parse(string messageTemplate);
}

class MessageTemplateCache : IMessageTemplateParser
{
    readonly IMessageTemplateParser _innerParser;
    readonly object _templatesLock = new object();
    readonly HashTable _templates = new HashTable();
    
    public MessageTemplateCache(IMessageTemplateParser innerParser)
    {
        _innerParser = innerParser;
    }
    public MessageTemplate Parse(string messageTemplate)
    {
        ...
        // 第一步
        var result = (MessageTemplate)_templates[messageTemplate];
        if (result != null) return result;
      
        // 第二步
        result = _innerParser.Parse(messageTemplate);

        // 第三步
        lock (_templatesLock)
        {
            ...
            _templates[messageTemplate] = result;
        }
    }
}

首先，MessageTemplateCache類繼承IMessageTemplateParser介面，該介面位於Core文件夾下，表示是一個解析字元串模板的核心介面，內部包含解析函數Parse，該函數的輸入是字元串模板的字元串數據，輸出是MessageTemplate類。其次，看下繼承類MessageTemplateCache的實現，從名稱上來看，可以看出它帶有快取的解析。當然，內部的實現也是這樣的，在該類內部，有一個_innerParser的同類介面對象，感覺有點熟悉。繼續往下，_templates是一個哈希表，它是字典類的非泛型實現，通過它可以尋找字元串模板對應的MessageTemplate對象，可以將其看成是一個快取。構造函數附帶一個對應消息解析對象，並給_innerParser賦值。在其核心的Parser方法中，它給出了具體的解析邏輯：

  1. 如果當前字元串的解析數據被哈希表所記錄下來，那麼直接從對應的位置提取解析好的MessageTemplate對象並返回。
  2. 如果沒有，則利用內部維護的_innerParser對其解析
  3. 將解析後的MessageTemplate對象添加到哈希表中，為後續同一個消息模板中提供快取數據。

可以發現，這種程式碼結構和之前的 Sink 邏輯非常像，它也是裝飾模式的一個實現。即無論採用何種具體解析消息模板的邏輯，通過MessageTemplateCache類可以為其動態添加快取記錄的功能，對於常用的消息模板場合下可以提高解析的效率，縮短運行時間。換句話來說，解析這一操作行為是一個純函數，即給定的輸入就能給定輸出，不存在副作用，該函數的處理結果可以快取下來。

MessageTemplateParser類

那麼在 Serilog 有提供具體的解析類么？有的，它是位於 Parsing 文件夾下的MessageTemplateParser類。

public class MessageTemplateParser : IMessageTemplateParser
{
    public MessageTemplate Parse(string messageTemplate)
    {
        ...
        return new MessageTemplate(messageTemplate, Tokenize(messageTemplate));
    }
}

可以看到，這個類做的就是直接構造對應的MessageTemplate類對象，這裡的Tokenize函數則是將字元串模板轉換成一個或多個MessageTemplateToken對象，其核心思想就是從左到右依次掃描字元串中的每個字元，判斷其是否是屬性Token起始的{，然後將其分割。如果感興趣的話請閱讀具體源碼，考慮到這段程式碼是一個過程性程式碼，通過調試一步步讀下去即可，這裡就不進行詳述了。

總結

本篇主要講述字元串解析過程的程式碼結構，該結構較為簡單，模板解析的數據均保存在MessageTemplate類中，主要以MessageTemplateToken類對象的形式存在。解析後的 Token 主要分為兩類，只用於描述文本資訊的TextToken類以及描述屬性數據的PropertyToken類。整個字元串模板通過MessageTemplateProcessor的Process函數進行解析，而其內部，利用裝飾模式給處理行為添加快取機制，即MessageTemplateCache類，真正的解析處理邏輯則放在MessageTemplateParser類中，同時這兩個類實現IMessageTemplateParser介面，方便第三方進行替換。

這篇文章主要注重對模板數據的解析，然而，在日誌記錄的過程中，除了日誌模板外，日誌記錄通常還會輸入一些日誌數據，這些數據常用來替換屬性 Token 中的文本。在下一篇中，我們將著重研究 Serilog 日誌庫是如何處理這些日誌數據的。

Tags:

VirMach 便宜 VPS