JavaScript API 디자인 원칙에 대한 자세한 소개

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

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

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

부드러운 인터페이스

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

//常见的 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 및 get 작업을 다음과 같이 결합할 수 있습니다. one ;메서드가 많을수록 문서 작성이 더 어려워질 수 있습니다

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

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

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

일관성

관련 인터페이스는 일관된 스타일을 유지합니다. 친숙함과 편안함 덕분에 개발자가 새로운 도구에 쉽게 적응할 수 있습니다. <… ”

“컴퓨터 공학에는 캐시 무효화와 이름 지정 문제라는 두 가지 문제만 있습니다.”

—Phil Karlton

좋아하는 단어를 선택하고 계속 사용하세요. 스타일을 선택하고 그대로 유지하세요.

매개변수 처리

제공한 메소드를 사람들이 어떻게 사용하는지 고려해야 합니다. 왜 반복적으로 호출됩니까? 귀하의 API는 개발자가 중복 호출을 줄이는 데 어떻게 도움이 됩니까?

지도 매핑 매개변수, 콜백 또는 직렬화된 속성 이름을 수신하면 API를 더 깔끔하게 만들 수 있을 뿐만 아니라 사용하기 더 편안하고 효율적으로 만듭니다.

jQuery의

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

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

이 메서드는 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);

처리 유형css()

정의 방법 , 수신할 수 있는 매개변수를 결정해야 합니다. 사람들이 우리 코드를 어떻게 사용하는지 모르지만, 좀 더 미래 지향적으로 지원하는 매개변수 유형을 고려해 볼 수 있습니다.

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

단 6줄의 코드만으로 우리의 방법은

객체, 숫자 타임스탬프는 물론

과 같은 문자열까지 수용할 수 있을 만큼 강력합니다. 들어오는 매개변수 유형(문자열, 숫자, 부울)은 다음과 같이 변환할 수 있습니다.

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

DateHandle unundefinedSat Sep 08 2012 15:34:35 GMT+0200 (CEST)

API를 더욱 강력하게 만들려면 이것이 true인지 식별해야 합니다.

값이 전달되면

개체를 확인할 수 있습니다.

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

매개변수 이름 지정

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

undefinedEvent.initMouseEvent 이 방법은 정말 미친 짓입니다. 문서는 무엇을 의미하나요? arguments

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

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 또는 Harmony에는 기본 매개변수 값과 나머지 매개변수가 있습니다.

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

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

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

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

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

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

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

매개변수 기본값

매개변수에 대한 기본값을 갖는 것이 가장 좋습니다. 미리 설정된 기본값은 jQuery.extend() http://www.php.cn/) 및 프로토타입의 Object.extend.

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

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

이벤트

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

오류 처리

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

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

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

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

참고:

는 이전 브라우저에서 문제를 일으키고

는

으로 처리됩니다.

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

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

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

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

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

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

jQuery의 선택기 구문은 CSS1-CSS3 선택기를 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

비례적인 조화

좋은 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 디자인의 비밀

위 내용은 JavaScript API 디자인 원칙에 대한 자세한 소개의 상세 내용입니다. 자세한 내용은 PHP 중국어 웹사이트의 기타 관련 기사를 참조하세요!