URLPattern مسیریابی را به پلتفرم وب می آورد

رویکردی برای استانداردسازی موارد استفاده تطبیق الگوی رایج

Jeff Posnick

پس زمینه

مسیریابی یک بخش کلیدی از هر برنامه وب است. در قلب خود، مسیریابی شامل گرفتن یک URL، اعمال برخی تطابق الگوها یا سایر منطق های خاص برنامه برای آن، و سپس، معمولا، نمایش محتوای وب بر اساس نتیجه است. مسیریابی ممکن است به روش‌های مختلفی پیاده‌سازی شود: گاهی اوقات کدی است که روی سروری اجرا می‌شود که مسیری را به فایل‌های روی دیسک ترسیم می‌کند، یا منطقی در یک برنامه تک صفحه‌ای که منتظر تغییرات در مکان فعلی است و یک قطعه DOM مربوطه را برای نمایش ایجاد می‌کند.

در حالی که هیچ استاندارد قطعی وجود ندارد، توسعه‌دهندگان وب به سمت یک نحو مشترک برای بیان الگوهای مسیریابی URL که اشتراکات زیادی با regular expressions دارند، اما با برخی از اضافات خاص دامنه مانند توکن‌ها برای تطبیق بخش‌های مسیر جذب شده‌اند. فریمورک های محبوب سمت سرور مانند Express و Ruby on Rails از این نحو (یا چیزی بسیار نزدیک به آن) استفاده می کنند و توسعه دهندگان جاوا اسکریپت می توانند از ماژول هایی مانند path-to-regexp یا regexpparam برای اضافه کردن این منطق به کد خود استفاده کنند.

URLPattern افزودنی به پلتفرم وب است که بر پایه‌ی ایجاد شده توسط این چارچوب‌ها بنا شده است. هدف آن استاندارد کردن یک نحو الگوی مسیریابی، از جمله پشتیبانی از حروف عام، گروه‌های نشانه نام‌گذاری شده، گروه‌های عبارت منظم و اصلاح‌کننده‌های گروه است. نمونه‌های URLPattern ایجاد شده با این نحو می‌توانند وظایف مسیریابی رایج را انجام دهند، مانند تطبیق با URLهای کامل یا pathname URL، و بازگرداندن اطلاعات مربوط به نشانه‌ها و تطابق‌های گروهی.

یکی دیگر از مزایای ارائه تطبیق URL به طور مستقیم در پلت فرم وب این است که می توان یک نحو مشترک را با سایر APIهایی که همچنین باید با URL ها مطابقت داشته باشند به اشتراک گذاشت.

پشتیبانی از مرورگر و polyfills

URLPattern به طور پیش فرض در کروم و اج نسخه 95 و بالاتر فعال است.

کتابخانه urlpattern-polyfill راهی برای استفاده از رابط URLPattern در مرورگرها یا محیط‌هایی مانند Node که فاقد پشتیبانی داخلی هستند، ارائه می‌کند. اگر از polyfill استفاده می‌کنید، مطمئن شوید که از تشخیص ویژگی استفاده می‌کنید تا مطمئن شوید که فقط در صورتی آن را بارگیری می‌کنید که محیط فعلی پشتیبانی نمی‌شود. در غیر این صورت، یکی از مزایای کلیدی URLPattern از دست خواهید داد: این واقعیت که محیط های پشتیبانی برای استفاده از آن نیازی به دانلود و تجزیه کد اضافی ندارند.

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

سازگاری نحوی

یک فلسفه راهنما برای URLPattern اجتناب از اختراع مجدد است. اگر قبلاً با نحو مسیریابی مورد استفاده در Express یا Ruby on Rails آشنا هستید، نباید چیز جدیدی یاد بگیرید. اما با توجه به تفاوت‌های جزئی بین نحو در کتابخانه‌های مسیریابی محبوب، چیزی باید به‌عنوان نحو پایه انتخاب می‌شد و طراحان URLPattern تصمیم گرفتند از نحو الگو از path-to-regexp (البته نه سطح API آن) به عنوان نقطه شروع استفاده کنند.

این تصمیم پس از مشورت نزدیک با نگهدارنده فعلی path-to-regexp گرفته شد.

بهترین راه برای آشنایی با هسته سینتکس پشتیبانی شده این است که به مستندات مربوط به path-to-regexp مراجعه کنید. می‌توانید اسناد در نظر گرفته شده برای انتشار در MDN را در خانه فعلی آن در GitHub بخوانید.

ویژگی های اضافی

نحو URLPattern ابرمجموعه ای از آنچه path-to-regexp پشتیبانی می کند است، زیرا URLPattern از یک ویژگی غیر معمول در میان کتابخانه های مسیریابی پشتیبانی می کند: منشاهای منطبق، از جمله حروف عام در نام میزبان. بیشتر کتابخانه‌های مسیریابی دیگر فقط با نام مسیر و گاهی اوقات جستجو یا هش بخشی از یک URL سر و کار دارند. آنها هرگز مجبور نیستند قسمت مبدا URL را بررسی کنند، زیرا فقط برای مسیریابی با مبدا یکسان در یک برنامه وب مستقل استفاده می شوند.

در نظر گرفتن مبدا در را برای موارد استفاده اضافی باز می کند، مانند مسیریابی درخواست های متقاطع در داخل کنترل کننده رویداد fetch یک کارگر خدماتی . اگر فقط URL های با منشاء یکسان را مسیریابی می کنید، می توانید به طور موثر این ویژگی اضافی را نادیده بگیرید و از URLPattern مانند سایر کتابخانه ها استفاده کنید.

نمونه ها

ساخت الگو

برای ایجاد یک URLPattern ، سازنده آن را رشته‌ها یا شیئی ارسال کنید که ویژگی‌های آن حاوی اطلاعاتی درباره الگوی مورد تطبیق است.

ارسال یک شی، واضح ترین کنترل را بر روی الگوی استفاده برای تطبیق هر جزء URL ارائه می دهد. در پرمخاطب ترین حالت، این می تواند به نظر برسد

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

ارائه یک رشته خالی برای یک ویژگی تنها در صورتی مطابقت دارد که قسمت مربوطه از URL تنظیم نشده باشد. علامت * با هر مقداری برای بخش مشخصی از URL مطابقت دارد.

سازنده چند میانبر برای استفاده ساده تر ارائه می دهد. حذف کامل search و hash ، یا هر ویژگی دیگر، معادل تنظیم آنها بر روی علامت عام '*' است. مثال بالا را می توان ساده کرد

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

به عنوان یک میانبر اضافی، تمام اطلاعات مربوط به مبدا را می توان در یک ویژگی واحد، baseURL ارائه کرد که منجر به

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

همه این مثال‌ها فرض می‌کنند که مورد استفاده شما شامل منشاهای تطبیقی ​​است. اگر فقط به تطبیق در بخش‌های دیگر URL، به استثنای مبدا علاقه دارید (همانطور که در مورد بسیاری از سناریوهای مسیریابی تک مبدأ "سنتی" وجود دارد)، می‌توانید اطلاعات مبدا را به طور کامل حذف کنید و فقط ترکیبی از pathname ، search و ویژگی‌های hash را ارائه دهید. مانند قبل، با ویژگی های حذف شده به گونه ای رفتار می شود که گویی روی الگوی علامت * تنظیم شده اند.

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

به عنوان جایگزینی برای ارسال یک شی به سازنده، می توانید یک یا دو رشته را ارائه دهید. اگر یک رشته ارائه شده باشد، باید یک الگوی URL کامل، از جمله اطلاعات الگوی مورد استفاده برای مطابقت با مبدا را نشان دهد. اگر دو رشته ارائه کنید، رشته دوم به عنوان یک baseURL استفاده می شود و رشته اول نسبت به آن پایه در نظر گرفته می شود.

چه یک رشته یا دو رشته ارائه شود، سازنده URLPattern الگوی URL کامل را تجزیه می‌کند، آن را به اجزای URL تقسیم می‌کند و هر بخش از الگوی بزرگ‌تر را به جزء مربوطه نگاشت می‌کند. این به این معنی است که در زیر هود، هر URLPattern ایجاد شده با رشته ها در نهایت به عنوان یک URLPattern معادل ایجاد شده با یک شی نشان داده می شود. سازنده رشته ها فقط یک میانبر است، برای کسانی که رابط کاربری کمتر پرمخاطب را ترجیح می دهند.

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

هنگام استفاده از رشته ها برای ایجاد URLPattern ، باید چند نکته را در نظر داشت.

کنار گذاشتن یک ویژگی هنگام استفاده از یک شی برای ساخت URLPattern معادل ارائه یک علامت * برای آن ویژگی است. هنگامی که الگوی رشته URL کامل تجزیه می شود، اگر یکی از مؤلفه های URL فاقد مقدار باشد، به گونه ای رفتار می شود که گویی ویژگی جزء روی '' تنظیم شده است، که تنها زمانی مطابقت می کند که آن جزء خالی باشد.

هنگامی که از رشته ها استفاده می کنید، اگر می خواهید در URLPattern ساخته شده استفاده شود، باید به صراحت حروف عام را اضافه کنید.

// 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',
});

همچنین باید بدانید که تجزیه یک الگوی رشته در اجزای آن به طور بالقوه مبهم است. کاراکترهایی مانند : وجود دارند که در URL ها یافت می شوند، اما در نحو تطبیق الگو نیز معنای خاصی دارند. برای جلوگیری از این ابهام، سازنده URLPattern فرض می‌کند که هر یک از آن کاراکترهای خاص بخشی از یک الگو هستند، نه بخشی از URL. اگر می خواهید یک کاراکتر مبهم به عنوان بخشی از URL تفسیر شود، مطمئن شوید که با یک \` character. For example, the literal URL about:blank should be escaped as .

با استفاده از الگو

پس از ساخت URLPattern ، دو گزینه برای استفاده از آن دارید. متدهای test() و exec() هر دو ورودی یکسان را دریافت می کنند و از الگوریتم یکسانی برای بررسی یک تطابق استفاده می کنند و فقط در مقدار بازگشتی آنها متفاوت هستند. test() زمانی که برای ورودی داده شده مطابقت داشته باشد true و در غیر این صورت false برمی گرداند. exec() اطلاعات دقیق مربوط به مسابقه را به همراه گروه‌های ضبط برمی‌گرداند یا در صورت عدم تطابق، null برمی‌گرداند. مثال‌های زیر استفاده از exec() را نشان می‌دهند، اما اگر فقط یک مقدار بازگشتی بولی ساده می‌خواهید، می‌توانید در test() با هر یک از آنها تعویض کنید.

یکی از راه های استفاده از متدهای test() و exec() عبور دادن رشته هاست. مشابه آنچه سازنده پشتیبانی می کند، اگر یک رشته ارائه شود، باید یک URL کامل، از جمله مبدا باشد. اگر دو رشته ارائه شود، رشته دوم به عنوان یک مقدار baseURL در نظر گرفته می شود و رشته اول نسبت به آن پایه ارزیابی می شود.

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.

همچنین، می‌توانید همان نوع شی را که سازنده پشتیبانی می‌کند، با ویژگی‌هایی که فقط روی قسمت‌هایی از URL که برای شما مهم است مطابقت داشته باشند، ارسال کنید.

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

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

هنگام استفاده از exec() در URLPattern که حاوی علائم یا نشانه‌ها است، مقدار بازگشتی اطلاعاتی در مورد مقادیر مربوطه در URL ورودی به شما می‌دهد. این می تواند شما را از دردسر تجزیه این ارزش ها نجات دهد.

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'

گروه های ناشناس و نامگذاری شده

هنگامی که یک رشته URL را به exec() می‌فرستید، مقداری دریافت می‌کنید که به شما می‌گوید کدام بخش با همه گروه‌های الگو مطابقت دارد.

مقدار بازگشتی دارای خصوصیاتی است که با اجزای URLPattern مطابقت دارد، مانند pathname . بنابراین اگر گروهی به عنوان بخشی از قسمت pathname URLPattern تعریف شده باشد، می‌توان موارد مطابق را در pathname.groups مقدار بازگشتی یافت. بسته به اینکه الگوی متناظر یک گروه ناشناس یا با نام بود، مطابقت ها متفاوت نشان داده می شوند.

می‌توانید از شاخص‌های آرایه برای دسترسی به مقادیر مربوط به الگوی ناشناس استفاده کنید. اگر چندین الگوی ناشناس وجود داشته باشد، شاخص 0 مقدار تطبیق را برای سمت چپ نشان می دهد، با 1 و شاخص های بیشتر برای الگوهای بعدی استفاده می شود.

هنگام استفاده از گروه‌های نام‌گذاری‌شده در یک الگو، مطابقت‌ها به‌عنوان ویژگی‌هایی نمایش داده می‌شوند که نام آنها با نام هر گروه مطابقت دارد.

پشتیبانی و عادی سازی یونیکد

URLPattern از کاراکترهای یونیکد به روش های مختلف پشتیبانی می کند.

• گروه‌های نام‌گذاری شده، مانند :café ، می‌توانند شامل کاراکترهای یونیکد باشند. قوانین مورد استفاده برای شناسه های معتبر جاوا اسکریپت برای گروه های نامگذاری شده اعمال می شود.

• متن درون یک الگو به طور خودکار مطابق با قوانینی که برای رمزگذاری URL آن جزء خاص استفاده می شود، کدگذاری می شود. کاراکترهای یونیکد در pathname با درصد رمزگذاری می شوند، بنابراین یک الگوی pathname مانند /café به طور خودکار به /caf%C3%A9 عادی می شود. کاراکترهای یونیکد در hostname به‌طور خودکار با استفاده از Punycode کدگذاری می‌شوند، نه رمزگذاری درصد.

• گروه‌های عبارت منظم باید فقط شامل نویسه‌های ASCII باشند. نحو عبارت منظم، رمزگذاری خودکار کاراکترهای یونیکد در این گروه ها را دشوار و ناامن می کند. اگر می‌خواهید یک کاراکتر یونیکد را در یک گروه عبارت معمولی مطابقت دهید، باید درصد آن را به صورت دستی رمزگذاری کنید، مانند (caf%C3%A9) برای مطابقت با café .

URLPattern علاوه بر رمزگذاری کاراکترهای یونیکد، عادی سازی URL را نیز انجام می دهد. برای مثال، /foo/./bar در مولفه pathname به معادل /foo/bar جمع می‌شود.

وقتی در مورد اینکه چگونه یک الگوی ورودی داده شده عادی شده است شک دارید، نمونه URLPattern ساخته شده را با استفاده از DevTools مرورگر خود بررسی کنید.

همه را کنار هم گذاشتن

نسخه ی نمایشی Glitch تعبیه شده در زیر یک مورد استفاده اصلی از URLPattern را در fetch event handler یک سرویس دهنده نشان می دهد، الگوهای خاصی را به توابع ناهمزمان نگاشت می کند که می تواند پاسخی به درخواست های شبکه ایجاد کند. مفاهیم موجود در این مثال را می‌توان برای سایر سناریوهای مسیریابی، چه سمت سرور یا سمت سرویس گیرنده، اعمال کرد.

بازخورد و برنامه های آینده

در حالی که عملکرد اصلی URLPattern به کروم و اج رسیده است، برنامه‌ریزی‌هایی برای اضافه شدن وجود دارد. برخی از جنبه‌های URLPattern هنوز در حال توسعه هستند، و تعدادی سؤال باز درباره رفتارهای خاص وجود دارد که ممکن است هنوز اصلاح شوند. ما شما را تشویق می کنیم URLPattern امتحان کنید و هر گونه بازخوردی را از طریق مشکل GitHub ارائه دهید.

پشتیبانی از قالب

کتابخانه path-to-regexp یک compile() function ارائه می دهد که به طور موثر رفتار مسیریابی را معکوس می کند. compile() یک الگو و مقادیر برای مکان‌نماهای نشانه می‌گیرد و یک رشته برای مسیر URL با آن مقادیر جایگزین شده برمی‌گرداند.

ما امیدواریم که در آینده این را به URLPattern اضافه کنیم ، اما در محدوده انتشار اولیه نیست.

فعال کردن ویژگی‌های پلتفرم وب آینده

با فرض اینکه URLPattern به بخشی ثابت از پلتفرم وب تبدیل می‌شود، سایر ویژگی‌هایی که می‌توانند از مسیریابی یا تطبیق الگو سود ببرند، می‌توانند در بالای آن به‌عنوان یک ویژگی اولیه ایجاد شوند.

بحث‌های مداومی در مورد استفاده از URLPattern برای ویژگی‌های پیشنهادی مانند تطبیق الگوی محدوده کارگر سرویس ، PWAها به‌عنوان کنترل‌کننده فایل و واکشی پیش فرضی وجود دارد.

قدردانی

برای فهرست کامل قدردانی ها به سند توضیح دهنده اصلی مراجعه کنید.