JSON

擴充卡是一種将

ObjectScript

對象(registered, serial or persistent)映射到

JSON

文本或動态實體的方法。本章涵蓋以下主題：

導出和導入-介紹啟用 JSON 的對象并示範 %JSON.Adaptor 導入和導出方法
帶參數映射-描述控制如何将對象屬性轉換為 JSON 字段的屬性參數。
使用擴充資料映射塊-介紹将多個參數映射應用到單個類的方法。
格式化 JSON -示範如何使用 %JSON.ForMatter 格式化 JSON 字元串。
%JSON 快速參考-提供本章中讨論的每個 %JSON 類成員的簡要說明。

Exporting and Importing

從JSON序列化或序列化到JSON的任何類都需要子類

%JSON.Adaptor

，它包括以下方法：

%JSONExport() 将啟用JSON的類序列化為JSON文檔，并将其寫入目前裝置。
%JSONExportToStream() 将啟用JSON的類序列化為JSON文檔并将其寫入流。
%JSONExportToString() 将啟用JSON的類序列化為JSON文檔并将其作為字元串傳回。
%JSONImport() 将JSON作為字元串或流導入，或者作為 %DynamicAbstract Object的子類導入，并傳回啟用JSON的類的執行個體。

為了示範這些方法，本節中的示例将使用這兩個類：

啟用JSON的類 `Model.Event` 和 `Model.Location`

Class Model.Event Extends (%Persistent, %JSON.Adaptor)
  {
    Property Name As %String;
    Property Location As Model.Location;
  }

複制

Class Model.Location Extends (%Persistent, %JSON.Adaptor)
  {
    Property City As %String;
    Property Country As %String;
  }

複制

如所見，我們有一個持久

Event

類，有一個

Location

屬性類型為

Model.Location

。這兩個類都繼承自

%JSON.Adaptor

。這使能夠填充對象圖，并将其直接導出為JSON字元串。

将對象導出為JSON字元串

/// d ##class(PHA.TEST.Xml).SaveEvent()
ClassMethod SaveEvent()
{
    set event = ##class(Model.Event).%New()
    set event.Name = "Global Summit"
    set location = ##class(Model.Location).%New()
    set location.Country = "United States of America"
    set event.Location = location
    do event.%JSONExport()
}

複制

此代碼顯示以下JSON字元串：

DHC-APP>d ##class(PHA.TEST.Xml).SaveEvent()
{"Name":"Global Summit","Location":{"Country":"United States of America"}}

複制

可以使用

%JSONExportToString()

而不是

%JSONExport()

将

JSON

字元串賦給變量：

/// d ##class(PHA.TEST.Xml).SaveEventString()
ClassMethod SaveEventString()
{
    set event = ##class(Model.Event).%New()
    set event.Name = "Global Summit"
    set location = ##class(Model.Location).%New()
    set location.Country = "United States of America"
    set event.Location = location
    do event.%JSONExportToString(.jsonEvent)
    w jsonEvent,!
}

複制

DHC-APP>d ##class(PHA.TEST.Xml).SaveEventString()
{"Name":"Global Summit","Location":{"Country":"United States of America"}}

複制

最後，可以通過

%JSONImport()

将JSON字元串轉換回對象。此示例從上一個示例中擷取字元串變量

jsonEvent

，并将其轉換回

Model.Event

對象：

将JSON字元串導入到對象中

/// d ##class(PHA.TEST.Xml).SaveEventStringImport()
ClassMethod SaveEventStringImport()
{
    set event = ##class(Model.Event).%New()
    set event.Name = "yx"
    set location = ##class(Model.Location).%New()
    s location.City = "tianjin"
    set location.Country = "United States of America"
    set event.Location = location
    do event.%JSONExportToString(.jsonEvent)
    
    
    set eventTwo = ##class(Model.Event).%New()
    do eventTwo.%JSONImport(jsonEvent)
    write eventTwo.Name,!,eventTwo.Location.City
}

複制

DHC-APP>d ##class(PHA.TEST.Xml).SaveEventStringImport()
yx
tianjin

複制

導入和導出都适用于任意嵌套的結構。

使用參數映射

可以通過設定相應的參數為每個單獨的屬性指定映射邏輯。

可以通過指定屬性參數來更改

Model.Event

類(在上一節中定義)的映射：

Class Model.Event Extends (%Persistent, %JSON.Adaptor)
  {
    Property Name As %String(%JSONFIELDNAME = "eventName");
    Property Location As Model.Location(%JSONINCLUDE = "INPUTONLY");
  }

複制

此映射引入了兩個更改：

屬性名稱将映射到名為 eventName 的JSON字段。
Location 屬性仍将由 %JSONImport() 用作輸入，但将被 %JSONExport() 和其他導出方法忽略。

以前，在未修改的

Model.Event

類的執行個體上調用

%JSONExport()

，并傳回以下

JSON

字元串：

{"Name":"Global Summit","Location":{"City":"Boston","Country":"United States of America"}}

複制

如果對重新映射的

Model.Event

執行個體調用

%JSONExport()

(使用相同的屬性值)，将傳回以下字元串：

DHC-APP>d ##class(PHA.TEST.Xml).SaveEvent()
{"eventName":"Global Summit"}

複制

有各種參數可用于調整映射：

%JSONFIELDNAME( 僅限屬性)設定要用作JSON内容中的字段名稱的字元串(預設情況下，值為屬性名稱)。
%JSONIGNOREINVALIDFIELD 控制對JSON輸入中意外字段的處理。
%JSONIGNORENULL 允許開發人員覆寫字元串屬性的空字元串的預設處理。
%JSONINCLUDE (僅限屬性)指定該屬性是否包含在JSON輸出或輸入中(有效值為 "inout" (預設)， "outputonly" ， "inputOnly" ，或 "none" )。
%JSONNULL 指定了如何為字元串屬性存儲空字元串。
%JSONREFERENCE
指定如何将對象引用投影到JSON字段。

選項包括
OBJECT(預設值) 、 ID 、 OID 和 GUID 。

使用XData映射塊

可以在特殊的XData mapping塊中指定映射，并在調用導入或導出方法時應用映射，而不是在屬性級别上設定映射參數。

Class Model.Event Extends (%Persistent, %JSON.Adaptor)
{

Property Name As %String;

Property Location As Model.Location;

XData OnlyLowercaseTopLevel
{
<Mapping xmlns="http://www.intersystems.com/jsonmapping">
        <Property Name="Name" FieldName="eventName"/>
        <Property Name="Location" Include="INPUTONLY"/>
      </Mapping>
}

Storage Default
{
<Data name="EventDefaultData">
<Value name="1">
<Value>%%CLASSNAME</Value>
</Value>
<Value name="2">
<Value>Name</Value>
</Value>
<Value name="3">
<Value>Location</Value>
</Value>
</Data>
<DataLocation>^Model.EventD</DataLocation>
<DefaultData>EventDefaultData</DefaultData>
<IdLocation>^Model.EventD</IdLocation>
<IndexLocation>^Model.EventI</IndexLocation>
<StreamLocation>^Model.EventS</StreamLocation>
<Type>%Storage.Persistent</Type>
}

}

複制

這裡有一個重要的差別:

XData

塊中的

JSON

映射不會改變預設行為，但是可以通過在導入和導出方法的可選參數

%mappingName

中指定塊名稱來應用它們。

例如:

do event.%JSONExport("OnlyLowercaseTopLevel")

複制

/// d ##class(PHA.TEST.Xml).SaveEventXData()
ClassMethod SaveEventXData()
{
    set event = ##class(Model.Event).%New()
    set event.Name = "Global Summit"
    set location = ##class(Model.Location).%New()
    set location.Country = "United States of America"
    set event.Location = location
    do event.%JSONExport("OnlyLowercaseTopLevel")
}

複制

顯示

{"eventName":"Global Summit"}

複制

就像在屬性定義中指定了參數一樣。

如果沒有具有提供名稱的擴充資料塊，将使用預設映射。使用這種方法，可以配置多個映射并分别引用每個調用所需的映射，進而使可以更好地控制，同時使您的映射更加靈活和可重用。

定義到擴充資料映射塊

支援JSON的類可以定義任意數量的附加映射。每個映射都在以下形式的單獨擴充資料塊中定義：

XData {MappingName}
  {
    <Mapping  {ClassAttribute}="value" [...] xmlns="http://www.intersystems.com/jsonmapping".>
      <{Property Name}="PropertyName" {PropertyAttribute}="value" [...] />
      [... more Property elements]
    </Mapping>
  }

複制

其中，

{MappingName}

、

{ClassAttribute}

、

{Property Name}

和

{PropertyAttribute}

的定義如下：

MappingName %JSONREFERENCE 參數或 Reference 屬性使用的映射的名稱。
ClassAttribute 指定映射的類參數。可以定義以下類屬性：
- Mapping -要應用的擴充資料映射塊的名稱。
- IgnoreInvalidField -指定類參數 %JSONIGNOREINVALIDFIELD 。
- NULL -指定類參數 %JSONNULL 。
- IgnoreNull -指定類參數 %JSONIGNORENULL 。
- Reference -指定類參數 %JSONREFERENCE 。
PropertyName 要映射的屬性的名稱。
PropertyAttribute 指定映射的特性參數。可以定義以下特性屬性：
- FieldName -指定屬性參數 %JSONFIELDNAME (預設情況下與屬性名稱相同)。
- Include -指定屬性參數 %JSONINCLUDE (有效值為 "inout" (預設值)， "outputonly" ， "inputOnly" ，或 "none" )。
- Mapping -要應用于對象屬性的映射定義的名稱。
- NULL -覆寫類參數 %JSONNULL 。
- IgnoreNull -覆寫類參數 %JSONIGNORENULL 。
- Reference -覆寫類參數 %JSONREFERENCE 。

格式化JSON

%JSON.ForMatter

是一個具有非常簡單接口的類，允許将動态對象、數組和JSON字元串格式化為更易于閱讀的表示形式。所有方法都是執行個體方法，是以始終從檢索執行個體開始：

set formatter = ##class(%JSON.Formatter).%New()

複制

此選擇背後的原因是，可以将格式化程式配置為隻使用一次某些字元作為行終止符和縮進(例如，空格與制表符；請參閱本節末尾的屬性清單)，然後在需要的任何地方使用它。

Format()

方法接受動态實體或JSON字元串。下面是一個使用動态對象的簡單示例：

/// d ##class(PHA.TEST.Xml).FormatterJson()
ClassMethod FormatterJson()
{
    s formatter = ##class(%JSON.Formatter).%New()
    s dynObj = {"type":"string"}
    do formatter.Format(dynObj)
}

複制

DHC-APP>d ##class(PHA.TEST.Xml).FormatterJson()
{
  "type":"string"
}

複制

Format

方法可以将輸出定向到目前裝置、字元串或流：

Format() 使用指定的縮進格式化JSON文檔并将其寫入目前裝置。
FormatToStream() 使用指定的縮進格式化JSON文檔并将其寫入流。
FormatToString() 使用指定的縮進格式化JSON文檔并将其寫入字元串，或者将啟用JSON的類序列化為JSON文檔并将其作為字元串傳回。

此外，以下屬性可用于控制縮進和換行符：

Indent 縮進指定是否應縮進JSON輸出
IndentChars 指定用于每個縮進級别的字元序列(預設為每個級别一個空格)。
LineTerminator 行終止符指定縮進時終止每行的字元序列。

Caché JSON 使用JSON擴充卡Exporting and Importing使用XData映射塊格式化JSON