Спроектируйте и создайте свою собственную библиотеку JavaScript: советы и рекомендации

Окончательный тест качества API состоит в том, чтобы есть свою собачью еду, использовать свою библиотеку в своих собственных проектах. Попробуйте заменить код приложения своей библиотекой и посмотреть, охватывает ли он все функции, которые вы желаете. Постарайтесь сохранить библиотеку настолько простой, насколько это возможно, при этом сохраняя ее достаточно гибкой, чтобы она работала и для их пограничных случаев, путем настройки (как описано далее в этой статье).

Вот пример того, как может выглядеть реализация или схема строковой библиотеки User-Agent:

// Start with empty UserAgent string var userAgent = new UserAgent; // Create and add first product: EvilCorpBrowser/1.2 (X11; Linux; en-us) var application = new UserAgent.Product('EvilCorpBrowser', '1.2'); application.setComment('X11', 'Linux', 'en-us'); userAgent.addProduct(application); // Create and add second product: Blink/20420101 var engine = new UserAgent.Product('Blink', '20420101'); userAgent.addProduct(engine); // EvilCorpBrowser/1.2 (X11; Linux; en-us) Blink/20420101 userAgent.toString(); // Make some more changes to engine product engine.setComment('Hello World'); // EvilCorpBrowser/1.2 (X11; Linux; en-us) Blink/20420101 (Hello World) userAgent.toString(); 

В зависимости от сложности вашей библиотеки, вы также можете подумать о структурировании. Использование шаблонов проектирования — отличный способ структурировать вашу библиотеку или даже преодолеть некоторые технические проблемы. Это также снижает риск рефакторинга крупных деталей при добавлении новых функций.

Гибкость и настройка

То, что делает библиотеки великолепными, — это гибкость, но также трудно провести грань между тем, что вы можете, и тем, что вы не можете настроить. Прекрасным примером этого является chart.js против D3.js. Оба являются отличными библиотеками для визуализации данных. Chart.js позволяет легко создавать и стилизовать различные типы встроенных диаграмм. Но если вам нужен больший контроль над графикой, D3.js — это то, что вам нужно.

Существуют различные способы управления пользователем: настройка, предоставление открытых методов, а также обратные вызовы и события.

Настройка библиотеки часто выполняется во время инициализации, но некоторые библиотеки позволяют изменять параметры во время выполнения. Параметры часто ограничены крошечными частями, и их изменение не должно делать ничего, кроме обновления этих значений для последующего использования.

 // Configure at initialization var userAgent = new UserAgent({ commentSeparator: ';' }); // Run-time configuration using a public method userAgent.setOption('commentSeparator', '-'); // Run-time configuration using a public property userAgent.commentSeparator = '-'; 

Методы могут быть доступны для взаимодействия с экземпляром, например, для извлечения данных из экземпляра (получателей), для помещения данных в экземпляр (установщиков) и для выполнения действий.

 var userAgent = new UserAgent; // A getter to retrieve comments from all products userAgent.getComments(); // An action to shuffle the order of all products userAgent.shuffleProducts(); 

Обратные вызовы иногда передаются с помощью открытых методов, часто для запуска пользовательского кода после асинхронной задачи.

 var userAgent = new UserAgent; userAgent.doAsyncThing(function asyncThingDone() { // Run code after async thing is done }); 

События имеют большой потенциал. Они похожи на обратные вызовы, за исключением того, что добавление обработчиков событий не должно вызывать действия. События часто используются для обозначения, как вы уже догадались, событий! Подобно обратному вызову, вы можете предоставить дополнительную информацию и вернуть значение для библиотеки для работы.

 var userAgent = new UserAgent; // Validate a product on addition userAgent.on('product.add', function onProductAdd(e, product) { var shouldAddProduct = product.toString().length < 5; // Tell the library to add the product or not return shouldAddProduct; }); 

В некоторых случаях вы можете разрешить пользователям расширять вашу библиотеку. Для этого вы можете предоставить открытый метод или свойство, которое могут заполнять пользователи, во многом как Angular модули ( angular.module('myModule') ) и jQuery’s fn ( jQuery.fn.myPlugin ), или ничего не делать и просто позволить пользователям получать доступ к вашей библиотеке. Пространство имен:

 // AngryUserAgent module // Has access to UserAgent namespace (function AngryUserAgent(UserAgent) { // Create new method .toAngryString() UserAgent.prototype.toAngryString = function() { return this.toString().toUpperCase(); }; })(UserAgent); // Application code var userAgent = new UserAgent; // ... // EVILCORPBROWSER/1.2 (X11; LINUX; EN-US) BLINK/20420101 userAgent.toAngryString(); 

Точно так же это позволяет вам перезаписывать методы.

 // AngryUserAgent module (function AngryUserAgent(UserAgent) { // Store old .toString() method for later use var _toString = UserAgent.prototype.toString; // Overwrite .toString() UserAgent.prototype.toString = function() { return _toString.call(this).toUpperCase(); }; })(UserAgent); var userAgent = new UserAgent; // ... // EVILCORPBROWSER/1.2 (X11; LINUX; EN-US) BLINK/20420101 userAgent.toString(); 

В последнем случае, предоставляя пользователям доступ к пространству имен вашей библиотеки, вы получаете меньше контроля над тем, как определяются расширения / плагины. Чтобы убедиться, что расширения следуют некоторому соглашению, вы можете (и должны) написать документацию.

тестирование

Написание набросков — отличное начало для разработки на основе тестов . Короче говоря, это когда вы записываете критерии в форме тестов, прежде чем писать реальную библиотеку. Если эти тесты проверяют, ведет себя ли функция так, как она должна, и вы пишете ее перед написанием своей библиотеки, стратегия называется поведенческой разработкой . В любом случае, если ваши тесты охватывают все функции вашей библиотеки и ваш код проходит все тесты, вы можете смело предполагать, что ваша библиотека работает.

 describe('Basic usage', function () { it('should generate a single product', function () { // Create a single product var product = new UserAgent.Product('EvilCorpBrowser', '1.2'); product.setComment('X11', 'Linux', 'en-us'); expect(product.toString()) .toBe('EvilCorpBrowser/1.2 (X11; Linux; en-us)'); }); it('should combine several products', function () { var userAgent = new UserAgent; // Create and add first product var application = new UserAgent.Product('EvilCorpBrowser', '1.2'); application.setComment('X11', 'Linux', 'en-us'); userAgent.addProduct(application); // Create and add second product var engine = new UserAgent.Product('Blink', '20420101'); userAgent.addProduct(engine); expect(userAgent.toString()) .toBe('EvilCorpBrowser/1.2 (X11; Linux; en-us) Blink/20420101'); }); it('should update products correctly', function () { var userAgent = new UserAgent; // Create and add first product var application = new UserAgent.Product('EvilCorpBrowser', '1.2'); application.setComment('X11', 'Linux', 'en-us'); userAgent.addProduct(application); // Update first product application.setComment('X11', 'Linux', 'nl-nl'); expect(userAgent.toString()) .toBe('EvilCorpBrowser/1.2 (X11; Linux; nl-nl)'); }); }); 

 # git tag -a [version] -m [version message] git tag -a v1.2.0 -m "Awesome Library v1.2.0" 

 npm init 

 npm publish 

 bower init 

 bower register awesomelib https://github.com/you/awesomelib