Reka dan Bina Perpustakaan JavaScript Anda Sendiri: Petua & Trik

Bina dan siarkan perpustakaan JavaScript anda sendiri: Panduan terperinci

mata teras

• Kosongkan matlamat: Sebelum anda mula membina perpustakaan, jelaskan masalah khusus yang ingin diselesaikan, tetap fokus dan pastikan kegunaannya.
• Reka bentuk API yang berpusat pada pengguna: Reka bentuk perpustakaan anda dengan pusat pengguna akhir untuk menjadikannya mudah dan mudah digunakan, dengan itu meningkatkan penggunaan dan kepuasan pengguna.
• fleksibiliti dan penyesuaian: Menyediakan pilihan penyesuaian melalui konfigurasi, kaedah awam, dan pengendalian acara untuk memenuhi keperluan pengguna yang berbeza. Ujian dan dokumentasi
• : Gunakan rangka kerja seperti mocha atau melati untuk menjalankan ujian menyeluruh dan memastikan dokumentasi komprehensif disediakan untuk membantu memahami dan menggunakan.
• Keserasian Loader Modul: Pastikan perpustakaan anda menyokong pelbagai pemuat modul dengan menggunakan definisi modul sejagat (UMD) atau kaedah yang serupa untuk memaksimumkan keserasian.
• Versioning and Release: Kemas kini dengan versi semantik dan menerbitkan perpustakaan anda kepada pengurus pakej seperti NPM atau Bower untuk mencapai khalayak yang lebih luas.

Artikel ini dikaji semula oleh Adrian Sandu, Vildan Softic dan Dan Prince. Terima kasih kepada semua pengulas rakan sebaya untuk mendapatkan kandungan SitePoint dengan sebaik -baiknya!

Projek sumber terbuka yang popular juga boleh membawa peluang besar. Sebuah syarikat mungkin kagum dengan kualiti pekerjaan anda dan menawarkan pekerjaan kepada anda. Mungkin syarikat akan meminta bantuan untuk mengintegrasikan projek anda ke dalam permohonan mereka. Lagipun, tiada siapa yang tahu perpustakaan anda lebih baik daripada anda.

Bagi ramai orang, ia hanya hobi - menikmati proses menulis kod, membantu orang lain, dan belajar dan berkembang dalam proses. Anda boleh menolak had anda dan mencuba perkara baru.

Skop dan Sasaran

Sebelum menulis baris kod pertama, anda harus jelas tentang tujuan perpustakaan anda - anda perlu menetapkan matlamat. Dengan mereka, anda boleh memberi tumpuan kepada masalah yang ingin anda selesaikan dengan perpustakaan anda. Ingat, perpustakaan anda harus lebih mudah digunakan dan ingat daripada bentuk soalan asal. Semakin mudah API, semakin mudah bagi pengguna untuk belajar menggunakan perpustakaan anda. Quote Falsafah Unix:

Tanya diri anda: Apakah masalah yang diselesaikan oleh perpustakaan anda? Bagaimana anda akan menyelesaikannya? Adakah anda akan menulis semuanya sendiri atau bolehkah anda menggunakan perpustakaan orang lain?

Cuba buat peta jalan tanpa mengira saiz perpustakaan. Senaraikan semua ciri yang anda inginkan dan kemudian keluarkan ciri -ciri seberapa banyak yang anda boleh sehingga anda mempunyai perpustakaan kecil tetapi berfungsi sepenuhnya seperti produk yang paling kecil. Ini akan menjadi versi pertama anda. Dari sana, anda boleh membuat tonggak untuk setiap ciri baru. Pada asasnya, anda memecahkan projek ke dalam kepingan kecil, menjadikan setiap ciri lebih seperti pencapaian dan lebih menyeronokkan. Percayalah, ini akan membuatkan anda waras.

reka bentuk API

Saya secara peribadi benar -benar suka mengendalikan perpustakaan saya dari perspektif pengguna akhir. Anda boleh memanggilnya reka bentuk yang berpusatkan pengguna. Pada asasnya, anda mencipta ringkasan perpustakaan, dengan harapan dapat memikirkan lebih lanjut mengenainya dan menjadikannya lebih mudah bagi sesiapa yang memilih untuk menggunakannya. Pada masa yang sama, anda boleh mempertimbangkan aspek apa yang harus disesuaikan, yang akan dibincangkan kemudian dalam artikel ini.

Ujian kualiti API akhir adalah untuk makan makanan anjing anda sendiri dan menggunakan perpustakaan anda dalam projek anda sendiri. Cuba ganti kod aplikasi dengan perpustakaan anda dan lihat sama ada ia meliputi semua ciri yang anda mahukan. Cuba buat perpustakaan sebagai nipis mungkin sambil menjadikannya cukup fleksibel untuk menjadikannya sesuai untuk situasi yang melampau mereka serta penyesuaian (seperti yang diterangkan kemudian dalam artikel ini).

Berikut adalah apa pelaksanaan atau ringkasan perpustakaan rentetan ejen pengguna mungkin kelihatan seperti:

<code>// 以空的UserAgent字符串开始
var userAgent = new UserAgent;

// 创建并添加第一个产品：EvilCorpBrowser/1.2 (X11; Linux; en-us)
var application = new UserAgent.Product('EvilCorpBrowser', '1.2');
application.setComment('X11', 'Linux', 'en-us');
userAgent.addProduct(application);

// 创建并添加第二个产品：Blink/20420101
var engine = new UserAgent.Product('Blink', '20420101');
userAgent.addProduct(engine);

// EvilCorpBrowser/1.2 (X11; Linux; en-us) Blink/20420101
userAgent.toString();

// 对引擎产品进行更多更改
engine.setComment('Hello World');

// EvilCorpBrowser/1.2 (X11; Linux; en-us) Blink/20420101 (Hello World)
userAgent.toString();
</code>

Bergantung pada kerumitan perpustakaan, anda juga mungkin perlu mempertimbangkan struktur. Menggunakan corak reka bentuk adalah cara terbaik untuk membina perpustakaan atau mengatasi masalah teknikal tertentu. Ia juga mengurangkan risiko refactoring kebanyakan kod apabila menambah ciri -ciri baru.

fleksibiliti dan penyesuaian

Apa yang menjadikan perpustakaan berkuasa adalah fleksibiliti, tetapi juga sukar untuk menarik garis antara apa yang anda boleh menyesuaikan dan apa yang anda tidak dapat. Contoh yang sempurna ialah Chart.js dan D3.Js. Kedua -duanya adalah perpustakaan yang sangat baik untuk menggambarkan data. Chart.js menjadikannya sangat mudah untuk membuat dan menubuhkan pelbagai jenis carta terbina dalam. Walau bagaimanapun, jika anda memerlukan lebih banyak kawalan ke atas grafik, anda perlu menggunakan d3.js. Terdapat beberapa cara untuk memberi kawalan pengguna: konfigurasi, mendedahkan kaedah awam, dan melalui panggilan balik dan acara.

biasanya dilakukan semasa permulaan, tetapi beberapa perpustakaan membolehkan anda mengubah suai pilihan pada masa runtime. Pilihan biasanya terhad kepada butiran, menukar pilihan ini tidak boleh melakukan apa -apa kecuali mengemas kini nilai -nilai ini untuk kegunaan kemudian.

<code>// 在初始化时配置
var userAgent = new UserAgent({
  commentSeparator: ';'
});

// 使用公共方法进行运行时配置
userAgent.setOption('commentSeparator', '-');

// 使用公共属性进行运行时配置
userAgent.commentSeparator = '-';
</code>

<code>var userAgent = new UserAgent;

// 获取器，用于从所有产品中检索注释
userAgent.getComments();

// 用于打乱所有产品顺序的操作
userAgent.shuffleProducts();
</code>

<code>var userAgent = new UserAgent;

userAgent.doAsyncThing(function asyncThingDone() {
  // 异步操作完成后运行代码
});
</code>

<code>var userAgent = new UserAgent;

// 验证添加的产品
userAgent.on('product.add', function onProductAdd(e, product) {
  var shouldAddProduct = product.toString().length 
  // 告诉库添加或不添加产品
  return shouldAddProduct;
});
</code>

<code>// AngryUserAgent 模块
// 可以访问UserAgent命名空间
(function AngryUserAgent(UserAgent) {

  // 创建新的方法 .toAngryString()
  UserAgent.prototype.toAngryString = function() {
    return this.toString().toUpperCase();
  };

})(UserAgent);

// 应用程序代码
var userAgent = new UserAgent;
// ...

// EVILCORPBROWSER/1.2 (X11; LINUX; EN-US) BLINK/20420101
userAgent.toAngryString();
</code>

<code>// AngryUserAgent 模块
(function AngryUserAgent(UserAgent) {

  // 存储旧的 .toString() 方法以供以后使用
  var _toString = UserAgent.prototype.toString;

  // 覆盖 .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();
</code>

ujian

Menulis gambaran keseluruhan adalah permulaan yang baik untuk pembangunan yang didorong oleh ujian. Singkatnya, ini adalah standard untuk menulis borang ujian sebelum anda menulis perpustakaan sebenar. Jika ujian ini menyemak bahawa ciri bertindak seperti yang diharapkan dan anda menulis ujian ini sebelum menulis perpustakaan, strategi itu dipanggil pembangunan yang didorong oleh tingkah laku. Sama ada cara, jika ujian anda meliputi setiap ciri di perpustakaan dan kod anda melepasi semua ujian, anda boleh menganggap bahawa perpustakaan anda boleh berfungsi.

Jani Hartikainen menerangkan cara menulis ujian unit dalam "Menggunakan Mocha dan Chai untuk Unit Menguji JavaScript anda". Dalam "Ujian JavaScript dengan Jasmine, Travis, dan Karma", Tim Evko menunjukkan bagaimana untuk menubuhkan saluran paip ujian yang hebat dengan rangka kerja lain yang dipanggil Jasmine. Kedua -dua kerangka ujian ini sangat popular, tetapi terdapat banyak jenis kerangka lain.

Ringkasan yang saya buat sebelum ini dalam artikel ini telah mengulas mengenai output yang diharapkan. Di sinilah semua ujian bermula: bermula dengan jangkaan. Ujian Jasmine untuk perpustakaan saya adalah seperti berikut:

<code>// 以空的UserAgent字符串开始
var userAgent = new UserAgent;

// 创建并添加第一个产品：EvilCorpBrowser/1.2 (X11; Linux; en-us)
var application = new UserAgent.Product('EvilCorpBrowser', '1.2');
application.setComment('X11', 'Linux', 'en-us');
userAgent.addProduct(application);

// 创建并添加第二个产品：Blink/20420101
var engine = new UserAgent.Product('Blink', '20420101');
userAgent.addProduct(engine);

// EvilCorpBrowser/1.2 (X11; Linux; en-us) Blink/20420101
userAgent.toString();

// 对引擎产品进行更多更改
engine.setComment('Hello World');

// EvilCorpBrowser/1.2 (X11; Linux; en-us) Blink/20420101 (Hello World)
userAgent.toString();
</code>

Sebaik sahaja anda berpuas hati dengan versi pertama reka bentuk API, sudah tiba masanya untuk mula memikirkan seni bina dan bagaimana perpustakaan anda akan digunakan.

keserasian loader modul

anda mungkin atau tidak boleh menggunakan pemuat modul. Walau bagaimanapun, pemaju yang memilih untuk melaksanakan perpustakaan anda boleh menggunakannya, jadi anda mahu perpustakaan anda bersesuaian dengan Loader Modul. Tetapi yang mana? Bagaimanakah anda memilih antara CommonJs, RequireJs, AMD dan pemuat modul lain?

Sebenarnya, anda tidak perlu memilih! Definisi Modul Universal (UMD) adalah satu lagi strategi yang direka untuk menyokong pelbagai pemuat modul. Anda boleh menemui versi coretan kod yang berbeza dalam talian, dan anda juga boleh mencari versi UMD yang berbeza di repositori UMD Github untuk menjadikan perpustakaan anda serasi dengan UMD. Mulakan perpustakaan anda dengan salah satu templat, atau tambahkan UMD dengan alat binaan kegemaran anda, dan anda tidak perlu bimbang tentang pemuat modul.

Jika anda ingin menggunakan sintaks import/eksport ES2015, saya sangat mengesyorkan menggunakan Babel untuk disusun ke ES5, digabungkan dengan plugin UMD Babel. Dengan cara ini, anda boleh menggunakan ES2015 dalam projek anda semasa masih menjana perpustakaan yang sesuai untuk semua orang.

Dokumen

Saya benar -benar memihak kepada dokumentasi menyeluruh semua projek, tetapi ini sering dianggap banyak kerja, ditangguhkan dan akhirnya dilupakan.

Maklumat Asas

Dokumentasi harus selalu bermula dengan maklumat asas, seperti nama projek dan perihalan. Ini akan membantu orang lain memahami fungsi perpustakaan anda dan sama ada ia berfungsi untuk mereka.

Anda boleh memberikan maklumat tambahan, seperti skop dan matlamat, untuk memaklumkan pengguna dengan lebih baik, serta peta jalan supaya mereka tahu apa yang akan berlaku pada masa akan datang atau bagaimana mereka dapat menyumbang.

API, Tutorial dan Contoh

Sudah tentu, anda perlu membiarkan pengguna mengetahui cara menggunakan perpustakaan anda. Ini bermula dengan dokumentasi API. Tutorial dan contoh adalah penambahan yang hebat, tetapi menulis ini boleh mengambil banyak kerja. Walau bagaimanapun, ini tidak berlaku dengan dokumentasi sebaris. Ini adalah komen yang boleh dihuraikan dan ditukar ke halaman dokumen menggunakan JSDOC.

Metaquest

Sesetengah pengguna mungkin mahu menukar perpustakaan anda. Dalam kebanyakan kes, ini akan menjadi sumbangan, tetapi sesetengah orang mungkin ingin membuat versi tersuai untuk kegunaan peribadi. Bagi pengguna ini, dokumen yang mengandungi metatasks berguna, seperti senarai arahan untuk perpustakaan bangunan, ujian menjalankan, menjana, menukar, atau memuat turun data, dll.

Sumbangan

Sumbangan sangat penting apabila anda membuka sumber perpustakaan anda. Untuk membimbing penyumbang, anda boleh menambah dokumentasi kepadanya, menerangkan langkah -langkah untuk menyumbang dan kriteria yang perlu dipenuhi. Ini akan memudahkan anda mengkaji semula dan menerima sumbangan dan memudahkan mereka menyumbang dengan betul.

had

Terakhir tetapi tidak kurang, sila sertakan lesen. Secara teknikal, jika anda memilih untuk tidak memasukkan lesen, ia masih berhak cipta, tetapi tidak semua orang tahu ini.

Saya dapati pilihanikence.com untuk menjadi sumber yang hebat untuk anda memilih lesen tanpa menjadi pakar undang -undang. Selepas memilih lesen, simpan teks dalam fail Lesen.TXT dalam direktori root projek.

pek dan tambahkan busur

versi adalah penting untuk perpustakaan yang baik. Jika anda memilih untuk membuat perubahan yang ketara, pengguna mungkin mahu terus menggunakan versi yang berfungsi untuk mereka.

Kriteria penamaan versi de facto semasa adalah kawalan versi semantik, atau Semver. Versi Semver terdiri daripada tiga nombor, masing -masing mewakili perubahan yang berbeza: versi utama, kecil, dan patch.

tambahkan versi/versi ke repositori git anda

Jika anda mempunyai repositori git, anda boleh menambah nombor versi ke repositori. Anda boleh memikirkannya sebagai gambar repositori. Kami menyebutnya label. Untuk membuat tag, buka terminal dan jenis:

<code>// 以空的UserAgent字符串开始
var userAgent = new UserAgent;

// 创建并添加第一个产品：EvilCorpBrowser/1.2 (X11; Linux; en-us)
var application = new UserAgent.Product('EvilCorpBrowser', '1.2');
application.setComment('X11', 'Linux', 'en-us');
userAgent.addProduct(application);

// 创建并添加第二个产品：Blink/20420101
var engine = new UserAgent.Product('Blink', '20420101');
userAgent.addProduct(engine);

// EvilCorpBrowser/1.2 (X11; Linux; en-us) Blink/20420101
userAgent.toString();

// 对引擎产品进行更多更改
engine.setComment('Hello World');

// EvilCorpBrowser/1.2 (X11; Linux; en-us) Blink/20420101 (Hello World)
userAgent.toString();
</code>

Banyak perkhidmatan (seperti GitHub) akan memberikan gambaran keseluruhan semua versi dan pautan muat turun untuk setiap versi.

Terbitkan ke repositori awam

<code>// 在初始化时配置
var userAgent = new UserAgent({
  commentSeparator: ';'
});

// 使用公共方法进行运行时配置
userAgent.setOption('commentSeparator', '-');

// 使用公共属性进行运行时配置
userAgent.commentSeparator = '-';
</code>

<code>var userAgent = new UserAgent;

// 获取器，用于从所有产品中检索注释
userAgent.getComments();

// 用于打乱所有产品顺序的操作
userAgent.shuffleProducts();
</code>

<code>// 以空的UserAgent字符串开始
var userAgent = new UserAgent;

// 创建并添加第一个产品：EvilCorpBrowser/1.2 (X11; Linux; en-us)
var application = new UserAgent.Product('EvilCorpBrowser', '1.2');
application.setComment('X11', 'Linux', 'en-us');
userAgent.addProduct(application);

// 创建并添加第二个产品：Blink/20420101
var engine = new UserAgent.Product('Blink', '20420101');
userAgent.addProduct(engine);

// EvilCorpBrowser/1.2 (X11; Linux; en-us) Blink/20420101
userAgent.toString();

// 对引擎产品进行更多更改
engine.setComment('Hello World');

// EvilCorpBrowser/1.2 (X11; Linux; en-us) Blink/20420101 (Hello World)
userAgent.toString();
</code>

<code>// 在初始化时配置
var userAgent = new UserAgent({
  commentSeparator: ';'
});

// 使用公共方法进行运行时配置
userAgent.setOption('commentSeparator', '-');

// 使用公共属性进行运行时配置
userAgent.commentSeparator = '-';
</code>

Atas ialah kandungan terperinci Reka dan Bina Perpustakaan JavaScript Anda Sendiri: Petua & Trik. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!