適切なAPIデザイン：「1」、「多」、「ゼロ」、「無」とは

こんにちは、定期的および時折の読者。

本日は、APIの設計と関連する落とし穴に関する興味深い記事を提供したいと思います。 どうやってそれに出会ったのか聞かないでください;創造的な検索は非常に非線形の問題です。

読書を楽しむ


復習

APIを設計する際に考慮すべき多くの要素があります。 セキュリティ、一貫性、状態管理、スタイル。 このリストは無限のようです。 ただし、見落とされがちな要素が1つあります。それは規模に関するものです。 APIを最初から設計するときにシステムの規模を考慮すると、後で（システムが成長するとき）数百時間の作業時間を節約できます。

はじめに

アプリケーションプログラミングインターフェイス（API）を構成するものを定式化するのが難しい場合があります。 技術的な観点から見ると、他のプログラマーのコードによって呼び出された関数はすべて、APIに起因する可能性があります。 どのコードがAPIを「プル」するかについての議論はこの記事の範囲を超えているため、APIは最も単純な関数であると想定します。

この記事では、主なテーマを説明するためだけの簡単な例を特別に選択しました。 C＃の関数が使用されましたが、ここで概説した基本原則は、ほぼすべての言語、フレームワーク、またはシステムに適用できます。 この記事のデータ構造は、多くの産業用データベースで使用されている一般的なリレーショナルスタイルでモデル化されています。 繰り返しますが、例は説明としてのみ書かれており、推奨事項と見なすべきではありません。

必要条件

顧客向けの最も単純な注文処理システムを作成しており、3つの主要なクラス（または必要に応じて「データ構造」）をすでに定義しているとします。 CustomerクラスにはAddressクラスの「外部キー」（データベース用語）があり、OrderクラスにはAddressクラスとCustomerクラスの外部キーがあります。 あなたの仕事は、注文の処理に使用できるライブラリを作成することです。 この場合の最初のビジネスルール：顧客（顧客）のHomeAddress状態は、注文のBillingAddress状態と同じである必要があります。 理由を聞かないでください、ビジネスルールは通常、知的に理解されていません:)

public class Address { public int AddressId { get; set; } public string Street { get; set; } public string City { get; set; } public string State { get; set; } public string Zipcode { get; set; } } public class Customer { public Address HomeAddress { get; set; } public int CustomerId { get; set; } public int HomeAddressId { get; set; } public string CustomerName { get; set; } } public class Order { public Customer MainCustomer { get; set; } public Address ShippingAddress { get; set; } public Address BillingAddress { get; set; } public int OrderId { get; set; } public int CustomerId { get; set; } public int ShippingAddressId { get; set; } public int BillingAddressId { get; set; } public decimal OrderAmount { get; set; } public DateTime OrderDate { get; set; } } 

実装

2つのフィールドが同じかどうかを確認することは、明らかに簡単なタスクです。 上司に感銘を与えたいので、10分もかからずに解決策を作成しました。 VerifyStatesMatch関数は、呼び出し元がビジネスルールが実行されているかどうかを判断できるブール値を返します。 ライブラリをいくつかの簡単なテストで実行し、コードの実行に平均50ミリ秒かかることを確認します。 上司は非常に喜んで、あなたのライブラリを他の開発者に提供し、アプリケーションで使用します。

 public bool VerifyStatesMatch(Order order) { bool retVal = false; try { // ,     25 . Customer customer = SomeDataSource.GetCustomer(order.CustomerId); // ,     25 . Address shippingAddress = SomeDataSource.GetAddress(order.ShippingAddressId); retVal = customer.HomeAddress.State == shippingAddress.State; } catch (Exception ex) { SomeLogger.LogError(ex); } return retVal; } 

問題

翌日、仕事に来ると、モニターにステッカーがあります。「早急に私のところに来てください-シェフ」。 あなたは、昨日あなたがあなたの図書館で非常にうまくいったので、今日上司があなたにさらに深刻な仕事を任せることにしたことを理解します。 しかし、すぐにコードに重大な問題があることがわかりました。

あなた ：おはようございます、シェフ、どうしたの？
チーフ ：これはあなたのライブラリです。それからコードに継続的な問題があります！
あなた ：何？ どうやって？
ヘッド ：ボブはアルゴリズムが遅すぎると言い、ジョンはすべてが正しく機能していないと不満を言い、スティーブはこう言いました。「オブジェクトへの参照はオブジェクトのインスタンスを示していない」
あなた ：わからない、昨日テストして、すべてが順調だった
チーフ ：何も聞きたくありません。 行って理解してください！

その日は最高のスタートではありませんか？ 私には、ほとんどの開発者が同様の状況に出くわしたことがあるようです。 あなたはライブラリを「完璧に」書いたと思っていましたが、それはたくさんの問題をもたらしました。 しかし、「One」、「Many」、「Zero」、および「Nothing」が何であるかを正しく理解すれば、APIが同僚の期待に応えていない場所を区別することができます。

一



en.wikipedia.org/wiki/The_Matrix

行動への最初のガイドは、「1」とは何か、そしてそれをどう扱うかを理解することです。 つまり、APIはいずれの場合でも、予期される入力の一部をエラーなしで処理する必要があります。 このようなエラーは理論的には可能ですが、呼び出し元に報告する必要はありません。 「それは明らかではないですか？」と思うかもしれません。 さて、例を見て、Orderの処理中に発生する可能性のあるエラーを見てみましょう。

 Customer customer = SomeDataSource.GetCustomer(order.CustomerId); Address shippingAddress = SomeDataSource.GetAddress(order.ShippingAddressId); //   customer.HomeAddress       null? retVal = customer.HomeAddress.State == shippingAddress.State; 

上記のコメントから明らかなように、HomeAddressプロパティがデータソースから正しくロードされたと想定しています。 99.99％のケースではそうなる可能性がありますが、真に信頼できるAPIは、これが起こらない場合にもこのようなシナリオを考慮する必要があります。 さらに、言語によっては、これらのプロパティのいずれかが正しくロードされない場合、2つのStateプロパティの比較が失敗する場合があります。 この場合、受け取ることができる入力、または制御していないコードから抽出されたデータについて何も知らないことが重要です。

これは最も単純な例なので、コードを修正して先に進みましょう。

 Customer customer = SomeDataSource.GetCustomer(order.CustomerId); Address shippingAddress = SomeDataSource.GetAddress(order.ShippingAddressId); if(customer.HomeAddress != null) { retVal = customer.HomeAddress.State == shippingAddress.State; } 

たくさん



msdn.microsoft.com/en-us/library/w5zay9db.aspx

上記のシナリオに戻ります。 ボブと話す必要があります。 ボブは、コードが遅いと文句を言いましたが、50ミリ秒の値は、このアーキテクチャを備えたシステムで予想される期間と一致していました。 しかし、ボブは1つのパッケージで最大ユーザーの100件の注文を処理するため、ボブサイクルではメソッドを完了するのに5秒かかります。

 //  : foreach(Order order in bobsOrders) { ... bool success = OrderProcess.VerifyStatesMatch(order); .... } 

あなた ：ボブ、どうして私のコードが遅すぎると思ったの？ 注文の処理にかかる時間はわずか50ミリ秒です。
Bob ：私たちの顧客はAcme Inc.です。 バッチ注文をできるだけ早く処理する必要があります。 100件の注文を処理する必要があるため、5秒は長すぎます。
あなた ：ああ、注文をバッチで処理する必要があることを知りませんでした。
ボブ ：まあ、これはAcmeだけのためです、彼らは私たちの最大のクライアントです。
あなた ：Acmeやバッチ注文については何も言わなかった。
ボブ ：あなたのコードは一度に複数の注文を効率的に処理すべきではありませんか？
あなた ：ああ...はい、もちろん。

何が起こったのか、そしてコードがボブが「遅すぎる」と思われる理由は明らかです。 Acmeやバッチ処理については何も言われませんでした。 Bobループは通常のCustomerクラスをロードし、ほとんどの場合同じAddressレコードを100回ロードします。 この問題は、1つだけではなく、一連の注文を受け入れ、さらにいくつかの単純なキャッシュを追加すると簡単に解決できます。 C＃のparamsキーワードは、まさにそのような状況のために存在します。

 public bool VerifyStatesMatch(params Order[] orders) { bool retVal = false; try { var customerMap = new Dictionary<int, Customer>(); var addressMap = new Dictionary<int, Address>(); foreach (Orderorder in orders) { Customer customer = null; if(customerMap.ContainsKey(order.CustomerId)) { customer = customerMap[order.CustomerId]; } else { customer = SomeDataSource.GetCustomer(order.CustomerId); customerMap.Add(order.CustomerId, customer); } Address shippingAddress = null; if(addressMap.ContainsKey(order.ShippingAddressId)) { shippingAddress = addressMap[order.ShippingAddressId]; } else { shippingAddress = SomeDataSource.GetAddress(order.ShippingAddressId); addressMap.Add(order.ShippingAddressId,shippingAddress); } retVal = customer.HomeAddress.State == shippingAddress.State; if(!retVal) { break; } } } catch (Exception ex) { SomeLogger.LogError(ex); } return retVal; } 

この方法で関数を変更すると、Bobのバッチ処理が劇的に加速します。 一時キャッシュ（ディクショナリ）でIDによってエントリを簡単に見つけることができるため、ほとんどのデータ呼び出しは消えます。

「多く」のAPIを開くとすぐに、すぐに何らかの境界線コントロールを接続する必要があります。 たとえば、誰かがメソッドに100万件の注文を送信した場合はどうなりますか？ このような多数は、このアーキテクチャの機能を超えていますか？ この場合、システムアーキテクチャとビジネスプロセスの両方の概念が役立ちます。 実際に最大10,000件の注文を処理する必要がある場合、自信を持って50,000件の制御を確立できます。これにより、誰もシステムを1つの巨大な受け入れられない呼び出しに入れることができなくなります。

もちろん、可能な最適化のリストはこれに限定されませんが、この例は、最初から「多くの」インスタンスを当てにする場合に、不要な作業を取り除く方法を示しています。

ゼロ



あなた ：スティーブ、私のコードにヌルポインターを渡していますか？
スティーブ ：私はそうは思わないが、何だ？
あなた ：上司は、システムが「リンクは示していない...」と誓います。
スティーブ ：ああ、それはおそらくレガシーシステムの場合でしょう。 このシステムからの出力を制御するのではなく、パイプラインを通じて新しいシステムに出力をそのままアップロードします。
あなた ：ある種のナンセンスだから、これらのゼロで問題を解決してみませんか？
スティーブ ：私は決める。 コードでゼロチェックを行います。 そうじゃない？
あなた ：O ...はい、もちろん。

「オブジェクト参照は、オブジェクトのインスタンスを示すものではありません。」 このエラーの意味を説明する価値はありますか？ 私たちの多くは、それと戦うために人生の1時間以上を費やしました。 ほとんどの言語では、null、空のセットなど。 -未定義の値を持つ任意の型（非値型）に対して完全に有効な状態。 したがって、呼び出し側が技術的に渡すことを許可されていない場合でも、本格的なAPIは値「Null」を考慮する必要があります。

もちろん、ゼロへのすべての参照をチェックすることは複雑な問題であり、時には過剰な測定です。 ただし、どのような場合でも、管理していないソースからの入力を信頼するべきではありません。 したがって、ゼロの「orders」パラメーターと、その中のOrderインスタンスのゼロをチェックする必要があります。

ゼロチェックを正しく実行することにより、テクニカルサポートに申し込んで「オブジェクトのインスタンス」とは何かを尋ねる顧客からの迷惑な電話を避けることができます。 私は常に追い越しを好む。 私の関数は、「オブジェクトのインスタンスを示していない」というかなり役に立たないエラーをスローするよりも、デフォルト値を返し、メッセージをログに記録する（または警告を送信する）方が良いです。 もちろん、このようなソリューションは、システムのタイプ、コードがクライアントで実行されるかサーバーで実行されるかなどに完全に依存します。 重要なのは、ゼロが無視されることですが、それが戻ってくるまでです。

説明：正直なところ、無効な状態に遭遇した場合、関数は「非アクティブ」であるべきだと言っているのではありません。 nullパラメータがシステムで受け入れられない場合、例外をスローします（.NETのArgumentNullなど）。 ただし、状況によっては、意味のあるデフォルトを返すことは完全に受け入れられ、例外をスローする必要はありません。 たとえば、通常、現在のメソッドは、この値で何もできない場合に渡された値を返します。 ゼロに直面しなければならない場合に一般的な推奨事項を与えることができない要因が多すぎます。

なし



youtu.be/CrG-lsrXKRM

あなた ：ジョン、私のコードに何を渡しますか？ 不完全な注文のようです。
ジョン ：ああ、ごめんなさい。 メソッドは必要ありませんが、別のライブラリでOrderパラメーターを渡す必要があります。 このライブラリはあなたのコードを呼び出すと思います。 注文は処理しませんが、別のライブラリを使用する必要があります。
あなた ：このライブラリは修正する必要があります：曲がって設計されています！
ジョン ：なるほど、そのライブラリはビジネスタスクと共に有機的に開発されました-それらは変化していました。 マットはそれを書いたが、彼は今週はいません。 一般に、変更方法はわかりません。 しかし、入力が有効かどうかをコードでチェックすべきではありませんか？
あなた ：はい...確かに。

4つの原則すべてのうち、説明するのが最も難しいものはおそらくありません。 ゼロは、「無」および「無効」のように見えますが、定義があり、定量化できます。 それは、ほとんどの言語で、ゼロ用に特別なキーワードが組み込まれています。 nullを使用する場合、APIはそのような入力を処理する必要がありますが、これは本質的にゴミです。 この例では、CustomerIdを持たない、または5世紀前のOrderDateを持つOrderの処理について説明しています。 より明白な例は、単一の要素がないコレクションです。 このコレクションはnullではないため、カテゴリ「多」に属する必要がありますが、呼び出し元はコレクションにデータを入力しませんでした。 「何も」表示されないようなシナリオを常に考慮する必要があります。 この例では、「何も」も処理されないように調整しましょう。 呼び出し元は、単にOrderのようなものを渡すことはできません。 彼女の注文は、最低限の一般的な要件を満たす必要があります。 それ以外の場合、この情報は「なし」と見なされます。

 ... // ,  . ;-) if (order != null && order.IsValid) ... 

おわりに

この記事の主旨を読者に伝えることができたことを願っています。コードが問題なく入力情報を受け入れることができるということは起こりません。 関数またはAPIを実装するときは、このAPIの使用方法を考慮する必要があります。 この例では、元の関数は12行から50行に増加しましたが、基本的な変更は加えていません。 追加したすべてのコードは、スケーリング、境界線制御、および関数が入力を正しく効率的に処理するために必要です。
近年の保存データの量は指数関数的に増加しているため、入力データの規模は大きくなりますが、このデータの品質は低下します。 APIを最初から正しく記述すると、これはビジネスの成長、増加する顧客ベースへの適応、および長期的に重要な役割を果たすことができます-技術サポートコストを節約できます（そして頭痛が少なくなります）。