Principes de conception des API JavaScript

Il y a quelque temps, nous avons organisé et optimisé notre API de module natif (les modules iOS et Android sont encapsulés dans des interfaces JavaScript), j'ai donc étudié plusieurs articles sur la conception d'API JavaScript, bien qu'ils soient anciens, j'en ai beaucoup profité. enregistrez-les ici.

Bonne conception d'API : atteindre l'objectif d'abstraction tout en étant auto-descriptif.

Avec une API bien conçue, les développeurs peuvent démarrer rapidement. Il n'est pas nécessaire de conserver fréquemment des manuels et des documents, et il n'est pas nécessaire de consulter fréquemment la communauté d'assistance technique.

Interface fluide

Chaîne de méthodes : fluide et facile à lire, plus facile à comprendre

//常见的 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");
  });

Les opérations Set et Get peuvent être combinées en une seule ; meilleure est la documentation Plus il est difficile d'écrire des interfaces liées à la

var $elem = jQuery("#foobar");
//setter
$elem.setCss("background", "green");
//getter
$elem.getCss("color") === "red";
//getter, setter 合二为一
$elem.css("background", "green");
$elem.css("color") === "red";

cohérence

maintenir un style cohérent Si un ensemble complet d'API transmet un sentiment familier et confortable, cela facilitera grandement les développeurs. ' anxiété face aux nouveaux outils.

Nommer les choses : court, auto-descriptif et surtout cohérent

"Il n'y a que deux problèmes difficiles en informatique : l'invalidation du cache et la dénomination des choses."
"Il y a seulement deux maux de tête en informatique : les invalidations de cache et les problèmes de nommage"
— Phil Karlton

Choisissez une formulation que vous aimez et respectez-la. Choisissez un style et gardez-le ainsi.

Paramètres de traitement

Vous devez considérer la façon dont les gens utilisent la méthode que vous fournissez. Sera-t-elle appelée à plusieurs reprises ? Pourquoi est-il appelé à plusieurs reprises ? Comment votre API aide-t-elle les développeurs à réduire les appels en double ?
Recevez des paramètres de mappage de carte, des rappels ou des noms d'attributs sérialisés, ce qui non seulement rend votre API plus propre, mais la rend également plus confortable et efficace à utiliser.

La méthode css() de jQuery peut définir des styles pour les éléments DOM :

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

Cette méthode peut accepter un objet JSON :

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);

Type de traitement

Lors de la définition d'une méthode, vous devez décider quels paramètres elle peut recevoir. Nous ne savons pas comment les gens utilisent notre code, mais nous pouvons être plus prospectifs et réfléchir aux types de paramètres que nous prenons en charge.

//原来的代码
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);
};

Avec seulement 6 lignes de code ajoutées, notre méthode est suffisamment puissante pour recevoir des objets Date, des horodatages numériques et même le samedi 8 septembre 2012 15:34:35 GMT 0200 (CEST) String

Si vous devez vous assurer du type du paramètre entrant (chaîne, nombre, booléen), vous pouvez le convertir comme ceci :

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

handle undefined

afin d'utiliser Votre API est plus robuste. Si vous avez besoin d'identifier si une valeur réelle non définie est transmise, vous pouvez vérifier l'objet arguments :

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

Nommez les paramètres

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

Événement. initMouseEvent Cette méthode est tout simplement folle, sans lire la documentation, qui peut dire ce que signifie chaque paramètre ?

Donnez un nom à chaque paramètre et attribuez une valeur par défaut. Par exemple,

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, ou Harmony a des valeurs de paramètres par défaut et des paramètres de repos.

Le paramètre reçoit un objet JSON

Au lieu de recevoir un tas de paramètres, il vaut mieux recevoir un objet JSON :

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

C'est aussi plus simple à appeler :

nightmare("text", true, undefined, false, undefined, /* 等28个参数 */);
dream({
  accepts: "text",
  async: true,
  cache: false
});

Valeurs par défaut des paramètres

Il est préférable d'avoir des valeurs par défaut pour les paramètres. Les valeurs par défaut prédéfinies peuvent être remplacées via jQuery.extend() http://. underscorejs.org/#extend) et Object.extend de 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"

Extensibilité

Rappels

Grâce aux rappels, les utilisateurs de l'API peuvent écraser une certaine partie de votre code. Ouvrez certaines fonctions qui nécessitent une personnalisation dans des fonctions de rappel configurables, permettant aux utilisateurs de l'API de remplacer facilement votre code par défaut.

Une fois que l'interface API reçoit un rappel, assurez-vous de le documenter et de fournir des exemples de code.

Événements

Il est préférable de connaître le nom de l'interface des événements. Vous pouvez choisir librement le nom de l'événement pour éviter la duplication des noms avec les événements natifs.

Gestion des erreurs

Toutes les erreurs ne sont pas utiles aux développeurs pour déboguer le code :

// 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

De telles erreurs sont difficiles à déboguer, alors ne faites pas perdre de temps aux développeurs. Dites-leur directement quelle erreur ils ont commise :

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

Remarque : typeof callback === "function" posera des problèmes dans les anciens navigateurs et l'objet sera traité comme une fonction.

Prévisibilité

Une bonne API est prévisible et les développeurs peuvent déduire son utilisation à partir d'exemples.

La détection de fonctionnalités de Modernizr est un exemple :

a) Elle utilise des noms d'attributs qui correspondent exactement aux concepts HTML5, CSS et API

b) Chaque détection individuelle est cohérente. Renvoyer vrai ou les fausses valeurs

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

s'appuient sur des concepts que les développeurs connaissent déjà et qui peuvent être prévisibles.

La syntaxe des sélecteurs de jQuery est un exemple évident. Les sélecteurs CSS1-CSS3 peuvent être utilisés directement dans son moteur de sélection DOM.

$("#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

Coordination proportionnelle

Une bonne API n'est pas forcément une petite API, la taille de l'API doit être proportionnée à ses fonctionnalités.

Par exemple, Moment.js, une bibliothèque bien connue d'analyse et de formatage de dates, peut être qualifiée d'équilibrée. Son API est à la fois concise et fonctionnelle.

Pour une bibliothèque spécifique à une fonction comme Moment.js, il est important de garder l'API ciblée et petite.

Rédiger la documentation de l'API

L'une des tâches les plus difficiles dans le développement de logiciels est de rédiger de la documentation. En fait, tout le monde déteste rédiger de la documentation. Le reproche le plus courant est qu'il n'y a pas de documentation facile à réaliser. utiliser l'outil de documentation.

Voici quelques outils de génération automatique de documents :

• YUIDoc (nécessite Node.js, npm)

• JsDoc Toolkit (nécessite Node.js, npm)

• Markdox (nécessite Node.js, npm)

• Dox (nécessite Node.js, npm)

• Docco (nécessite Node.js, Python, CoffeeScript)

• JSDuck (nécessite Ruby, gem)

• JSDoc 3 (nécessite Java)

Le plus important est de s'assurer que la documentation et le code sont mis à jour simultanément.

Références :

Bonne conception d'API

Concevoir de meilleures API JavaScript

Les secrets d'une conception d'API JavaScript géniale

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

Ce qui précède est le contenu des principes de conception de l'API JavaScript. Pour plus de contenu connexe, veuillez faire attention. vers PHP Chinese Net (www.php.cn) !