どう定義するの良し悪しのAPI?[定休日]

StackOverflow https://stackoverflow.com/questions/469161

  •  19-08-2019
  •  | 
  •  

質問

背景：

私の授業を大学という"ソフトウェア制約".最初の講義でした学習方法セミナーなどについてのApiを用意しています。

良い例でしたのは本当に悪いのAPI機能のソケット public static void Select(IList checkRead, IList checkWrite, IList checkError, int microseconds); クライアントまで、フルのC#.この機能を受け3のリストソケットを破壊し、ユーザーをクローンのすべてのソケットに送る Select().でも、タイムアウト(マイクロ秒単位)であるintである最長時間のサーバーへアクセスできるのを待ちます。この制限は+/-35分ですのでint).

ご質問:

  1. どう定義するAPIとして '悪い'?
  2. 方法を定義する APIとして"良い"?

ポイントで発生していると考えること

  • 機能の名前を覚えておいてください。
  • 機能パラメータが理解され難い。
  • 悪ます。
  • すべて相互接続を切り替える必要性がある場合、1行のコードで実際に変更する必要が数百ラインです。
  • 機能の破壊を引数になります。
  • 悪い拡張性により"隠れた"複雑になります。
  • 必要から、ユーザー/devを包みのAPIで使用できます。
役に立ちましたか？

解決

APIの設計では、この基調講演はいつも非常に役に立ちました。
商品をデザインする方法APIとそれが重要な理由-ジョシュアブロッホ

ここに抜粋があります。全体を読む/ビデオを見ることをお勧めします。

  

II。一般原則

     
      
  • APIは1つのことを実行し、適切に実行する必要があります
    •   
  • APIはできるだけ小さくする必要がありますが、小さくはなりません
    •   
  • 実装はAPIに影響を与えません
    •   
  • すべてのアクセシビリティを最小限に抑える
    •   
  • Names Matter <！>＃8211; APIは小さな言語です
    •   
  • ドキュメントの問題
    •   
  • 宗教的な文書
    •   
  • API設計決定のパフォーマンスへの影響を考慮する
    •   
  • パフォーマンスに対するAPI設計決定の効果は現実的かつ永続的です
    •   
  • APIはプラットフォームと平和的に共存しなければなりません
    •   
     

III。クラス設計

     
      
  • 可変性の最小化
    •   
  • 意味のあるサブクラスのみ
    •   
  • 継承のための設計と文書化またはその他の禁止
    •   
     

IV。メソッド設計

     
      
  • クライアントにモジュールができることをさせない
    •   
  • 最低限の驚きの原則に違反しない
    •   
  • Fail Fast-エラーが発生したらできるだけ早く報告する
    •   
  • 文字列形式で利用可能なすべてのデータへのプログラムによるアクセスの提供
    •   
  • 注意してオーバーロード
    •   
  • 適切なパラメーターと戻り値の型を使用する
    •   
  • メソッド間で一貫したパラメーターの順序を使用する
    •   
  • 長いパラメータリストを避ける
    •   
  • 例外的な処理を要求する戻り値を避ける
    •   

他のヒント

正しく使用するためにドキュメントを読む必要はありません。

素晴らしいAPIの兆候。

多くのコーディング標準と長いドキュメント、さらには書籍（フレームワーク設計ガイドライン）はこのトピックについて書かれていますが、この多くはかなり低いレベル。

味の問題もあります。 APIは、さまざまな流行のイデオロギーを奴隷的に順守しているため、どのようなルールブックのすべてのルールにも従う可能性があります。最近の犯人はパターン指向であり、シングルトンパターン（初期化されたグローバル変数より少し）とファクトリーパターン（構築をパラメーター化する方法ですが、必要でないときに実装されることが多い）が多用されます。最近、Inversion of Control（IoC）および関連する爆発的な小さなインターフェイスタイプの数が増え、設計に冗長な概念の複雑さが追加される可能性が高くなります。

好みに最適なチューターは、模倣（多くのコードとAPIを読み、機能するものと機能しないものを見つける）、経験（間違いを犯し、そこから学ぶ）、思考（そのためにおしゃれなことをやるだけではありません）です自分のために、行動する前に考えてください。）

  • 役に立つのでアドレスが必要ないた（または改善、既存のもの)
  • 簡単に説明し、基礎的な理解できなく簡単に把握
  • 以下のオブジェクトモデルの問題領域や現実の世界です。この構築があっても無視されるのでご注意
  • 正しくご使用いただくため、同期されます。なブロックのためにも時間がかかる)
  • 良いデフォルトの動作が可能で拡張できるよう、調整を行うものをデフォルトのすべてに必要な単純な場合
  • サンプル用に作サンプルアプリケーション.この最も重要なのです。
  • 優れた文書
  • 食べご自身のドッグフードがある場合
  • ではセグメントでは大きな汚染された空間です。く機能を設定し異なる分離の少ない場合の依存関係.

がありますが、それは良いスタート

優れたAPIには、説明するものに近いセマンティックモデルがあります。

たとえば、Excelスプレッドシートを作成および操作するためのAPIには、Workbook、Sheetなどのメソッドを持つCell、Cell.SetValue(text)、およびWorkbook.listSheets()などのクラスがあります。

優れたAPIを使用すると、クライアントは必要なほとんどすべてのことを実行できますが、多くの心のこもった忙しい仕事をする必要はありません。 <！> quot;心のない忙しい仕事<！> quotの例;データ構造フィールドを初期化して、間に実際のカスタムコードがなくても変化しないシーケンスでいくつかのルーチンを呼び出します。

悪いAPIの最も確実な兆候は、すべてのクライアントが独自のヘルパーコードでそれをラップしたい場合です。少なくとも、あなたのAPIはそのヘルパーコードを提供しているはずです。最も可能性が高いのは、クライアントが毎回自分自身でロールバックしているより高いレベルの抽象化を提供するように設計されていることです。

API Design Matters

というタイトルのキューにあるこの記事はいつも気に入っています。

http://queue.acm.org/detail.cfm?id=1255422

また、API設計の問題を扱うこの列：

http://queue.acm.org/detail.cfm?id=1229903

不適切なAPIとは、対象とするユーザーが使用しないAPIです。

優れたAPIとは、設計された目的のために対象読者が使用するAPIです。

優れたAPIとは、意図した目的のために意図した対象者と、デザイナーが予期しない理由で意図していない対象者の両方によって使用されるものです。

AmazonがそのAPIをSOAPとRESTの両方として公開し、RESTバージョンが勝つ場合、それは基礎となるSOAP APIが悪かったという意味ではありません。

同じことがあなたにも当てはまると思います。あなたはデザインについてあなたが望むすべてを読んで、あなたのベストを尽くすことができます、しかし、酸テストは使用です。何が機能し、何が機能しないかについてのフィードバックを得る方法を構築し、それを改善するために必要に応じてリファクタリングする準備をします。

優れたAPIは、シンプルなもの（最も一般的なことを行うための最小限の定型文と学習曲線）と可能なもの（可能な限り少ない前提条件で、最大限の柔軟性）を可能にするものです。平凡なAPIは、これらのうちの1つをうまく実行します（非常に単純ですが、本当に基本的なことをしようとしている場合のみ、または非常に強力ですが、非常に急な学習曲線など）。恐ろしいAPIは、これらのどちらもうまくいかないものです。

適切なAPIは、適切な場合、カスタムIOおよびメモリ管理フックを許可する必要があると思います。

典型的な例は、ディスク上のデータ用のカスタム圧縮アーカイブ形式があり、貧弱なapiを持つサードパーティのライブラリがディスク上のデータにアクセスし、データをロードできるファイルへのパスを期待している場合です

このリンクにはいくつかの良い点があります： http://gamearchitect.net/2008/09/19/good-middleware/

APIがエラーメッセージを生成する場合、メッセージと診断が開発者が問題の解決に役立つことを確認します。

私の期待は、APIの呼び出し元が正しい入力を渡すことです。開発者は、エンドユーザーではなくAPIによって生成されるエラーメッセージのコンシューマーであり、開発者向けのメッセージは、開発者が呼び出しプログラムをデバッグするのに役立ちます。

APIは、文書化が不十分な場合は不正です。

APIは、十分に文書化され、コーディング標準に従っている場合に優れています。

今、これらは非常にシンプルで、従うべき非常に難しい2つのポイントです。これにより、ソフトウェアアーキテクチャの領域に1つが入ります。システムを構築し、フレームワークが独自のガイドラインに従うのを支援する優れたアーキテクトが必要です。

コメント付きのコード、よく説明された APIのマニュアルを書くことは必須です。

APIには、使用方法を説明した適切なドキュメントがあれば良いでしょう。ただし、コードがクリーンで、適切であり、コード自体が標準に準拠している場合、適切なドキュメントがあるかどうかは関係ありません。

コーディング構造について少し書きましたこちら

最も重要なことは読みやすさだと思います。つまり、コードができる限り短い時間で何をしているかを理解するために、最も多くのプログラマーが理解できる品質を意味します。しかし、どのソフトウェアが読めるか、どれが読めないかを判断することは、言葉では言い表せないほどの人間の質、つまり曖昧さを持っています。あなたが言及するポイントは、それを結晶化することに部分的に成功します。ただし、全体としてはケースバイケースの状況を維持する必要があり、普遍的なルールを思い付くのは本当に難しいでしょう。

ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top