LogoENEnglish

راهنمای جامع ماژول URL در Node.js

ماژول node:url ابزارهایی برای تحلیل، ساخت، و دست‌کاری URLها در Node.js فراهم می‌کند. Node.js دو API برای کار با URL دارد: WHATWG URL API — استاندارد مدرن و سازگار با مرورگرها (توصیه‌شده). Legacy API — API قدیمی Node.js (غیرتوصیه‌شده). WHATWG URL API یک رابط تمیز، سازگار و قدرتمند برای کار با اجزای URL، پارامترهای query، الگوهای URL و حتی Blob URLها ارائه می‌دهد.

WHATWG URLLegacy url.parseURLSearchParamsURLPattern

~2 دقیقه مطالعه • بروزرسانی ۹ دی ۱۴۰۴

1. معرفی


ماژول node:url امکان تحلیل و ساخت URLها را فراهم می‌کند. Node.js هم API قدیمی و هم API مدرن WHATWG را پشتیبانی می‌کند.


2. URL String و URL Object


یک URL شامل بخش‌هایی مانند پروتکل، hostname، پورت، مسیر، query و hash است. با parse کردن URL، یک شیء ساختاریافته دریافت می‌کنیم.


3. مقایسه WHATWG و Legacy


  • WHATWG URL → new URL() (استاندارد و توصیه‌شده)
  • Legacy API → url.parse() (قدیمی)

مثال WHATWG:

const myURL = new URL('https://user:[email protected]:8080/path?query=1#hash');

مثال Legacy:

const url = require('node:url');
const myURL = url.parse('https://user:[email protected]:8080/path?query=1#hash');

4. ساخت URL


می‌توان URL را با setterها یا template literal ساخت:

const myURL = new URL('https://example.org');
myURL.pathname = '/a/b';
myURL.search = '?x=1';
myURL.hash = '#top';

5. سازنده WHATWG URL


ورودی می‌تواند نسبی یا مطلق باشد. ورودی‌های نسبی نیاز به base دارند.

new URL('/foo', 'https://example.org/');

پشتیبانی از Unicode و Punycode

new URL('https://測試'); // → https://xn--g6w251d/

6. ویژگی‌های URL


6.1 url.hash

بخش fragment (#...)

6.2 url.host

hostname + port

6.3 url.hostname

فقط hostname

6.4 url.href

رشتهٔ کامل URL

6.5 url.origin

پروتکل + host

6.6 url.username / url.password

اطلاعات احراز هویت

6.7 url.pathname

مسیر URL

6.8 url.port

پورت (۰ تا ۶۵۵۳۵)

6.9 url.protocol

پروتکل (http:, https:, ftp:, ...)

پروتکل‌های Special

فقط پروتکل‌های ftp، file، http، https، ws، wss «special» هستند.


7. url.search و url.searchParams


url.search رشتهٔ query است. url.searchParams یک API ساختاریافته برای مدیریت پارامترهاست.

مثال:

myURL.searchParams.get('id');
myURL.searchParams.append('key', 'value');
myURL.searchParams.delete('id');
myURL.searchParams.set('a', 'b');

8. API کلاس URLSearchParams


سازنده‌ها:

  • new URLSearchParams()
  • new URLSearchParams('a=b&c=d')
  • new URLSearchParams({ a: 'b' })
  • new URLSearchParams([['a','b']])

متدهای مهم:

  • append()
  • delete()
  • get()
  • getAll()
  • has()
  • set()
  • sort()

9. Blob Object URLs


Node.js امکان ساخت URLهای blob:nodedata را فراهم می‌کند:

const id = URL.createObjectURL(blob);
const restored = resolveObjectURL(id);
URL.revokeObjectURL(id);

10. URL.canParse()


برای بررسی معتبر بودن URL بدون پرتاب خطا:

URL.canParse('/foo', 'https://example.org/'); // true

11. URL.parse()


نسخهٔ امن‌تر که در صورت نامعتبر بودن، null برمی‌گرداند.


12. URLPattern API


API جدید و آزمایشی برای match کردن URLها.

مثال:

const pattern = new URLPattern('https://site.com/docs/*.html');
pattern.test('https://site.com/docs/api.html'); // true

نتیجه‌گیری


ماژول node:url یک سیستم قدرتمند و استاندارد برای تحلیل و ساخت URLها در Node.js ارائه می‌دهد. WHATWG URL API روش مدرن و سازگار با مرورگرهاست و باید در تمام پروژه‌های جدید استفاده شود. با امکاناتی مانند URLSearchParams، Blob URLs، URLPattern و پشتیبانی از Punycode، Node.js مجموعه‌ای کامل برای کار با URLها فراهم می‌کند.


نوشته و پژوهش شده توسط دکتر شاهین صیامی

Next Article