URLPattern, web platformuna yönlendirme sağlar

Yaygın kalıp eşleştirme kullanım alanlarını standartlaştırmaya yönelik bir yaklaşım.

Jeff Posnick

Arka plan

Yönlendirme, her web uygulamasının temel bir parçasıdır. Yönlendirme, temel olarak bir URL almayı, ona bir kalıp eşleştirme veya uygulamaya özel başka bir mantık uygulamayı ve ardından, genellikle sonuca göre web içeriğini görüntülemeyi içerir. Yönlendirme birkaç şekilde uygulanabilir: Bazen diskteki dosyaların yolunu eşleyen bir sunucuda çalışan kod veya geçerli konumda değişiklik yapılmasını bekleyen ve görüntülenecek karşılık gelen bir DOM parçasını oluşturan tek sayfalık bir uygulamadaki mantıktır.

Tek bir kesin standart olmasa da web geliştiricileri, regular expressions ile birçok ortak yöne sahip URL yönlendirme kalıplarını ifade etmek için ortak bir söz dizimine yönelmiş, ancak yol segmentlerini eşleştiren jetonlar gibi bazı alana özgü eklemeler yapmıştır. Express ve Ruby on Rails gibi popüler sunucu tarafı çerçeveler bu söz dizimini (veya ona çok yakın bir şeyi) kullanır ve JavaScript geliştiricileri, path-to-regexp veya regexpparam gibi modülleri kullanarak bu mantığı kendi kodlarına ekleyebilir.

URLPattern, bu çerçeveler tarafından oluşturulan temeli üzerine alan web platformuna yapılan bir eklemedir. Amacı; joker karakterler, adlandırılmış jeton grupları, normal ifade grupları ve grup değiştiricileri için destek de dahil olmak üzere bir yönlendirme kalıbı söz dizimini standartlaştırmaktır. Bu söz dizimiyle oluşturulan URLPattern örnekleri, tam URL'ler veya bir URL pathname ile eşleştirme, jeton ve grup eşleşmeleriyle ilgili bilgileri döndürme gibi yaygın yönlendirme görevlerini gerçekleştirebilir.

Doğrudan web platformunda URL eşleştirmesi sağlamanın bir başka yararı da ortak bir söz diziminin, URL'lerle eşleşmesi gereken diğer API'lerle de paylaşılabilmesidir.

Tarayıcı desteği ve çoklu dolgular

URLPattern, Chrome ile Edge 95 ve sonraki sürümlerde varsayılan olarak etkindir.

urlpattern-polyfill kitaplığı, URLPattern arayüzünü yerleşik desteği olmayan Node gibi tarayıcılarda veya ortamlarda kullanmak için bir yol sağlar. Çoklu dolguyu kullanıyorsanız özelliği yalnızca mevcut ortamda desteklenmemesi durumunda yüklediğinizden emin olmak için özellik algılamayı kullandığınızdan emin olun. Aksi takdirde, URLPattern ürününün önemli avantajlarından birini kaybedersiniz: yani desteklenen ortamların, kullanmak için ek kod indirip ayrıştırmasına gerek kalmaz.

if (!(globalThis && 'URLPattern' in globalThis)) {
  // URLPattern is not available, so the polyfill is needed.
}

Söz dizimi uyumluluğu

URLPattern için yol gösterici felsefe, yeniden buluşlardan kaçınmaktır. Express veya Ruby on Rails'de kullanılan yönlendirme söz dizimini zaten biliyorsanız yeni bir şey öğrenmenize gerek yoktur. Ancak popüler yönlendirme kitaplıklarındaki söz dizimleri arasındaki küçük farklılıklar nedeniyle bir şeyin temel söz dizimi olarak seçilmesi gerekiyordu ve URLPattern tasarımcıları, başlangıç noktası olarak path-to-regexp kalıbı söz dizimini kullanmaya karar verdi (ancak API yüzeyini kullanmadı).

Bu karar, path-to-regexp cihazının mevcut koruyucusuyla yakından görüşüldükten sonra alınmıştır.

Desteklenen söz diziminin temelini öğrenmenin en iyi yolu path-to-regexp ile ilgili belgelere bakmaktır. MDN'de yayınlanması planlanan dokümanları şu anda GitHub'daki ana sayfasında okuyabilirsiniz.

Ek özellikler

URLPattern, yönlendirme kitaplıkları arasında yaygın olmayan bir özelliği desteklediğinden URLPattern söz dizimi, path-to-regexp tarafından desteklenen özelliklerin üst kümesidir: ana makine adlarındaki joker karakterler dahil kaynakları eşleştirme. Diğer yönlendirme kitaplıklarının çoğu yalnızca yol adı ve bazen de bir URL'nin arama veya karma bölümüyle ilgilenir. URL'ler yalnızca bağımsız bir web uygulaması içinde aynı kaynak yönlendirmesi için kullanıldığından hiçbir zaman URL'nin kaynak kısmını kontrol etmeleri gerekmez.

Kaynakların dikkate alınması, Service Worker'ın fetch etkinlik işleyicisi içinde kaynaklar arası isteklerin yönlendirilmesi gibi ek kullanım alanları için kapı açar. Yalnızca aynı kaynaklı URL'leri yönlendiriyorsanız bu ek özelliği etkili bir şekilde yok sayabilir ve URLPattern öğesini diğer kitaplıklar gibi kullanabilirsiniz.

Örnekler

Kalıbı oluşturma

Bir URLPattern oluşturmak için kurucusunu dizeleri veya özellikleri, eşleştirilecek kalıpla ilgili bilgiler içeren bir nesne iletin.

Bir nesnenin iletilmesi, her bir URL bileşenini eşleştirmek için hangi kalıbın kullanılacağı konusunda en açık kontrolü sağlar. En ayrıntılı haliyle,

const p = new URLPattern({
  protocol: 'https',
  username: '',
  password: '',
  hostname: 'example.com',
  port: '',
  pathname: '/foo/:image.jpg',
  search: '*',
  hash: '*',
});

Bir mülk için boş dize sağlanması, yalnızca URL'nin karşılık gelen bölümü ayarlanmadığında eşleşir. * joker karakteri, URL'nin belirli bir bölümü için her değerle eşleşir.

Oluşturucu, daha basit kullanım için çeşitli kısayollar sunar. search ve hash özelliklerini ya da diğer özellikleri tamamen atlamak, bunları '*' joker karakterine ayarlamakla eşdeğerdir. Yukarıdaki örnek aşağıdaki şekilde

const p = new URLPattern({
  protocol: 'https',
  username: '',
  password: '',
  hostname: 'example.com',
  port: '',
  pathname: '/foo/:image.jpg',
});

Ek bir kısayol olarak, kaynakla ilgili tüm bilgiler tek bir mülkte (baseURL) sağlanabilir. Böylece,

const p = new URLPattern({
  pathname: '/foo/:image.jpg',
  baseURL: 'https://example.com',
});

Bu örneklerin tümünde, kullanım alanınızın eşleşen kaynaklar içerdiği varsayılır. Kaynağı hariç tutarak yalnızca URL'nin diğer bölümleriyle eşleştirme yapmak istiyorsanız (birçok "geleneksel" tek kaynak yönlendirme senaryosunda olduğu gibi) kaynak bilgilerini tamamen atlayıp yalnızca pathname, search ve hash özelliklerinin bir kombinasyonunu sağlayabilirsiniz. Daha önce olduğu gibi, atlanan özellikler * joker karakter kalıbına ayarlanmış gibi değerlendirilir.

const p = new URLPattern({pathname: '/foo/:image.jpg'});

Bir nesneyi oluşturucuya geçirmeye alternatif olarak bir veya iki dize sağlayabilirsiniz. Bir dize sağlanırsa kaynağı eşleştirmek için kullanılan kalıp bilgileri de dahil olmak üzere tam URL kalıbını temsil etmelidir. İki dize sağlarsanız ikinci dize baseURL olarak kullanılır ve ilk dize bu tabana göre değerlendirilir.

İster bir ister iki dize sağlanmış olsun, URLPattern oluşturucusu tam URL kalıbını ayrıştırarak bunu URL bileşenlerine ayırır ve daha büyük kalıbın her bir bölümünü karşılık gelen bileşenle eşler. Bu da, dizelerle oluşturulan her URLPattern öğesinin, bir nesneyle oluşturulmuş eşdeğer bir URLPattern ile aynı şekilde temsil edileceği anlamına gelir. Dize oluşturucu, daha az ayrıntılı bir arayüzü tercih edenler için bir kısayoldur.

const p = new URLPattern('https://example.com/foo/:image.jpg?*#*');

URLPattern oluşturmak için dizeleri kullanırken unutulmaması gereken birkaç nokta vardır.

URLPattern oluşturmak için bir nesne kullanırken bir özelliğin dışarıda bırakılması, söz konusu özellik için * joker karakteri sağlamaya eşdeğerdir. Tam URL dize kalıbı ayrıştırıldığında, URL bileşenlerinden birinde bir değer eksikse bileşenin özelliği '' olarak ayarlanmış gibi değerlendirilir. Bu özellik, yalnızca bileşen boş olduğunda eşleşir.

Dizeleri kullanırken, oluşturulan URLPattern içinde kullanılmasını istiyorsanız joker karakterleri açıkça eklemeniz gerekir.

// p1 and p2 are equivalent.
const p1 = new URLPattern('/foo', location.origin);
const p2 = new URLPattern({
  protocol: location.protocol,
  hostname: location.hostname,
  pathname: '/foo',
  search: '',
  hash: '',
});

// p3 and p4 are equivalent.
const p3 = new URLPattern('/foo?*#*', location.origin);
const p4 = new URLPattern({
  protocol: location.protocol,
  hostname: location.hostname,
  pathname: '/foo',
});

Bir dize kalıbını bileşenlerine ayrıştırmanın muhtemelen belirsiz olduğunu da unutmamalısınız. URL'lerde bulunan : gibi karakterler vardır ancak kalıp eşleştirme söz diziminde de özel anlamları vardır. Bu belirsizliği önlemek için URLPattern oluşturucusu, bu özel karakterlerden herhangi birinin URL'nin parçası değil, bir kalıbın parçası olduğunu varsayar. Belirsiz bir karakterin URL'nin bir parçası olarak yorumlanmasını istiyorsanız dize olarak sağlandığında \` character. For example, the literal URLabout:blankshould be escaped as'about\:blank'` ile kod dışına alındığından emin olun.

Kalıbı kullanma

Bir URLPattern oluşturduktan sonra bunu kullanmak için iki seçeneğiniz vardır. Hem test() hem de exec() yöntemi aynı girişi alır ve eşleşme olup olmadığını kontrol etmek için aynı algoritmayı kullanır ve yalnızca döndürülen değerleri birbirinden farklıdır. test(), belirtilen giriş için eşleşme olduğunda true değerini, aksi halde false değerini döndürür. exec(), yakalama gruplarıyla birlikte eşleşme hakkında ayrıntılı bilgileri veya eşleşme yoksa null değerini döndürür. Aşağıdaki örneklerde exec() kullanımı gösterilmektedir ancak yalnızca basit bir boole döndürme değeri istiyorsanız bunlardan herhangi biriyle test() değiştirebilirsiniz.

test() ve exec() yöntemlerini kullanmanın bir yolu dizeleri geçirmektir. Oluşturucunun desteklediği gibi, tek bir dize sağlanırsa kaynak dahil olmak üzere tam URL olmalıdır. İki dize sağlanırsa ikinci dize bir baseURL değeri olarak değerlendirilir ve ilk dize bu tabana göre değerlendirilir.

const p = new URLPattern({
  pathname: '/foo/:image.jpg',
  baseURL: 'https://example.com',
});

const result = p.exec('https://example.com/foo/cat.jpg');
// result will contain info about the successful match.
// const result = p.exec('/foo/cat.jpg', 'https://example.com')
// is equivalent, using the baseURL syntax.

const noMatchResult = p.exec('https://example.com/bar');
// noMatchResult will be null.

Alternatif olarak, oluşturucunun desteklediği türden nesneyi aktarabilirsiniz. Bu tür nesneler, URL'nin yalnızca eşleştirmeyi önemsediğiniz bölümleri olarak ayarlanır.

const p = new URLPattern({pathname: '/foo/:image.jpg'});

const result = p.exec({pathname: '/foo/:image.jpg'});
// result will contain info about the successful match.

Joker karakter veya jeton içeren bir URLPattern üzerinde exec() kullandığınızda döndürülen değer, giriş URL'sindeki karşılık gelen değerlerin ne olduğu hakkında size bilgi verir. Böylece bu değerleri kendiniz ayrıştırma zahmetinden kurtulmuş olursunuz.

const p = new URLPattern({
  hostname: ':subdomain.example.com',
  pathname: '/*/:image.jpg'
});

const result = p.exec('https://imagecdn1.example.com/foo/cat.jpg');
// result.hostname.groups.subdomain will be 'imagecdn1'
// result.pathname.groups[0] will be 'foo', corresponding to *
// result.pathname.groups.image will be 'cat'

Anonim ve adlandırılmış gruplar

exec() öğesine bir URL dizesi ilettiğinizde, hangi bölümlerin modelin tüm gruplarıyla eşleştiğini bildiren bir değer alırsınız.

Döndürülen değer, URLPattern bileşenlerine karşılık gelen özelliklere (ör. pathname) sahiptir. Dolayısıyla, bir grup URLPattern öğesinin pathname bölümünün bir parçası olarak tanımlanmışsa eşleşmeler, döndürülen değerin pathname.groups öğesinde bulunabilir. Eşleşmeler, karşılık gelen kalıbın anonim veya adlandırılmış grup olmasına bağlı olarak farklı şekilde temsil edilir.

Anonim bir kalıp eşleşmesine ilişkin değerlere erişmek için dizi dizinlerini kullanabilirsiniz. Birden fazla anonim kalıp varsa 0 dizini, 1 ve sonraki kalıplar için kullanılan diğer dizinler en soldakiyle eşleşen değeri temsil eder.

Bir kalıpta adlandırılmış gruplar kullanıldığında eşleşmeler, adları her grup adına karşılık gelen özellikler olarak gösterilir.

Unicode desteği ve normalleştirme

URLPattern, Unicode karakterleri birkaç farklı şekilde destekler.

  • :café gibi adlandırılmış gruplar Unicode karakterleri içerebilir. Geçerli JavaScript tanımlayıcıları için kullanılan kurallar adlandırılmış gruplar için de geçerlidir.

  • Bir kalıp içindeki metin, söz konusu bileşenin URL kodlaması için kullanılan kurallara göre otomatik olarak kodlanır. pathname içindeki Unicode karakterleri yüzde kodlamalı olacaktır. Böylece /café gibi bir pathname kalıbı, otomatik olarak /caf%C3%A9 şeklinde normalleştirilir. hostname içindeki Unicode karakterleri, yüzde kodlaması yerine Punycode kullanılarak otomatik olarak kodlanır.

  • Normal ifade grupları yalnızca ASCII karakterleri içermelidir. Normal ifade söz dizimi, bu gruplardaki Unicode karakterlerinin otomatik olarak kodlanmasını zorlaştırır ve güvenli değildir. Bir normal ifade grubundaki bir Unicode karakteriyle eşleştirmek istiyorsanız bunu, café ile eşleştirmek için (caf%C3%A9) örneğinde olduğu gibi manuel olarak yüzde olarak kodlamanız gerekir.

URLPattern, Unicode karakterlerini kodlamaya ek olarak URL normalleştirmesini de gerçekleştirir. Örneğin, pathname bileşenindeki /foo/./bar, eşdeğer /foo/bar değerine daraltılmıştır.

Belirli bir giriş kalıbının nasıl normalleştirildiği konusunda şüpheye düşerseniz tarayıcınızın DevTools'nı kullanarak oluşturulan URLPattern örneğini inceleyin.

Özet

Aşağıya yerleştirilen Arıza demosu, belirli kalıpları ağ isteklerine yanıt oluşturulabilecek eşzamansız işlevlerle eşleyerek bir Service Worker'ın fetch event handler içinde yer alan temel URLPattern kullanım alanını gösterir. Bu örnekteki kavramlar, sunucu tarafı veya istemci tarafında diğer yönlendirme senaryolarına da uygulanabilir.

Geri bildirim ve gelecek planları

URLPattern için temel işlevler Chrome ve Edge'e ulaşmış olsa da bazı eklemeler yapılması planlanmaktadır. URLPattern ürününün bazı yönleri hâlâ geliştirilme aşamasındadır ve belirli davranışlar hakkında hâlâ iyileştirilmesi gereken bazı açık sorular mevcuttur. URLPattern ürününü denemenizi ve GitHub sorunu aracılığıyla geri bildirimlerinizi bizimle paylaşmanızı öneririz.

Şablon desteği

path-to-regexp kitaplığı, yönlendirme davranışını etkili bir şekilde tersine çeviren bir compile() function sağlar. compile(), jeton yer tutucuları için bir kalıp ve değerler alır ve bu değerlerin değiştirildiği bir URL yolu için bir dize döndürür.

Gelecekte URLPattern'e bunu eklemeyi umuyoruz ancak ilk sürümün kapsamında değildir.

Gelecekteki web platformu özelliklerini etkinleştirme

URLPattern ürününün web platformunun yerleşik bir parçası haline geldiği varsayıldığında, yönlendirme veya kalıp eşleştirmeden yararlanabilecek diğer özellikler, temel öğe olarak bunun üzerine inşa edilebilir.

Hizmet çalışanı kapsam kalıbı eşleşmesi, dosya işleyici olarak PWA'lar ve spekülatif önceden getirme gibi önerilen özellikler için URLPattern kullanımıyla ilgili tartışmalar devam etmektedir.

Teşekkür

Tüm teşekkür listesi için orijinal açıklayıcı belgeye bakın.