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, aber ich werde davon sehr profitieren Nehmen Sie sie 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 Schnittstelle

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-Operationen können zu einer kombiniert werden, je mehr Methoden; Je besser die Dokumentation, desto schwieriger ist es,

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

verwandte Schnittstellen einen konsistenten Stil beizubehalten. Wenn ein vollständiger Satz von APIs ein vertrautes und komfortables Gefühl vermittelt, wird dies den Entwicklern erheblich erleichtern ' Angst vor neuen Werkzeugen.

Dinge benennen: kurz, selbsterklärend und vor allem konsistent

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

Wählen Sie eine Formulierung, die Ihnen gefällt, und bleiben Sie dabei. 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.

Die css()-Methode von jQuery 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 Datumsobjekte, numerische Zeitstempel und sogar einen solchen String zu empfangen

Wenn Sie den Typ des eingehenden Parameters (Zeichenfolge, Zahl, Boolescher Wert) sicherstellen müssen, 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

in order Um Ihre API robuster zu machen, können Sie das Argumentobjekt überprüfen, wenn Sie feststellen müssen, ob ein echter undefinierter Wert übergeben wird:

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 , 然而它实际是传进来的

Benennen Sie die Parameter

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

Event.initMouseEvent Diese Methode ist einfach. Es ist verrückt, ohne die Dokumentation zu lesen. Wer kann schon 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. underscorejs.org/#extend) 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 bestimmte Teile 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: Art des Rückrufs === „Funktion“ verursacht Probleme in alten Browsern und das Objekt wird als Funktion 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.

Für eine funktionsspezifische 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. Dokumentationstool verwenden.

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 fantastischen JavaScript-API-Designs

über: http :/ /jinlong.github.io/2015/08/31/secrets-of-awesome-javascript-api-design/

Das Obige ist der Inhalt der JavaScript-API-Designprinzipien. Weitere verwandte Inhalte finden Sie hier zu PHP Chinese Net (www.php.cn)!