URLPattern, web platformuna yönlendirme sağlar

Jeff Posnick

Yayınlanma tarihi: 22 Temmuz 2021

Yönlendirme, her web uygulamasının önemli bir parçasıdır. Yönlendirme, temel olarak bir URL alır, bu URL'ye kalıp eşleştirme veya uygulamaya özgü başka bir mantık uygular ve ardından genellikle sonuca göre web içeriğini gösterir. Yönlendirme çeşitli şekillerde uygulanabilir:

  • Yolları diskteki dosyalarla eşleyen sunucu kodu
  • Tek sayfalık bir uygulamada, geçerli konumdaki değişiklikleri bekleyen, ardından karşılık gelen bir DOM parçası oluşturan ve görüntüleyen mantık.

Kesin bir standart olmasa da web geliştiriciler, regular expressions ile birçok ortak noktası olan ancak yol segmentlerini eşleştirmek için kullanılan jetonlar gibi alana özgü bazı eklemeler içeren URL yönlendirme kalıplarını ifade etmek için ortak bir söz dizimi kullanmaya başlamıştır. Express ve Ruby on Rails gibi popüler sunucu tarafı çerçeveler bu söz dizimini (veya buna çok yakın bir söz dizimini) kullanır. JavaScript geliştiriciler ise path-to-regexp veya regexpparam gibi modülleri kullanarak bu mantığı kendi kodlarına ekleyebilir.

URLPattern Bu çerçeveler tarafından oluşturulan temelin üzerine inşa edilen web platformuna eklenir. Bu özellik, joker karakterler, adlandırılmış jeton grupları, normal ifade grupları ve grup değiştiriciler için destek de dahil olmak üzere bir yönlendirme kalıbı söz dizimini standartlaştırmayı amaçlar. Bu söz dizimiyle oluşturulan URLPattern örnekleri, tam URL'lerle veya bir URL pathname ile eşleştirme ve jeton ile grup eşleşmeleri hakkında bilgi döndürme gibi yaygın yönlendirme görevlerini gerçekleştirebilir.

URL eşleştirme işlevini doğrudan web platformunda sunmanın bir diğer avantajı da URL'lerle eşleştirme yapması gereken diğer API'lerle ortak bir söz diziminin paylaşılabilmesidir.

Tarayıcı desteği ve polyfill'ler

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

urlpattern-polyfill kitaplığı, URLPattern arayüzünü tarayıcılarda veya yerleşik desteği olmayan Node gibi ortamlarda kullanmanın bir yolunu sunar. Polyfill kullanıyorsanız yalnızca mevcut ortamda desteklenmediği durumlarda yüklediğinizden emin olmak için özellik algılamayı kullandığınızdan emin olun. Aksi takdirde, URLPattern'nın temel avantajlarından birini kaybedersiniz: Destek ortamlarının kullanmak için ek kod indirip ayrıştırması gerekmez.

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

Söz dizimi uyumluluğu

URLPattern'da temel felsefe, yeniden icat etmemektir. Express veya Ruby on Rails'de kullanılan yönlendirme söz dizimine zaten aşinaysanız yeni bir şey öğrenmeniz gerekmez. Ancak popüler yönlendirme kitaplıklarındaki söz dizimleri arasında küçük farklılıklar olduğundan temel söz dizimi olarak bir şeyin seçilmesi gerekiyordu. URLPattern tasarımcıları, başlangıç noktası olarak path-to-regexp'teki kalıp söz dizimini (API yüzeyini değil) kullanmaya karar verdi.

Bu karar, path-to-regexp adlı paketin mevcut bakımcısıyla yakın istişarede bulunulduktan sonra alınmıştır.

Desteklenen söz diziminin temellerini öğrenmenin en iyi yolu, path-to-regexp için belgelere bakmaktır. MDN'de yayınlanmak üzere hazırlanan belgeleri GitHub'daki mevcut konumunda okuyabilirsiniz.

Ek özellikler

URLPattern'nın söz dizimi, path-to-regexp'ın desteklediği söz diziminin üst kümesidir. Çünkü URLPattern, yönlendirme kitaplıkları arasında yaygın olmayan bir özelliği destekler: Ana makine adlarındaki joker karakterler de dahil olmak üzere kaynaklarla eşleşme. Diğer yönlendirme kitaplıklarının çoğu yalnızca pathname ile, bazen de URL'nin search veya hash bölümüyle ilgilenir. Yalnızca bağımsız bir web uygulamasında aynı kaynaklı yönlendirme için kullanıldıklarından, URL'nin kaynak kısmını asla kontrol etmeleri gerekmez.

Kaynakları hesaba katmak, kaynaklar arası istekleri bir service worker'ın fetch etkinlik işleyicisi içinde yönlendirmek gibi ek kullanım alanlarının önünü açar. Yalnızca aynı kaynaklı URL'leri yönlendiriyorsanız bu ek özelliği etkili bir şekilde yoksayabilir ve URLPattern öğesini diğer kitaplıklar gibi kullanabilirsiniz.

Örnekler

Deseni oluşturma

URLPattern oluşturmak için oluşturucusuna dizeler veya özellikleri eşleştirilecek desen hakkında bilgi içeren bir nesne iletin.

Bir nesne iletmek, her 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 bu, şu şekilde görünebilir:

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

Bir özellik için boş dize sağlama yalnızca URL'nin ilgili kısmı ayarlanmamışsa eşleşir. Joker karakter *, URL'nin belirli bir bölümündeki herhangi bir değerle eşleşir.

Oluşturucu, daha kolay kullanım için çeşitli kısayollar sunar. search ve hash veya diğer özelliklerin tamamen atlanması, bu özelliklerin '*' joker karakterine ayarlanmasına eşdeğerdir. Örnek şu şekilde basitleştirilebilir:

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. Bu da

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. Yalnızca URL'nin diğer kısımlarıyla eşleşmeyle ilgileniyorsanız (kaynak hariç, birçok tek kaynaklı yönlendirme senaryosunda olduğu gibi) kaynak bilgilerini tamamen atlayabilir ve yalnızca pathname, search ve hash özelliklerinin bir kombinasyonunu sağlayabilirsiniz. Daha önce olduğu gibi, atlanan özellikler * joker karakteriyle ayarlanmış gibi değerlendirilir.

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

Oluşturucuya bir nesne iletmek yerine bir veya iki dize sağlayabilirsiniz. Tek bir dize sağlanırsa bu dize, kaynağı eşleştirmek için kullanılan kalıp bilgileri de dahil olmak üzere tam bir URL kalıbını temsil etmelidir. İki dize sağlarsanız ikinci dize baseURL olarak kullanılır ve ilk dize bu tabana göreli olarak kabul edilir.

Bir dize veya iki dize sağlanmış olsun, URLPattern oluşturucu tam URL kalıbını ayrıştırır, URL bileşenlerine ayırır ve daha büyük kalıbın her bölümünü karşılık gelen bileşenle eşler. Bu, arka planda, dizelerle oluşturulan her URLPattern öğesinin, nesneyle oluşturulan eşdeğer bir URLPattern öğesiyle aynı şekilde temsil edildiği anlamına gelir. Daha az ayrıntılı bir arayüzü tercih edenler için dizeler oluşturucu yalnızca bir kısayoldur.

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

URLPattern oluşturmak için dizeler kullanırken dikkat etmeniz gereken birkaç nokta vardır.

URLPattern oluşturmak için bir nesne kullanılırken bir özelliğin atlanması, bu özellik için * joker karakteri sağlamaya eşdeğerdir. Tam URL dize kalıbı ayrıştırıldığında URL bileşenlerinden birinde değer eksikse bu bileşenin özelliği '' olarak ayarlanmış gibi işlem yapılır. Bu da yalnızca söz konusu 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',
});

Ayrıca, bir dize kalıbını bileşenlerine ayrıştırmanın belirsiz olabileceğini de unutmamalısınız. URL'lerde bulunan ancak kalıp eşleştirme söz diziminde özel anlamı olan : gibi karakterler vardır. Bu belirsizliği önlemek için URLPattern oluşturucusu, bu özel karakterlerin URL'nin değil, kalıbın bir 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:blank\` character. For example, the literal URL'about\:blank'` ile çıkış karakteri eklediğinizden emin olun.should be escaped as

Deseni kullanma

URLPattern oluşturduktan sonra bunu kullanmak için iki seçeneğiniz vardır. test() ve exec() yöntemleri aynı girişi alır, eşleşme kontrolü için aynı algoritmayı kullanır ve yalnızca dönüş değeri bakımından farklılık gösterir. test(), verilen girişle eşleşme olduğunda true, aksi takdirde false değerini döndürür. exec(), yakalama gruplarıyla birlikte eşleşmeyle ilgili 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 bir boole dönüş değeri istiyorsanız bunların herhangi biri için test() değerini kullanabilirsiniz.

test() ve exec() yöntemlerini kullanmanın bir yolu, dizeleri iletmektir. Oluşturucunun desteklediğine benzer şekilde, tek bir dize sağlanırsa bu dize, kaynak da dahil olmak üzere tam bir URL olmalıdır. İki dize sağlanırsa ikinci dize baseURL değeri olarak kabul edilir 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 aynı türde bir nesneyi, yalnızca eşleşmesini istediğiniz URL bölümleriyle ayarlanmış özelliklerle iletebilirsiniz.

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 karakterler veya jetonlar içeren bir URLPattern üzerinde exec() kullanılırken dönüş değeri, giriş URL'sindeki karşılık gelen değerlerin ne olduğu hakkında bilgi verir. Bu sayede, söz konusu değerleri kendiniz ayrıştırmak zorunda kalmazsınız.

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() işlevine bir URL dizesi ilettiğinizde, hangi bölümlerin kalıbın tüm gruplarıyla eşleştiğini belirten bir değer döndürülür.

Döndürülen değer, URLPattern öğesinin bileşenlerine karşılık gelen özelliklere sahiptir (ör. pathname). Dolayısıyla, bir grup URLPattern öğesinin pathname bölümünün parçası olarak tanımlanmışsa eşleşmeler, dönüş değerinin pathname.groups bölümünde bulunabilir. Eşleşmeler, ilgili kalıbın anonim mi yoksa adlandırılmış bir grup mu olduğuna bağlı olarak farklı şekilde gösterilir.

Anonim bir desen eşleşmesinin değerlerine erişmek için dizi dizinlerini kullanabilirsiniz. Birden fazla anonim desen varsa 0 dizini en soldaki desenle eşleşen değeri, 1 ve sonraki dizinler ise sonraki desenleri temsil eder.

Bir kalıpta adlandırılmış gruplar kullanıldığında eşleşmeler, adları her grup adıyla eşleşen özellikler olarak gösterilir.

Unicode desteği ve normalleştirme

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

  • :café gibi adlandırılmış gruplar Unicode karakterler 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ıbın 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 karakterler yüzde olarak kodlanır. Bu nedenle, pathname kalıbı (ör. /café) otomatik olarak /caf%C3%A9 şeklinde normalleştirilir. hostname içindeki Unicode karakterler, yüzde kodlama 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 olmamasına neden olur. Bir normal ifade grubunda Unicode karakteriyle eşleşmek istiyorsanız karakteri manuel olarak yüzde kodlamanız gerekir. Örneğin, café ile eşleşmek için (caf%C3%A9) gibi.

URLPattern, Unicode karakterleri kodlamanın yanı sıra URL normalleştirme de gerçekleştirir. Örneğin, pathname bileşenindeki /foo/./bar, eşdeğer /foo/bar olarak daraltılı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.

Her şeyi bir araya getirin

Glitch demosu, URLPattern'ın bir hizmet çalışanının fetch event handler içindeki temel kullanım alanını gösterir. Bu kullanım alanı, belirli kalıpları ağ isteklerine yanıt oluşturabilecek eşzamansız işlevlerle eşlemeyi içerir. Bu örnekteki kavramlar, sunucu tarafında veya istemci tarafında diğer yönlendirme senaryolarına da uygulanabilir.

Geri bildirimler ve gelecek planları

URLPattern'nın temel işlevleri Chrome ve Edge'e eklenmiş olsa da başka eklemeler planlanmaktadır. URLPattern'nın bazı yönleri geliştirilmeye devam etmektedir ve belirli davranışlarla ilgili, hâlâ iyileştirilebilecek bir dizi açık soru bulunmaktadır. URLPattern özelliğini deneyip GitHub sorunu üzerinden geri bildirimde bulunmanızı öneririz.

Şablon oluşturma desteği

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

Gelecekte bunu URLPattern'e eklemeyi umuyoruz ancak bu, ilk sürümün kapsamı içinde yer almıyor.

Gelecekteki web platformu özelliklerini etkinleştirme

URLPattern'nın web platformunun yerleşik bir parçası haline geldiğini varsayarsak yönlendirme veya kalıp eşleştirme özelliklerinden yararlanabilecek diğer özellikler, temel bir özellik olarak bu özelliğin üzerine inşa edilebilir.

URLPattern, service worker kapsamı kalıp eşleştirme, dosya işleyicileri olarak PWA'lar ve tahmini önceden getirme gibi önerilen özelliklerde kullanılmasıyla ilgili devam eden tartışmalar var.

Teşekkürlerin tam listesi için orijinal açıklama belgesine bakın.