題注：
發(fā)表這篇解決方案，屬于非盈利目的。主要是為了讓大家了解一種接口技術(shù)解決方案文檔的編寫格式以及讓大家評(píng)審在我的這個(gè)技術(shù)解決方案中的不足之處，以便大家指出并加以改進(jìn)。
轉(zhuǎn)載，下載或與各種形式使用這篇文章，必須注明文章的作者，出處。
其他未盡事宜，以國(guó)家法律規(guī)定的為準(zhǔn)！
作者：南瘋
在Web Service的調(diào)用過(guò)程中，無(wú)論是外協(xié)系統(tǒng)還是施工系統(tǒng)，都有發(fā)送數(shù)據(jù)和接收數(shù)據(jù)的要求，也即雙方系統(tǒng)同時(shí)作為客戶端又作為服務(wù)端。我們統(tǒng)稱這些傳遞的數(shù)據(jù)為報(bào)文。
客戶端發(fā)送報(bào)文，屬于調(diào)用；服務(wù)端接收?qǐng)?bào)文，屬于被調(diào)用。
客戶端和服務(wù)端互相之間通訊的請(qǐng)求報(bào)文和結(jié)果報(bào)文遵循XML格式。客戶端發(fā)送請(qǐng)求報(bào)文，服務(wù)器解析調(diào)用報(bào)文，執(zhí)行報(bào)文中所在接口對(duì)應(yīng)的服務(wù)功能。生成結(jié)果報(bào)文，以xml格式頁(yè)返回給請(qǐng)求者。請(qǐng)求者拿到結(jié)果報(bào)文，進(jìn)行解析，然后再進(jìn)行相應(yīng)的處理。
u 報(bào)文中所有的字典信息（比如性別1-男，2-女），都以代碼的值（1或者2）來(lái)傳遞。施工單位向外協(xié)系統(tǒng)發(fā)送的報(bào)文中的代碼都需要轉(zhuǎn)換成外協(xié)的代碼，外協(xié)系統(tǒng)向施工系統(tǒng)發(fā)送的報(bào)文中的代碼無(wú)需轉(zhuǎn)換。
u 報(bào)文中的其他數(shù)據(jù)類型，比如貨幣、RowID,自定義對(duì)象類型等，根據(jù)需要轉(zhuǎn)換成文本、數(shù)值或二進(jìn)制（最終轉(zhuǎn)換成Base64字符）的數(shù)據(jù)類型。
u 報(bào)文中數(shù)值信息，轉(zhuǎn)換成文本，如：
<ItemCount>50</ItemCount>
<ValueSum>12368.36</ValueSum>
u 報(bào)文中數(shù)值不支持科學(xué)計(jì)數(shù)的方式。報(bào)文中數(shù)值的單位使用國(guó)標(biāo)的單位，比如貨幣使用“元”，長(zhǎng)度使用“米”等。無(wú)國(guó)標(biāo)的單位以約定為準(zhǔn)。
u 報(bào)文中的日期信息，轉(zhuǎn)換成YYYYMMDD HHmmss文本格式（24小時(shí)制）。如果是空日期，則轉(zhuǎn)換成空文本。
u 報(bào)文中的true和false數(shù)據(jù)類型，轉(zhuǎn)換成 0(表示false)、1（表示true）
u 報(bào)文中的二進(jìn)制數(shù)據(jù)，轉(zhuǎn)換成Base64字符方式發(fā)送。
u 報(bào)文中的記錄集，放在< Records>標(biāo)簽中；報(bào)文中一條記錄，放在< Records>標(biāo)簽中。
u 報(bào)文中如果存在多條記錄，則在<Records>標(biāo)簽中就包含多個(gè)的<Record>標(biāo)簽。如果報(bào)文中僅有一條記錄，則<Records>標(biāo)簽中只包含一個(gè)<Record>標(biāo)簽.如果沒(méi)有記錄，則僅僅包含一個(gè)<Records>標(biāo)簽,沒(méi)有<Record>標(biāo)簽。
u 如果返回結(jié)果數(shù)據(jù)集非常多，在性能考慮和數(shù)據(jù)量沖突的情況下，可以使用分頁(yè)返回?cái)?shù)據(jù)集的方式分批返回?cái)?shù)據(jù)（每次返回最多100條記錄）。服務(wù)端提供分批結(jié)果返回的功能。至于如何使用分頁(yè)查詢的功能，參見下面的XML框架說(shuō)明。
施工系統(tǒng)向外協(xié)系統(tǒng)發(fā)送請(qǐng)求的數(shù)據(jù)目前有幾點(diǎn)需要考慮：
u 如何請(qǐng)求查詢一個(gè)業(yè)務(wù)數(shù)據(jù)
u 如何新增一條記錄，新增之后如何點(diǎn)到記錄的鍵值
u 如何修改一條記錄
u 如何刪除一條記錄
u 文檔如何上傳
u 一條記錄中一個(gè)FileID的字段如何上傳多個(gè)文件
u 如何在一條記錄中補(bǔ)充上傳文檔
u 如何在一條記錄中刪除一個(gè)文檔
u 如何獲得文檔的基本信息
u 如何獲得文檔的所有兄弟信息
u 如何獲得文檔的所有父親信息
u 如何下載一個(gè)文檔
針對(duì)這些問(wèn)題，接口方案的解決方法如下：
施工系統(tǒng)針對(duì)外協(xié)系統(tǒng)發(fā)送的業(yè)務(wù)數(shù)據(jù)查詢請(qǐng)求根據(jù)業(yè)務(wù)類型有很多種。為了簡(jiǎn)化接口，而不是在接口上進(jìn)行業(yè)務(wù)操作，所以，外協(xié)系統(tǒng)將施工系統(tǒng)發(fā)起的數(shù)據(jù)查詢請(qǐng)求看作是數(shù)據(jù)下載的一種方式，而不為了復(fù)雜的業(yè)務(wù)查詢請(qǐng)求提供復(fù)雜的條件解析。
外協(xié)系統(tǒng)提供的數(shù)據(jù)查詢接口是從數(shù)據(jù)下載和數(shù)據(jù)延期性來(lái)考慮的。為了滿足數(shù)據(jù)的下載，外協(xié)系統(tǒng)提供了按照某一個(gè)表的主鍵來(lái)下載數(shù)據(jù)和按照記錄的變更時(shí)間范圍來(lái)下載數(shù)據(jù)的兩種方式查詢請(qǐng)求。
請(qǐng)求報(bào)文：
<?xml version="1.0" encoding="utf-8" ?>
<XmlData>
<UserInfo>
<User>ZhangSan</User>
<PassWord>123456</PassWord>
</UserInfo>
<Description>
<RowID>0</RowID>
<KeyValue>123</KeyValue>
<QueryBeginTime>20061018 153000</QueryBeginTime>
<QueryEndTime>20061019 153000</QueryEndTime>
</Description>
</XmlData>
響應(yīng)報(bào)文：
<?xml version="1.0" encoding="utf-8"?>
<XmlData>
<Description>
<RowID>100</RowID>
</Description>
<Records>
<Record>
<Field1>Value1</Field1>
<Field2>Value2</Field2>
<Field3>Value3</Field3>
<Field4>Value4</Field4>
</Record>
<Record>
<Field1>Value1</Field1>
<Field2>Value2</Field2>
<Field3>Value3</Field3>
<Field4>Value4</Field4>
</Record>
<Record>
<Field1>Value1</Field1>
<Field2>Value2</Field2>
<Field3>Value3</Field3>
<Field4>Value4</Field4>
</Record>
</Records>
</XmlData>
報(bào)文說(shuō)明：
|
標(biāo)簽名
|
說(shuō)明
|
|
<XmlData>
|
報(bào)文數(shù)據(jù)主體
|
|
<Description>
|
報(bào)文頭部信息
|
|
<Records>
|
記錄集合
|
|
<Record>
|
一行記錄
|
|
<UserInfo>
|
業(yè)務(wù)認(rèn)證的用戶信息
|
|
<User>
|
業(yè)務(wù)用戶登錄名
|
|
<PassWord>
|
業(yè)務(wù)用戶驗(yàn)證口令
|
|
<RowID>
|
第一次請(qǐng)求的時(shí)候，客戶端RowID發(fā)送0，表示從第0條記錄開發(fā)返回。服務(wù)端根據(jù)條件查詢，發(fā)現(xiàn)結(jié)果超過(guò)100條記錄，則在返回的結(jié)果中，RowID的值為99，表示服務(wù)端當(dāng)前的記錄位置處在第100條的位置上，后面還會(huì)有剩余的記錄。客戶端檢查返回的結(jié)果，如果發(fā)現(xiàn)RowID大于0,則繼續(xù)發(fā)送請(qǐng)求進(jìn)行查詢。但是，客戶端第二次發(fā)送請(qǐng)求繼續(xù)查詢的時(shí)候，RowID的值要賦值為第一次返回的值，即RowID=99。服務(wù)端第二次收到請(qǐng)求的時(shí)候，發(fā)現(xiàn)RowID是99,則從第100條返回結(jié)果。以此類推循環(huán)調(diào)用，直到服務(wù)端達(dá)到記錄的末尾，這時(shí)候，服務(wù)端在返回的結(jié)果中RowID=0.客戶端發(fā)現(xiàn)服務(wù)端RowID=0，終止循環(huán)調(diào)用。
字典、用戶信息、單位信息，因?yàn)榉祷氐淖侄伪容^少，不受100條記錄返回的限制。一次調(diào)用，就返回全部的結(jié)果。
|
|
<KeyValue>
|
查詢時(shí)主鍵的值。這個(gè)<KeyValue>和下面的<QueryBeginTime><QueryEndTime>是互斥的。如果在請(qǐng)求的時(shí)候提供了主鍵的值，表示客戶端要求服務(wù)器按照主鍵的值查詢一條記錄。如果客戶端提供了主鍵的值，則服務(wù)端將忽略<QueryBeginTime><QueryEndTime>中的值。
字典、用戶信息、單位信息，因?yàn)闆](méi)有查詢時(shí)間范圍，所以<KeyValue>即表示字典類型。
|
|
<QueryBeginTime>
<QueryEndTime>
|
查詢時(shí)時(shí)間段范圍。<QueryBeginTime>是起始時(shí)間，<QueryEndTime>是結(jié)束時(shí)間。表示客戶端要求服務(wù)端查詢?cè)谶@個(gè)時(shí)間范圍之內(nèi)所有變更過(guò)的記錄（包括新增、修改、刪除）。
在外協(xié)中，一條記錄新增的時(shí)候，它的創(chuàng)建時(shí)間和最后修改時(shí)間是一樣的，以后修改記錄的時(shí)候，創(chuàng)建時(shí)間不變，改變的僅僅是最后修改時(shí)間。同時(shí)，外協(xié)系統(tǒng)中刪除記錄僅僅在“記錄是否刪除”字段中標(biāo)記“1”，并不是真正的物理刪除記錄。
這里的時(shí)間指的是記錄變更的時(shí)間，不是記錄中的某個(gè)業(yè)務(wù)時(shí)間。如果用戶需要按照業(yè)務(wù)時(shí)間來(lái)查詢數(shù)據(jù)，則施工系統(tǒng)把外協(xié)系統(tǒng)的數(shù)據(jù)獲取到本地進(jìn)行保存，在施工系統(tǒng)中提供按照業(yè)務(wù)時(shí)間查詢的功能。
<QueryBeginTime><QueryEndTime>和<KeyValue>是互斥的。如果客戶端需要按照時(shí)間范圍來(lái)查詢，則必須<KeyValue>空。
|
|
<Field1>
<Field2>
<Field3>
<Field4>
|
一行記錄中的英文字段名稱。實(shí)際中，這些標(biāo)簽都是字典的英文名。字段的標(biāo)簽全部是大寫。
具體的字段名稱請(qǐng)參見提供的數(shù)據(jù)模型
|
為了簡(jiǎn)化數(shù)據(jù)模型的處理，本方案不考慮主從表的并發(fā)處理情況。如果存在主從表的數(shù)據(jù)需要上傳，那么，在一個(gè)事務(wù)中，施工單位首先先上傳主表的記錄，從反饋信息中獲得主表的主鍵值。然后，把剛剛獲得的主表的主鍵值賦值給從表的對(duì)應(yīng)外鍵，再上傳從表數(shù)據(jù)，得到從表的主鍵值。
如果不是主從表，而是單表，則直接上傳數(shù)據(jù)，從反饋信息中得到主鍵值。
這種情況的優(yōu)點(diǎn)是：數(shù)據(jù)和表相關(guān)，施工單位可以靈活的控制表之間的關(guān)系；同時(shí)，數(shù)據(jù)包中的報(bào)文比較簡(jiǎn)單，容易解析；接口上面比較清晰，與業(yè)務(wù)的耦合比較低。
缺點(diǎn)是：一個(gè)業(yè)務(wù)涉及的主從表不能在同一個(gè)報(bào)文中（這個(gè)缺點(diǎn)可以通過(guò)施工系統(tǒng)靈活的控制表之間關(guān)系來(lái)解決）；一個(gè)業(yè)務(wù)中可能會(huì)使用到兩個(gè)或兩個(gè)以上的接口，造成業(yè)務(wù)完整性上面的分離（這種缺點(diǎn)可以通過(guò)把業(yè)務(wù)放在一個(gè)事務(wù)中來(lái)解決）；
鍵值的返回：在調(diào)用新增接口之后，外協(xié)會(huì)按照記錄的順序返回外外協(xié)中所生成的鍵值。 施工單位獲得鍵值之后，可以在本地表中更新記錄的主鍵值。
請(qǐng)求報(bào)文：
<?xml version="1.0" encoding="utf-8"?>
<XmlData>
<UserInfo>
<User>ZhangSan</User>
<PassWord>123456</PassWord>
</UserInfo>
<Description>
<Note>開工報(bào)告</Note>
</Description>
<Records>
<Record>
<KeyField></KeyField>
<NormalField1>Value1</NormalField1>
<NormalField2>Value2</NormalField2>
<NormalField3>Value3</NormalField3>
<NormalField4>Value4</NormalField4>
</Record>
<Record>
<KeyField></KeyField>
<NormalField1>Value1</NormalField1>
<NormalField2>Value2</NormalField2>
<NormalField3>Value3</NormalField3>
<NormalField4>Value4</NormalField4>
</Record>
</Records>
</XmlData>
響應(yīng)報(bào)文：
<?xml version="1.0" encoding="utf-8"?>
<XmlData>
<Description>
<Result>成功</Result> <!--如果失敗，則<Result>里面內(nèi)容是：失敗：（錯(cuò)誤原因）-->
</Description>
<Records>
<Record>
<KeyField>Value1</KeyField>
</Record>
<Record>
<KeyField>Value2</KeyField>
</Record>
</Records>
</XmlData>
報(bào)文說(shuō)明：
|
標(biāo)簽名
|
說(shuō)明
|
|
<XmlData>
|
報(bào)文數(shù)據(jù)主體
|
|
<Description>
|
報(bào)文頭部信息
|
|
<Records>
|
記錄集合
|
|
<Record>
|
一行記錄
|
|
<UserInfo>
|
業(yè)務(wù)認(rèn)證的用戶信息
|
|
<User>
|
業(yè)務(wù)用戶登錄名
|
|
<PassWord>
|
業(yè)務(wù)用戶驗(yàn)證口令
|
|
<Note>
|
業(yè)務(wù)的簡(jiǎn)單描述。比如：開工報(bào)告、施工組織方案 等
|
|
請(qǐng)求中的<KeyField>
|
一行記錄中的主鍵字段。在新增的時(shí)候，施工系統(tǒng)所給的主鍵字段內(nèi)容為空。外協(xié)系統(tǒng)中根據(jù)主鍵字段內(nèi)容為空，認(rèn)為這是一條新增的記錄
|
|
響應(yīng)中的<KeyField>
|
一行記錄中的主鍵字段。外協(xié)系統(tǒng)返回的主鍵值。這里的主鍵值和施工系統(tǒng)發(fā)送的記錄的順序是一一對(duì)應(yīng)的。
|
|
<Result>
|
反饋報(bào)文中的保存成功與否信息。
如果保存成功，則信息是“成功”
如果保存失敗，則信息是“失敗：（后面是錯(cuò)誤的詳細(xì)信息）”
|
|
|
|
|
|
|
|
|
|