dataset serialize

Delphi和Lazarus（FPC）的數據集序列化

數據集Serialize是一組功能，可以使JSON和DATASET變得簡單。它具有將記錄導出或導入到數據集中的功能，驗證JSON是否具有所需的所有屬性（以前在數據集中輸入），以JSON格式導出或導入數據集字段的結構。除了通過主細節管理嵌套JSON或使用TDATASETFIELD（您選擇最適合自己的方式）。所有這些都使用類助手，這使其更加簡單，更易於使用。

德爾菲的先決條件

• [Optional]為了放鬆，我建議使用Boss （Delphi的依賴管理器）進行安裝，只需在終端上運行以下命令（例如Windows PowerShell）：

 boss install github.com/viniciussanchez/dataset-serialize

Delphi的手動安裝

如果選擇手動安裝，只需在項目>“選項> building> delphi編譯器>搜索路徑”中添加以下文件夾

 ../dataset-serialize/src

入門

數據集序列化提供的所有功能均位於單元數據集的類幫助器中。要開始項目，只需在需要功能的位置添加您的參考。這是一個例子：

 uses DataSet.Serialize;

現在，讓我們看一下每個功能，其規則和特殊性，以向所有用戶提供最好的功能。

數據集到JSON

使用數據集記錄中的信息創建JSON對像似乎是一個非常簡單的任務。但是該任務變得更加容易。數據集序列化具有兩個功能，即tojsonObject和tojsonArray。讓我們看一下功能的使用：

 var
  LJSONArray: TJSONArray;
  LJSONObject: TJSONObject;  
begin
  LJSONObject := qrySamples.ToJSONObject(); // export a single record
  LJSONArray := qrySamples.ToJSONArray(); // export all records 
end ;

這兩個功能有什麼區別？ TojSonObject僅將當前數據集記錄轉換為tjsonobject。 TojsonArray將轉換為數據集的所有記錄，而不僅僅是所選記錄。

參數

• AChildRecords指示是否導出子記錄（通過主細節或TDATASETFIELD）。
• AOnlyUpdatedRecords指示是否僅導出已修改的記錄（添加，更改或刪除的記錄）。此功能僅在使用FireDac時可用。 cachedupdates屬性必須為真；

tojsonObject

• 如果數據集為空或未分配，則將返回一個空白的JSON對象（ {} ）；
• 沒有可見（真）屬性的字段將被忽略。
• JSON中的屬性名稱始終是較低情況下的字段名稱，即使字段名稱在上限為中。
• 如果該字段是TDATASETFIELD類型的字段，則會生成一個嵌套的JSON（JSONOBJECT，如果它只是子記錄，或者JsonArray（如果超過一個））。對於這種情況，最合適的方法是創建主細節。
• 所有兒童記錄都將出口為JSONARRAY；
• 當使用tojsonObject或tojsonArray方法的aonlyupdatedRecords參數時，將JSON項目添加到負責定義記錄發生的事情（已刪除，包含或更改）的“ Object_state”屬性中；
• 當創建JSON數組以使用主詳細信息表示嵌套的JSON時，數據集名稱將是生成的JSON屬性的名稱。有一個規則，如果數據集名稱以QRY（查詢）或MT（記憶）為單位，則這些縮寫被忽略，僅將其餘作為JSON中的屬性名稱。

Tojsonarray

• 如果數據集為空或未分配，則將返回一個空白的JSON數組（ [] ）；
• 遵循與TojsonObject相同的規則；

保存和負載結構

一個不是很有用的，但重要功能是Savestructure和Loadsstructure。顧名思義，可以保存數據集中配置的字段的整個結構，並以JSON格式加載結構。這是如何加載和導出數據集字段的一個示例：

 var
  LJSONArray: TJSONArray;
begin
  LJSONArray := qrySamples.SaveStructure;
  qrySamples.LoadStructure(LJSONArray, True);
end ;

控制以下屬性：

Alignment, FieldName, DisplayLabel, DataType, Size, Key, Origin, Required, Visible, ReadOnly, and AutoGenerateValue

參數

• AOwns指示誰負責銷毀通過的JSON作為參數。

savestructure

• 如果數據集的字段計數等於零，則將返回一個空白的JSON數組（ [] ）；

負載結構

• 數據集不能被激活，並且不能定義字段；

驗證JSON

當我們要在服務器上驗證我們在請求中收到的JSON是否具有所有必需的信息時，valatejson函數非常有用。實際上，數據集中的所有字段均已遍歷，檢查是否在JSON中輸入了所需的字段。如果需要該字段並且尚未在JSON中輸入，則將其添加到該函數返回的JSON數組中。請參閱下面的示例：

 begin
  LJSONArray := qrySamples.ValidateJSON( ' {"country":"Brazil"} ' );
end ;

在接收{"country": "Brazil"}後，假設我們的數據集有3個字段（ID，first_name，country），並且需要ID和first_name字段，則將返回以下內容：

 [{"field":"id","error":"Id not informed"},{"field":"firstName","error":"Name not informed"}]

參數

• ALang負責更改郵件組裝中使用的語言（默認為英語）；
• AOwns指示誰負責銷毀通過的JSON作為參數；

validatejson

• 如果未分配JSON或字段計數等於零，則提出異常。
• 消息的默認語言是英語；
• 即使輸入了所有必需的字段，也會返回一個空的JSON數組（ [] ）；
• 所需字段必須具有等於true的所需屬性。
• DisplayLabel屬性可用於自定義消息；

JSON的負載

數據集Serializa允許您使用JSONOBJECT，JSONARRAY甚至嵌套的JSON加載數據集，均以一種方法彙總：loadfromjson（）。這是如何使用它的示例：

 begin
  qrySamples.LoadFromJSON( ' {"firstName":"Vinicius Sanchez","country":"Brazil"} ' );
end ;

參數

• AOwns指示誰負責銷毀通過的JSON作為參數；

loadfromjson

• 如果尚未分配JSON或數據集，則將無所作為；
• 如果數據集未被激活，並且不是TFDMEMTABLE類，那麼將無所作為；
• 如果數據集的類型為TFDMemtable，則它不是活動性的，並且字段計數等於零，則將根據JSON需求創建字段。數據類型將等於FTSTRING和大小等於4096；
• 當“ object_state”屬性在JSON中時，進行了以下驗證：
  • 如果等於插入，則在數據集上執行一個附錄；
  • 如果修改或刪除，則在數據集中進行定位，以找到要操縱的記錄。如果找不到註冊表，將什麼也不會做。要執行定位，在JSON中進行了搜索密鑰字段；
  • 如果修改後等於數據集的編輯方法；
  • 如果刪除等於數據集的刪除方法；
• 如果在JSON中找不到“ object_state”屬性，則調用附加方法；
• 當使用JSON加載數據集時，忽略了可讀或可見（false）的字段；
• 如果在JSON中找不到字段名稱（不敏感），或者是nullo，則該字段被忽略（nullo / empty）；
• 使用主體詳細信息將數據集加載到包含嵌套JSON的JSON時，預計子數據集的名稱與代表要加載的兒童列表的JSON屬性名稱相同。兒童數據集的名稱可能仍然具有縮寫QRY（查詢）或MT（記憶），因為這些姓名將被忽略；

從Json合併

使用數據集序列化，您仍然可以通過使用MergeFromjSonObject更改數據集註冊。該功能類似於LoadFromjson。使用的一個示例是用於REST服務器時，當提出請求中使用的動詞時（不一定是），在這種情況下，我們不想包括新記錄，而是要更改當前記錄。

 begin
  qrySamples.MergeFromJSONObject( ' {"firstName":"Vinicius","country":"United States"} ' );
end ;

參數

• AOwns指示誰負責銷毀通過的JSON作為參數；

MergeFromjSonObject

• 與LoadFromjson驗證相同；

配置

您可以自定義數據集序列化的某些功能：

• 日期輸入是UTC（時區）

TDataSetSerializeConfig.GetInstance.DateInputIsUTC := True;

• 導出零值

  TDataSetSerializeConfig.GetInstance. Export .ExportNullValues := True;

• 當字符串以{或[[或[

  TDataSetSerializeConfig.GetInstance. Export .TryConvertStringToJson := True;

• 僅出口字段可見

  TDataSetSerializeConfig.GetInstance. Export .ExportOnlyFieldsVisible := True;

• 導出子數據集作為JSON對象（當您只有1個記錄時）

  TDataSetSerializeConfig.GetInstance. Export .ExportChildDataSetAsJsonObject := False;

• Export大入為字符串

  TDataSetSerializeConfig.GetInstance. Export .ExportLargeIntAsString := False;

• 導出BCD作為浮動

  TDataSetSerializeConfig.GetInstance. Export .ExportBCDAsFloat := False;

• 僅導入字段可見

  TDataSetSerializeConfig.GetInstance. Import .ImportOnlyFieldsVisible := True;

• base64在導入上解碼斑點字段

  TDataSetSerializeConfig.GetInstance. Import .DecodeBase64BlobField := True;

• 刪除字段名稱上的空白空間

  TDataSetSerializeConfig.GetInstance.RemoveBlankSpaceFieldName := True; // default

• 案例名稱定義

  // cndNone, cndLower, cndUpper, cndLowerCamelCase, cndUpperCamelCase
  TDataSetSerializeConfig.GetInstance.CaseNameDefinition := TCaseNameDefinition.cndLowerCamelCase;
  
  TCaseNameDefinition.cndNone:
  [ { "MOB_ICADASTRO":11795,"MOB_EMI_REG":6,"CODIGODOCLIENTE":1,"CDOCUMEN1":"999999" } ]
  
  TCaseNameDefinition.cndLower:
  [ { "mob_icadastro":11795,"mob_emi_reg":6,"codigodocliente":1,"cdocumen1":"999999" } ]

  TCaseNameDefinition.cndUpper:
  [ { "MOB_ICADASTRO":11795,"MOB_EMI_REG":6,"CODIGODOCLIENTE":1,"CDOCUMEN1":"999999" } ]

  TCaseNameDefinition.cndLowerCamelCase:
  [ { "mobIcadastro":11795,"mobEmiReg":6,"codigodocliente":1,"cdocumen1":"999999" } ]

  TCaseNameDefinition.cndUpperCamelCase:
  [ { "MobIcadastro":11795,"MobEmiReg":6,"Codigodocliente":1,"Cdocumen1":"999999" } ]  

• 格式日期（對於導出字段類型等於ftdate）

  TDataSetSerializeConfig.GetInstance. Export .FormatDate := ' YYYY-MM-DD ' ;

• 格式貨幣（對於導出字段類型等於FTCurrency）

  TDataSetSerializeConfig.GetInstance. Export .FormatCurrency := ' 0.00## ' ;

• 格式浮點（對於導出字段類型等於ftfloat）

  TDataSetSerializeConfig.GetInstance. Export .FormatFloat := ' ,0.00 ' ;

• 定義數據集前綴

  TDataSetSerializeConfig.GetInstance.DataSetPrefix := [ ' mt ' , ' qry ' ];

樣品

查看我們的示例項目，以了解上述運行中的每種情況。如果您有任何疑問或建議，請聯繫，提出拉請請求或創建問題。

代碼貢獻者

執照

DataSet-Serialize是根據MIT許可證許可的免費和開源軟件。

一個人我們走得更快。我們在一起走得更遠。