Eine detaillierte Einführung in die Designprinzipien der JavaScript-API

Vor einiger Zeit haben wir unsere native Modul-API organisiert und optimiert (iOS- und Android-Module sind in JavaScript-Schnittstellen gekapselt), daher habe ich mehrere Artikel zum JavaScript-API-Design studiert, obwohl es sich um alte Artikel handelt hat sehr davon profitiert. Nehmen Sie es hier auf.

Gutes API-Design: Erreichen Sie das Ziel der Abstraktion und bleiben Sie gleichzeitig selbstbeschreibend.

Mit einer gut gestalteten API können Entwickler schnell loslegen. Sie müssen nicht häufig Handbücher und Dokumente bereithalten und müssen nicht häufig die Community des technischen Supports aufsuchen.

Glatte Benutzeroberfläche

Methodenkette: reibungslos und leicht zu lesen, leichter zu verstehen

//常见的 API 调用方式：改变一些颜色，添加事件监听
var elem = document.getElementById("foobar");
elem.style.background = "red";
elem.style.color = "green";
elem.addEventListener('click', function(event) {
  alert("hello world!");
}, true);

//（设想的）方法链 API
DOMHelper.getElementById('foobar')
  .setStyle("background", "red")
  .setStyle("color", "green")
  .addEvent("click", function(event) {
    alert("hello world");
  });

Set- und Get-Vorgänge können durchgeführt werden kombiniert: Je mehr Methoden es gibt, desto schwieriger kann es sein, die Dokumentation zu schreiben

var $elem = jQuery("#foobar");

//setter
$elem.setCss("background", "green");
//getter
$elem.getCss("color") === "red";

//getter, setter 合二为一
$elem.css("background", "green");
$elem.css("color") === "red";

Konsistenz

Relevante Schnittstellen behalten einen konsistenten Stil bei und ein vollständiger Satz von APIs vermittelt a Gefühl der Vertrautheit und des Komforts Dieses Gefühl wird die Anpassungsfähigkeit der Entwickler an neue Tools erheblich verringern.

Nennen Sie dieses Ding: Es sollte kurz, selbsterklärend und vor allem konsistent sein

„In der Informatik gibt es nur zwei schwierige Probleme: Cache-Invalidierung und das Benennen von Dingen.“ „
„In der Informatik gibt es nur zwei Probleme: Cache-Ungültigmachungen und Namensprobleme“
-Phil Karlton

Wählen Sie ein Wort aus, das Ihnen gefällt, und verwenden Sie es weiterhin. Wählen Sie einen Stil und behalten Sie ihn bei.

Verarbeitungsparameter

Sie müssen berücksichtigen, wie die von Ihnen bereitgestellte Methode verwendet wird. Wird sie wiederholt aufgerufen? Warum wird es wiederholt aufgerufen? Wie hilft Ihre API Entwicklern, doppelte Aufrufe zu reduzieren?
Empfangen Sie Kartenzuordnungsparameter, Rückrufe oder serialisierte Attributnamen, was Ihre API nicht nur sauberer, sondern auch komfortabler und effizienter in der Nutzung macht.

jQuerys css()-Methode kann Stile für DOM-Elemente festlegen:

jQuery("#some-selector")
  .css("background", "red")
  .css("color", "white")
  .css("font-weight", "bold")
  .css("padding", 10);

Diese Methode kann ein JSON-Objekt akzeptieren:

jQuery("#some-selector").css({
  "background" : "red",
  "color" : "white",
  "font-weight" : "bold",
  "padding" : 10
});

//通过传一个 map 映射绑定事件
jQuery("#some-selector").on({
  "click" : myClickHandler,
  "keyup" : myKeyupHandler,
  "change" : myChangeHandler
});

//为多个事件绑定同一个处理函数
jQuery("#some-selector").on("click keyup change", myEventHandler);

Verarbeitungstyp

Beim Definieren einer Methode müssen Sie entscheiden, welche Parameter sie empfangen kann. Wir wissen nicht, wie die Leute unseren Code verwenden, aber wir können vorausschauender sein und überlegen, welche Parametertypen wir unterstützen.

//原来的代码
DateInterval.prototype.days = function(start, end) {
  return Math.floor((end - start) / 86400000);
};

//修改后的代码
DateInterval.prototype.days = function(start, end) {
  if (!(start instanceof Date)) {
    start = new Date(start);
  }
  if (!(end instanceof Date)) {
    end = new Date(end);
  }

  return Math.floor((end.getTime() - start.getTime()) / 86400000);
};

Mit nur 6 hinzugefügten Codezeilen ist unsere Methode leistungsstark genug, um Date Objekte, numerische Zeitstempel und sogar Zeichenfolgen wie Sat Sep 08 2012 15:34:35 GMT+0200 (CEST)

zu akzeptieren, wenn Sie dies sicherstellen müssen B. den Typ des eingehenden Parameters (Zeichenfolge, Zahl, Boolescher Wert), können Sie ihn wie folgt konvertieren:

function castaway(some_string, some_integer, some_boolean) {
  some_string += "";
  some_integer += 0; // parseInt(some_integer, 10) 更安全些
  some_boolean = !!some_boolean;
}

Handle undefiniert

Um Ihre API robuster zu machen, müssen Sie dies tun Um festzustellen, ob der tatsächliche undefined-Wert übergeben wird, können Sie das arguments-Objekt überprüfen:

function testUndefined(expecting, someArgument) {
  if (someArgument === undefined) {
    console.log("someArgument 是 undefined");
  }
  if (arguments.length > 1) {
    console.log("然而它实际是传进来的");
  }
}

testUndefined("foo");
// 结果: someArgument 是 undefined
testUndefined("foo", undefined);
// 结果:  someArgument 是 undefined , 然而它实际是传进来的

Namen des Parameters

event.initMouseEvent(
  "click", true, true, window,
  123, 101, 202, 101, 202,
  true, false, false, false,
  1, null);

Event.initMouseEvent Diese Methode ist einfach verrückt Wenn Sie die Dokumentation nicht lesen, kann jemand sagen, was die einzelnen Parameter bedeuten?

Geben Sie jedem Parameter einen Namen und weisen Sie einen Standardwert zu. Beispielsweise hat

event.initMouseEvent(
  type="click",
  canBubble=true,
  cancelable=true,
  view=window,
  detail=123,
  screenX=101,
  screenY=202,
  clientX=101,
  clientY=202,
  ctrlKey=true,
  altKey=false,
  shiftKey=false,
  metaKey=false,
  button=1,
  relatedTarget=null);

ES6 oder Harmony Standardparameterwerte und Ruheparameter.

Der Parameter empfängt ein JSON-Objekt

Anstatt eine Reihe von Parametern zu empfangen, ist es besser, ein JSON-Objekt zu empfangen:

function nightmare(accepts, async, beforeSend, cache, complete, /* 等28个参数 */) {
  if (accepts === "text") {
    // 准备接收纯文本
  }
}

function dream(options) {
  options = options || {};
  if (options.accepts === "text") {
    // 准备接收纯文本
  }
}

Es ist auch einfacher aufzurufen :

nightmare("text", true, undefined, false, undefined, /* 等28个参数 */);

dream({
  accepts: "text",
  async: true,
  cache: false
});

Parameter-Standardwerte

Es ist am besten, Standardwerte für Parameter zu haben. Die voreingestellten Standardwerte können durch jQuery.extend() http:// überschrieben werden. www.php.cn/) und Object.extend von Protoype.

var default_options = {
  accepts: "text",
  async: true,
  beforeSend: null,
  cache: false,
  complete: null,
  // …
};

function dream(options) {
  var o = jQuery.extend({}, default_options, options || {});
  console.log(o.accepts);
}

dream({ async: false });
// prints: "text"

Erweiterbarkeit

Rückrufe

Durch Rückrufe können API-Benutzer einen bestimmten Teil Ihres Codes überschreiben. Öffnen Sie einige Funktionen, die angepasst werden müssen, in konfigurierbare Rückruffunktionen, sodass API-Benutzer Ihren Standardcode einfach überschreiben können.

Sobald die API-Schnittstelle einen Rückruf erhält, stellen Sie sicher, dass Sie ihn dokumentieren und Codebeispiele bereitstellen.

Ereignisse

Es ist am besten, den Namen der Ereignisschnittstelle zu kennen. Sie können den Ereignisnamen frei wählen, um eine Duplizierung von Namen mit nativen Ereignissen zu vermeiden.

Umgang mit Fehlern

Nicht alle Fehler sind für Entwickler zum Debuggen von Code nützlich:

// jQuery 允许这么写
$(document.body).on('click', {});

// 点击时报错
//   TypeError: ((p.event.special[l.origType] || {}).handle || l.handler).apply is not a function
//   in jQuery.min.js on Line 3

Das Debuggen solcher Fehler ist schmerzhaft, also verschwenden Sie keine Zeit für Entwickler. Sagen Sie ihnen direkt, welchen Fehler sie gemacht haben:

if (Object.prototype.toString.call(callback) !== '[object Function]') { // 看备注
  throw new TypeError("callback is not a function!");
}

Hinweis: typeof callback === "function" verursacht Probleme in älteren Browsern und object wird als function behandelt.

Vorhersehbarkeit

Eine gute API ist vorhersehbar und Entwickler können ihre Verwendung anhand von Beispielen ableiten.

Die Funktionserkennung von Modernizr ist ein Beispiel:

a) Die verwendeten Eigenschaftsnamen stimmen genau mit HTML5, CSS-Konzepten und APIs überein

b) Jede einzelne Erkennung ist konsistent und gibt true oder zurück falsche Werte

// 所有这些属性都返回 'true' 或 'false'
Modernizr.geolocation
Modernizr.localstorage
Modernizr.webworkers
Modernizr.canvas
Modernizr.borderradius
Modernizr.boxshadow
Modernizr.flexbox

basiert auf Konzepten, mit denen Entwickler bereits vertraut sind und vorhersehbar sein können.

Die Selektorsyntax von jQuery ist ein offensichtliches Beispiel dafür, dass CSS1-CSS3-Selektoren direkt in der DOM-Selektor-Engine verwendet werden können.

$("#grid") // Selects by ID
$("ul.nav > li") // All LIs for the UL with class "nav"
$("ul li:nth-child(2)") // Second item in each list

Proportionale Koordination

Eine gute API ist nicht unbedingt eine kleine API, die Größe der API muss im Einklang mit ihrer Funktionalität stehen.

Moment.js, eine bekannte Bibliothek zur Datumsanalyse und -formatierung, kann als ausgewogen bezeichnet werden. Ihre API ist sowohl prägnant als auch funktional.

Bei einer funktionsspezifischen Bibliothek wie Moment.js ist es wichtig, die API fokussiert und klein zu halten.

API-Dokumentation schreiben

Eine der schwierigsten Aufgaben in der Softwareentwicklung ist das Schreiben von Dokumentationen. Tatsächlich hasst es jeder, Dokumentationen zu schreiben. Die häufigste Beschwerde ist, dass es kein einfach zu verwendendes Dokumentationstool gibt .

Im Folgenden sind einige Tools zur automatischen Dokumentgenerierung aufgeführt:

• YUIDoc (erfordert Node.js, npm)

• JsDoc Toolkit (erfordert Node.js, npm)

• Markdox (erfordert Node.js, npm)

• Dox (erfordert Node.js, npm)

• Docco (erfordert Node.js, Python, CoffeeScript)

• JSDuck (erfordert Ruby, Gem)

• JSDoc 3 (erfordert Java)

Das Wichtigste ist: Stellen Sie sicher, dass die Dokumentation und der Code gleichzeitig aktualisiert werden.

Referenzen:

• Gutes API-Design

• Entwerfen besserer JavaScript-APIs

• Geheimnisse des fantastischen JavaScript-API-Designs

Das obige ist der detaillierte Inhalt vonEine detaillierte Einführung in die Designprinzipien der JavaScript-API. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!