Effective C# 原則34：創建大容量的Web API
Item 34: Create Large-Grain Web APIs

交互協議的開銷與麻煩就是對數據媒體的如何使用。在交互過程中可能要不同的使用媒體，例如在交流中要不同的使用電話號碼，傳真，地址，和電子郵件地址。讓我們再回頭來看看上次的訂購目錄，當你用電話訂購時，你要回答售貨員的一系列問題：

“你可以把第一項填一下嗎？”

“這一項的號碼是123-456”

"您想訂購多少呢？"

"三件"

這樣的問題一直要問到銷售人員填寫完所有的信息為止，例如還要知道你的訂購地址，信用卡信息，運送地址，以及其它一些必須的信息來完成這比交易。在電話上完成這樣一來一回的討論還是令人鼓舞的。因為你不會是一個人長時間的自言自語，而且你也不會長時間忍受銷售人員是否還要哪里的安靜狀態。

與傳真訂購相比，你要填寫整個訂購文檔，然后把整個文檔發給公司。一個文件一次性傳輸完成，你不用很填寫產品編號，發傳真，然后填寫地址，然后再傳真，填寫信用卡號，然后再發傳真。

這里演示了一個定義糟糕的web方法接口會遇到的常見缺陷。當你使用web服務，或者.Net遠程交互時，你必須記住：最昂貴的開銷是在兩臺遠程機器之間進行對象傳輸時出現。你不應該只是通過重新封裝一下原來在本地計算機上使用的接口來創建遠程API。雖然這樣是可以工作的，但效率是很低的。
這就有點類似是用電話的方式來完成用傳真訂購的任務。你的應用程序大部份時間都在每次向信道上發送一段數據后等待網絡。使用越是小塊的API，應用程序在等待服務器數據返回的時間應用比就更高。

相反，我們在創建基于web的接口時，應該把服務器與客戶端的一系列對象進行序列化，然后基于這個序列化后的文檔進行傳輸。你的遠程交流應該像用傳真訂購時使用的表單一樣：客戶端應該有一個不與服務器進行通信的擴展運行時間段。這時，當所用的信息已經填寫完成時，用戶就可以一次性的提交這個文檔到服務器上。服務器上還是做同樣的事情：當服務器上返回到客戶上的信息到達時，客戶的手頭上就得到了完成訂購任務必須的所有信息。

比喻說我們要粘貼一個客戶訂單，我們要設計一個客戶的訂購處理系統，而且它要與中心服務器和桌面用戶通過網絡訪問信息保持一致。系統其中的一個類就是客戶類。如果你忽略傳輸問題，那么客戶類可能會像這樣設計，這充許用戶取回或者修改姓名，運輸地址，以及賬號信息：

public class Customer
{
? public Customer( )
? {
? }

? // Properties to access and modify customer fields:
? public string Name
? {
??? // get and set details elided.
? }

? public Address shippingAddr
? {
??? // get and set details elided.
? }

? public Account creditCardInfo
? {
??? // get and set details elided.
? }
}

這個客戶類不包含遠程調用的API，在服務器和客戶之間調用一個遠程的用戶會產生嚴重的交通阻塞：

// create customer on the server.
Customer c = new Server.Customer( );
// round trip to set the name.
c.Name = dlg.Name.Text;
// round trip to set the addr.
c.shippingAddr = dlg.Addr;
// round trip to set the cc card.
c.creditCardInfo = dlg.credit;

相反，你應該在本機創建一個完整的客戶對象，然后等用戶填寫完所有的信息后，再輸送這個客戶對象到服務器：

// create customer on the client.
Customer c = new Customer( );
// Set local copy
c.Name = dlg.Name.Text;
// set the local addr.
c.shippingAddr = dlg.Addr;
// set the local cc card.
c.creditCardInfo = dlg.credit;
// send the finished object to the server. (one trip)
Server.AddCustomer( c );

這個客戶的例子清楚簡單的演示了這個問題：在服務器與客戶端之間一來一回的傳輸整個對象。但為了寫出高效的代碼，你應該擴展這個簡單的例子，應該讓它包含正確的相關對象集合。在遠程請求中，使用對象的單個屬性就是使用太小的粒子(譯注：這里的粒子就是指一次交互時所包含的信息量)。但，對于每次在服務器與客戶之間傳輸來說，一個客戶實例可能不是大小完全正確的粒子。

讓我們來再擴展一下這個例子，讓它更接近現實設計中會遇到的一些問題，我們再對系統做一些假設。這個軟件主要支持一個擁有1百萬客戶的在線賣主。假設每個用戶有一個訂購房子的主要目錄，平均一點，去年有15個訂單。
每個電話接線員使用一臺機器輪班操作，而且不管電話訂單者是否回答電話，他們都要查找或者創建這條訂單記錄。你的設計任務是決定大多數在客戶和服務器之間傳輸的高效對象集合。

你一開始可能消除一些顯而易見的選擇，例如取回每一個客戶以及每次的訂單信息是應該明確禁止的：1百萬客戶以及15百萬(1千5百萬)訂單記錄顯然是太大了而不應該反回到做一個客戶那里去。這樣很容易在另一個用戶上遇到瓶頸問題。在每次可能要更新數據時，都會給服務器施加轟炸式打擊，你要發送一個包含15百萬對象的請求。當然，這只是一次事務，但它確實太低效了。

相反，考慮如何可以最好的取回一個對象的集合，你可以創建一個好的數據集合代理，處理一些在后來幾分鐘一定會使用的對象。一個接線員回復一個電話，而且可能對某個客戶有興趣。在電話交談的過程中，接線員可能添加或者移除訂單，修改訂單，或者修改一個客戶的賬號信息。明顯的選擇就是取回一個客戶，以及這個用戶的所有訂單。服務器上的方法可能會是這樣的：

public OrderData FindOrders( string customerName )
{
? // Search for the customer by name.
? // Find all orders by that customer.
}

對的嗎？傳送到客戶而且客戶已經接收到的訂單很可能在客戶機上是不須要的。一個更好的做法就是為每個請求的用戶只取回一條訂單。服務器的方法可能修改成這個樣子：

public OrderData FindOpenOrders( string customerName )
{
? // Search for the customer by name.
? // Find all orders by that customer.
? // Filter out those that have already
? // been received.
}

這樣你還是要讓客戶機為每個電話訂單創建一個新的請求。有一個方法來優化通信嗎？比下載用戶包含的所有訂單更好的方法。我們會在業務處理中添加一些新的假設，從而給你一些方法。假設呼叫中心是分布的，這樣每個工作組收到的電話具有不同的區號。現在你就可以修改你的設計了，從而對交互進行一個不小的優化。

每個區域的接線員可能在一開始輪班時，就取回并且更新客戶以及訂單信息。在每次電話后，客戶應用程序應該把修改后的數據返回到服務上，而且服務器應該響應上次客戶請求數據以后的所有修改。結果就是，在每次電話后，接線員發送所有的修改，這些修改包含這個組中其它接線員所做的所有修改。這樣的設計就是說，每一個電話只有一次會話，而且每一個接線員應該在每次回復電話時，手里有數據集合訪問權。這樣服務器上可能就有兩個這樣的方法：

public CustomerSet RetrieveCustomerData(
? AreaCode theAreaCode )
{
? // Find all customers for a given area code.
? // Foreach customer in that area code:
??? // Find all orders by that customer.
??? // Filter out those that have already
??? // been received.
? // Return the result.
}

public CustomerSet UpdateCustomer( CustomerData
? updates, DataTime lastUpdate, AreaCode theAreaCode )
{
? // First, save any updates, marking each update
? // with the current time.

? // Next, get the updates:
? // Find all customers for a given area code.
? // Foreach customer in that area code:
??? // Find all orders by that customer that have been
??? // updated since the last time. Add those to the result.
? // Return the result.
}

但這樣可能還是要浪費一些帶寬。當每個已知客戶每天都有電話時，最后一個設計是最有效。但這很可能是不對的。如果是的，那么你的公司應該在客戶服務上存在很大的問題，而這個問題應該用軟件是無法解決的。

如何更進一步限制傳輸大小呢，要求不增加會話次數和及服務器的響應延時？你可以對數據庫里的一些準備打電話的客戶進行一些假設。你可以跟蹤一些統計表，然后可以發現，如果一些客戶已經有6個月沒有訂單了，那么他們很可能就不會再有訂單了。這時你就應該在那一天的一開始就停止取回這些客戶以及他們的訂單。這可以收縮傳輸的初始大小，你同樣可以發現，很多客戶在通過一個簡短電話下了訂單過后，經常會再打電話來詢問上次訂單的事。因此，你可以修改訂單列表，只傳輸最后的一些訂單而不是所有的訂單。這可能不用修改服務器上的方法簽名，但這會收縮傳輸給客戶上的包的大小。

這些假設的討論焦點是要給你一些關于遠程交互的想法：你減少兩機器間的會話頻率和會話時數據包的大小。這兩個目標是矛盾的，你要在這兩者中做一個平衡的選擇。你應該取兩個極端的中點，而不是錯誤的選擇過大，或者過小的會話。
============================
???

Item 34: Create Large-Grain Web APIs
The cost and inconvenience of a communication protocol dictates how you should use the medium. You communicate differently using the phone, fax, letters, and email. Think back on the last time you ordered from a catalog. When you order by phone, you engage in a question-and-answer session with the sales staff:

"Can I have your first item?"

"Item number 123-456."

"How many would you like?"

"Three."

This conversation continues until the sales staff has your entire order, your billing address, your credit-card information, your shipping address, and any other information necessary to complete the transaction. It's comforting on the phone to have this back-and-forth discussion. You never give long soliloquies with no feedback. You never endure long periods of silence wondering if the salesperson is still there.

Contrast that with ordering by fax. You fill out the entire document and fax the completed document to the company. One document, one transaction. You do not fill out one product line, fax it, add your address, fax again, add your credit number, and fax again.

This illustrates the common pitfalls of a poorly defined web method interface. Whether you use a web service or .NET Remoting,you must remember that the most expensive part of the operation comes when you transfer objects between distant machines. You must stop creating remote APIs that are simply a repackaging of the same local interfaces that you use. It works, but it reeks of inefficiency. It's using the phone call metaphor to process your catalog request via fax. Your application waits for the network each time you make a round trip to pass a new piece of information through the pipe. The more granular the API is, the higher percentage of time your application spends waiting for data to return from the server.

Instead, create web-based interfaces based on serializing documents or sets of objects between client and server. Your remote communications should work like the order form you fax to the catalog company: The client machine should be capable of working for extended periods of time without contacting the server. Then, when all the information to complete the transaction is filled in, the client can send the entire document to the server. The server's responses work the same way: When information gets sent from the server to the client, the client receives all the information necessary to complete all the tasks at hand.

Sticking with the customer order metaphor, we'll design a customer order-processing system that consists of a central server and desktop clients accessing information via web services. One class in the system is the customer class. If you ignore the transport issues, the customer class might look something like this, which allows client code to retrieve or modify the name, shipping address, and account information:

public class Customer
{
? public Customer( )
? {
? }

? // Properties to access and modify customer fields:
? public string Name
? {
??? // get and set details elided.
? }

? public Address shippingAddr
? {
??? // get and set details elided.
? }

? public Account creditCardInfo
? {
??? // get and set details elided.
? }
}

?

The customer class does not contain the kind of API that should be called remotely. Calling a remote customer results in excessive traffic between the client and the server:

// create customer on the server.
Customer c = new Server.Customer( );
// round trip to set the name.
c.Name = dlg.Name.Text;
// round trip to set the addr.
c.shippingAddr = dlg.Addr;
// round trip to set the cc card.
c.creditCardInfo = dlg.credit;

?

Instead, you would create a local Customer object and transfer the Customer to the server after all the fields have been set:

// create customer on the client.
Customer c = new Customer( );
// Set local copy
c.Name = dlg.Name.Text;
// set the local addr.
c.shippingAddr = dlg.Addr;
// set the local cc card.
c.creditCardInfo = dlg.credit;
// send the finished object to the server. (one trip)
Server.AddCustomer( c );

?

The customer example illustrates an obvious and simple example: transfer entire objects back and forth between client and server. But to write efficient programs, you need to extend that simple example to include the right set of related objects. Making remote invocations to set a single property of an object is too small of a granularity. But one customer might not be the right granularity for transactions between the client and server, either.

To extend this example into the real-world design issues you'll encounter in your programs, we'll make a few assumptions about the system. This software system supports a major online vendor with more than 1 million customers. Imagine that it is a major catalog ordering house and that each customer has, on average, 15 orders in the last year. Each telephone operator uses one machine during the shift and must lookup or create customer records whenever he or she answers the phone. Your design task is to determine the most efficient set of objects to transfer between client machines and the server.

You can begin by eliminating some obvious choices. Retrieving every customer and every order is clearly prohibitive: 1 million customers and 15 million order records are just too much data to bring to each client. You've simply traded one bottleneck for another. Instead of constantly bombarding your server with every possible data update, you send the server a request for more than 15 million objects. Sure, it's only one transaction, but it's a very inefficient transaction.

Instead, consider how you can best retrieve a set of objects that can constitute a good approximation of the set of data that an operator must use for the next several minutes. An operator will answer the phone and be interacting with one customer. During the course of the phone call, that operator might add or remove orders, change orders, or modify a customer's account information. The obvious choice is to retrieve one customer, with all orders that have been placed by that customer. The server method would be something like this:

public OrderData FindOrders( string customerName )
{
? // Search for the customer by name.
? // Find all orders by that customer.
}

?

Or is that right? Orders that have been shipped and received by the customer are almost certainly not needed at the client machine. A better answer is to retrieve only the open orders for the requested customer. The server method would change to something like this:

public OrderData FindOpenOrders( string customerName )
{
? // Search for the customer by name.
? // Find all orders by that customer.
? // Filter out those that have already
? // been received.
}

?

You are still making the client machine create a new request for each customer phone call. Are there ways to optimize this communication channel more than including orders in the customer download? We'll add a few more assumptions on the business processes to give you some more ideas. Suppose that the call center is partitioned so that each working team receives calls from only one area code. Now you can modify your design to optimize the communication quite a bit more.

Each operator would retrieve the updated customer and order information for that one area code at the start of the shift. After each call, the client application would push the modified data back to the server, and the server would respond with all changes since the last time this client machine asked for data. The end result is that after every phone call, the operator sends any changes made and retrieves all changes made by any other operator in the same work group. This design means that there is one transaction per phone call, and each operator should always have the right set of data available when he or she answers a call. Now the server contains two methods that would look something like this:

public CustomerSet RetrieveCustomerData(
? AreaCode theAreaCode )
{
? // Find all customers for a given area code.
? // Foreach customer in that area code:
??? // Find all orders by that customer.
??? // Filter out those that have already
??? // been received.
? // Return the result.
}

public CustomerSet UpdateCustomer( CustomerData
? updates, DataTime lastUpdate, AreaCode theAreaCode )
{
? // First, save any updates, marking each update
? // with the current time.

? // Next, get the updates:
? // Find all customers for a given area code.
? // Foreach customer in that area code:
??? // Find all orders by that customer that have been
??? // updated since the last time. Add those to the result.
? // Return the result.
}

?

But you might still be wasting some bandwidth. Your last design works best when every known customer calls every day. That's probably not true. If it is, your company has customer service problems that are far outside of the scope of a software program.

How can we further limit the size of each transaction without increasing the number of transactions or the latency of the service rep's responsiveness to a customer? You can make some assumptions about which customers in the database are going to place calls. You track some statistics and find that if customers go six months without ordering, they are very unlikely to order again. So you stop retrieving those customers and their orders at the beginning of the day. That shrinks the size of the initial transaction. You also find that any customer who calls shortly after placing an order is usually inquiring about the last order. So you modify the list of orders sent down to the client to include only the last order rather than all orders. This would not change the signatures of the server methods, but it would shrink the size of the packets sent back to the client.

This hypothetical discussion focused on getting you to think about the communication between remote machines: You want to minimize both the frequency and the size of the transactions sent between machines. Those two goals are at odds, and you need to make trade-offs between them. You should end up close to the center of the two extremes, but err toward the side of fewer, larger transactions.
?
???

總結

以上是生活随笔為你收集整理的Effective C# 原则34：创建大容量的Web API(译)的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。