JavaScript API 디자인 원칙

얼마 전에 네이티브 모듈 API를 구성하고 최적화했기 때문에(iOS 및 Android 모듈은 JavaScript 인터페이스로 캡슐화됨) JavaScript API 디자인에 대한 여러 기사를 연구했지만 많은 도움이 되었습니다. 여기에 기록해 두세요.

좋은 API 디자인: 자기 설명적이면서 추상화 목표를 달성합니다.

잘 설계된 API를 사용하면 개발자는 매뉴얼과 문서를 자주 보관할 필요가 없고 기술 지원 커뮤니티를 자주 방문할 필요도 없이 빠르게 시작할 수 있습니다.

부드러운 인터페이스

메서드 체인: 부드럽고 읽기 쉽고 이해하기 쉽습니다

rree

설정 및 가져오기 작업을 하나로 결합할 수 있는 메서드가 많을수록 더 어려워집니다. 문서는 다음과 같습니다.

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

일관성

관련 인터페이스는 일관된 스타일을 유지합니다. 완전한 API 세트가 익숙하고 편안한 느낌을 전달한다면 개발자는 새로운 도구에 훨씬 쉽게 적응할 수 있습니다.

이름 지정: 짧고 자기 설명적이며 가장 중요하게는 일관성이 있습니다

“컴퓨터 과학에는 두 가지 어려운 문제가 있습니다. 캐시 무효화와 이름 지정입니다."
"다음이 있습니다. 컴퓨터 과학에서 두 가지 문제는 바로 캐시 무효화와 명명 문제입니다."
— Phil Karlton

좋아하는 문구를 골라 그대로 사용하세요. 스타일을 선택하고 그대로 유지하세요.

매개변수 처리

제공한 메소드를 사람들이 어떻게 사용하는지 고려해야 합니다. 왜 반복적으로 호출되나요? 귀하의 API는 개발자가 중복 호출을 줄이는 데 어떻게 도움이 됩니까?
지도 매핑 매개변수, 콜백 또는 직렬화된 속성 이름을 수신하면 API를 더 깔끔하게 만들 수 있을 뿐만 아니라 사용하기 더 편안하고 효율적으로 만듭니다.

jQuery의 css() 메서드는 DOM 요소의 스타일을 설정할 수 있습니다.

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

이 메서드는 JSON 개체를 허용할 수 있습니다.

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

처리 유형

정의 방법 , 수신할 수 있는 매개변수를 결정해야 합니다. 사람들이 우리 코드를 어떻게 사용하는지 모르지만, 좀 더 미래 지향적으로 지원하는 매개변수 유형을 고려해 볼 수 있습니다. 전달된 매개변수의 유형(문자열, 숫자, 부울)을 확인해야 하는 경우 다음과 같이 변환할 수 있습니다.

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

정의되지 않은 핸들

API 더욱 강력해졌습니다. 정의되지 않은 실제 값이 전달되는지 확인해야 하는 경우 인수 개체를 확인할 수 있습니다.

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

매개변수 이름 지정

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

Event.initMouseEvent 이 방법은 정말 이상합니다. . 문서를 읽지 않으면 누가 각 매개변수의 의미를 알 수 있습니까?

각 매개변수에 이름을 지정하고 기본값을 할당합니다. 예를 들어

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

ES6 또는 Harmony에는 기본 매개변수 값과 나머지 매개변수가 있습니다.

매개변수가 JSON 개체를 수신합니다

여러 매개변수를 받는 대신 JSON 개체를 받는 것이 좋습니다.

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

호출하는 것도 더 간단합니다.

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

매개변수 기본값

jQuery.extend() http://underscorejs.org/#extend) 및 Protoype의 Object.extend를 통해 매개변수에 대한 기본값을 갖는 것이 가장 좋습니다. 기본값은 재정의될 수 있습니다.

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

확장성

콜백

콜백을 통해 API 사용자는 코드의 특정 부분을 재정의할 수 있습니다. 사용자 정의가 필요한 일부 기능을 구성 가능한 콜백 함수로 열어 API 사용자가 기본 코드를 쉽게 재정의할 수 있도록 합니다.

API 인터페이스가 콜백을 수신하면 이를 문서화하고 코드 예제를 제공하세요.

이벤트

이벤트 이름은 네이티브 이벤트와 중복되지 않도록 자유롭게 선택하는 것이 가장 좋습니다.

오류 처리

모든 오류가 개발자가 코드를 디버그하는 데 유용한 것은 아닙니다.

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

이러한 오류는 디버깅하기 힘들므로 개발자의 시간을 낭비하지 말고 직접 알려주세요. 그들이 저지른 실수:

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"

참고: 콜백 유형 === "함수"는 이전 브라우저에서 문제를 일으키고 객체는 함수로 처리됩니다.

예측성

좋은 API는 예측 가능하며 개발자는 예제를 기반으로 사용법을 추론할 수 있습니다.

Modernizr의 기능 감지는 예입니다.

a) 사용하는 속성 이름은 HTML5, CSS 개념 및 API와 정확히 일치합니다.

b) 각 개별 감지는 일관됩니다. 또는 거짓 값

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

는 개발자가 이미 익숙하고 예측할 수 있는 개념에 의존합니다.

jQuery의 선택기 구문은 CSS1-CSS3 선택기를 DOM 선택기 엔진에서 직접 사용할 수 있는 확실한 예입니다.

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

비례적인 조화

좋은 API는 반드시 작은 API일 필요는 없으며, API의 크기는 기능에 비례해야 합니다.

예를 들어, 잘 알려진 날짜 구문 분석 및 형식 지정 라이브러리인 Moment.js의 API는 간결하고 기능적입니다.

Moment.js와 같은 함수별 라이브러리의 경우 API를 집중적이고 작게 유지하는 것이 중요합니다.

API 문서 작성

소프트웨어 개발에서 가장 어려운 작업 중 하나는 문서 작성입니다. 사실 가장 일반적인 불만은 문서 작성이 쉽지 않다는 것입니다. 문서화 도구를 사용하세요.

다음은 일부 자동 문서 생성 도구입니다.

• YUIDoc(Node.js, npm 필요)

• JsDoc Toolkit (Node.js, npm 필요)

• Markdox(Node.js, npm 필요)

• Dox(Node.js, npm 필요)

• Docco(Node.js, Python, CoffeeScript 필요)

• JSDuck(Ruby, gem 필요)

• JSDoc 3(Java 필요)

가장 중요한 것은 문서와 코드가 동시에 업데이트되는지 확인하는 것입니다.

참고 자료:

좋은 API 디자인

더 나은 JavaScript API 디자인

멋진 JavaScript API 디자인의 비밀

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

위 내용은 JavaScript API 디자인 원칙에 관한 내용입니다. PHP 중국어 넷(www.php.cn)으로!