Stajyerlerin Amacı
Externs, Closure Compiler'a gelişmiş derleme sırasında yeniden adlandırılmaması gereken sembollerin adlarını bildiren bildirimlerdir. Bu semboller genellikle derleme dışındaki kodlarla (ör. yerel kod veya üçüncü taraf kitaplıkları) tanımlandığı için "extern" olarak adlandırılır. Bu nedenle, Closure Compiler'ın bu sembolleri kullanımınızı tür denetimi yapabilmesi için harici değişkenlerde genellikle tür açıklamaları da bulunur.
Genel olarak, extern'leri uygulayıcı ile derlenmiş bir kod parçasının tüketicileri arasındaki bir API sözleşmesi olarak düşünmek en iyisidir. The externs define what the implementor promises to supply, and what the consumers can depend on using. Her iki tarafın da sözleşmenin bir kopyasına ihtiyacı vardır.
Extern'ler, diğer dillerdeki başlık dosyalarına benzer.
Externs Söz Dizimi
Externs, Closure Compiler için açıklama eklenmiş normal JavaScript'e çok benzeyen dosyalardır. Aradaki temel fark, içeriklerinin derlenmiş çıktının bir parçası olarak hiçbir zaman yazdırılmamasıdır. Bu nedenle, değerlerin hiçbiri anlamlı değildir. Yalnızca adlar ve türler anlamlıdır.
Aşağıda, basit bir kitaplık için stajyerler dosyası örneği verilmiştir.
// The `@externs` annotation is the best way to indicate a file contains externs. /** * @fileoverview Public API of my_math.js. * @externs */ // Externs often declare global namespaces. const myMath = {}; // Externs can declare functions, most importantly their names. /** * @param {number} x * @param {number} y * @return {!myMath.DivResult} */ myMath.div = function(x, y) {}; // Note the empty body. // Externs can contain type declarations, such as classes and interfaces. /** The result of an integer division. */ myMath.DivResult = class { // Constructors are special; member fields can be declared in their bodies. constructor() { /** @type {number} */ this.quotient; /** @type {number} */ this.remainder; } // Methods can be declared as usual; their bodies are meaningless though. /** @return {!Array<number>} */ toPair() {} }; // Fields and methods can also be declared using prototype notation. /** * @override * @param {number=} radix */ myMath.DivResult.prototype.toString = function(radix) {};
--externs Bayrağı
Genellikle, @externs ek açıklaması, derleyiciye bir dosyanın harici değişkenler içerdiğini bildirmenin en iyi yoludur. Bu tür dosyalar, --js komut satırı işareti kullanılarak normal kaynak dosyaları olarak eklenebilir.
Ancak harici dosyaları belirtmenin başka bir yolu daha vardır. Harici dosyaları açıkça iletmek için --externs komut satırı işareti kullanılabilir. Bu yöntem önerilmez.
Externs'i kullanma
Yukarıdaki harici işlevler aşağıdaki şekilde kullanılabilir.
/** * @fileoverview Do some math. */ /** * @param {number} x * @param {number} y * @return {number} */ export function greatestCommonDivisor(x, y) { while (y != 0) { const temp = y; // `myMath` is a global, it and `myMath.div` are never renamed. const result = myMath.div(x, y); // `remainder` is also never renamed on instances of `DivResult`. y = result.remainder; x = temp; } return x; }
Dışa Aktarma Amacı
Dışa aktarmalar, derlemeden sonra sembollere tutarlı adlar vermenin bir başka mekanizmasıdır. Bu türler, stajyerlerden daha az faydalıdır ve genellikle kafa karıştırıcıdır. Basit durumlar dışında bu tür ifadelerden kaçınmak en iyisidir.
Dışa aktarma işlemleri, Closure Compiler'ın dize değişmezlerini değiştirmediği gerçeğine dayanır. Bir nesneyi değişmez değer kullanılarak adlandırılmış bir özelliğe atadığınızda, nesne derlemeden sonra bile bu özellik adı aracılığıyla kullanılabilir.
Aşağıda basit bir örnek verilmiştir.
/** * @fileoverview Do some math. */ // Note that the concept of module exports is totally unrelated. /** @return {number} */ export function myFunction() { return 5; } // This assignment ensures `myFunctionAlias` will be a global alias exposing `myFunction`, // even after compilation. window['myFunctionAlias'] = myFunction;
Closure Library kullanıyorsanız dışa aktarmalar goog.exportSymbol ve goog.exportProperty işlevleri kullanılarak da bildirilebilir.
Bu işlevler hakkında daha fazla bilgiyi Closure Library belgelerinde bulabilirsiniz. Ancak, bu öğelerin özel derleyici desteği olduğunu ve derlenmiş çıktıda tamamen dönüştürüleceğini unutmayın.
Dışa aktarmayla ilgili sorunlar
Dışa aktarmalar, tüketicilerin başvurabileceği yalnızca bir takma ad oluşturmaları bakımından dışa aktarılanlardan farklıdır. Derlenmiş kodda, dışa aktarılan sembol yeniden adlandırılmaya devam eder. Bu nedenle, dışa aktarılan semboller sabit olmalıdır. Aksi takdirde, kodunuzda yeniden atama yapıldığında, kullanıma sunulan takma ad yanlış öğeyi işaret eder.
Yeniden adlandırmadaki bu incelik, özellikle dışa aktarılan örnek özellikleri açısından karmaşıktır.
Teorik olarak, uzun adlar kodunuzda daha kısa adlarla değiştirilebildiği için dışa aktarmalar, harici değişkenlere kıyasla daha küçük kod boyutuna izin verebilir. Uygulamada, bu iyileştirmeler genellikle çok küçük olur ve dışa aktarma işlemlerinin oluşturduğu kafa karışıklığını haklı çıkarmaz.
Ayrıca, dışa aktarmalar, tüketicilerin stajyerlerin yaptığı gibi izleyebileceği bir API sağlamaz. Dışa aktarmalarla karşılaştırıldığında, stajyerler kullanıma sunmayı planladığınız sembolleri, türlerini belgeler ve kullanım bilgileri ekleyebileceğiniz bir yer sağlar. Ayrıca, tüketicileriniz Closure Compiler'ı da kullanıyorsa derleme için harici dosyalar gerekir.