URL Parsing & Encoding: Structure to Secure Handling

EncodingEncoding, hashing, and QR

The Complete URL Structure

https://user:pass@example.com:8080/path/to/page?name=value&age=25#section
  │       │     │    │          │  │   │            │                │
  scheme  user  pass  host      port path           query            fragment
Component Example Description
scheme https Protocol
userinfo user:pass Authentication info (rarely used today)
host example.com Domain or IP
port 8080 Port number (defaults to 80/443)
path /path/to/page Path
query ?name=value&age=25 Query parameters
fragment #section Anchor (never sent to the server)

Parsing with the URL API

Basic Parsing

const url = new URL('https://example.com:8080/path?q=test#section');

url.protocol  // "https:"
url.hostname  // "example.com"
url.port      // "8080"
url.pathname  // "/path"
url.search    // "?q=test"
url.hash      // "#section"
url.origin    // "https://example.com:8080"
url.href      // The complete URL

Parsing Query Parameters

const url = new URL('https://example.com/api?name=Alice&age=25&tags=js&tags=css');

// URLSearchParams
url.searchParams.get('name')     // "Alice"
url.searchParams.get('age')      // "25"
url.searchParams.getAll('tags')  // ["js", "css"]
url.searchParams.has('name')     // true
url.searchParams.delete('age')

// Iteration
for (const [key, value] of url.searchParams) {
  console.log(`${key} = ${value}`);
}

Modifying a URL

const url = new URL('https://example.com/page');

url.pathname = '/new-page';
url.searchParams.set('sort', 'desc');
url.searchParams.append('filter', 'active');
url.hash = '#top';

console.log(url.toString());
// "https://example.com/new-page?sort=desc&filter=active#top"

URL Encoding Rules

Why Encoding Is Necessary

URLs only allow ASCII characters; everything else must be encoded:

Original: https://example.com/search?q=你好 世界
Encoded:  https://example.com/search?q=%E4%BD%A0%E5%A5%BD%20%E4%B8%96%E7%95%8C

encodeURI vs encodeURIComponent

Function Encoding Scope Use Case
encodeURI Preserves URL structural characters (:/?#[]@!$&'()*+,;=) Encoding a complete URL
encodeURIComponent Encodes all non-ASCII + reserved characters Encoding query parameter values 
const url = 'https://example.com/path?name=你好&redirect=/home';

// encodeURI: preserves URL structure
encodeURI(url);
// "https://example.com/path?name=%E4%BD%A0%E5%A5%BD&redirect=/home"

// encodeURIComponent: encodes all special characters
encodeURIComponent(url);
// "https%3A%2F%2Fexample.com%2Fpath%3Fname%3D%E4%BD%A0%E5%A5%BD%26redirect%3D%2Fhome"

// ✅ Correct usage: encode parameter values with encodeURIComponent
const name = '你好 世界';
const redirect = '/home';
const fullUrl = `https://example.com/path?name=${encodeURIComponent(name)}&redirect=${encodeURIComponent(redirect)}`;

Common Encoding Reference

Character Encoded Notes
Space %20 Don't use + in URLs
+ %2B + decodes to a space in query parameters
& %26 Query parameter separator
= %3D Key-value separator
# %23 Fragment identifier
% %25 The encoding prefix itself
Chinese %E4%BD%A0 UTF-8 three-byte encoding

Encoding/Decoding URLs with ToolsKu

  1. Open the URL Encoder/Decoder tool
  2. Paste a URL or text into the input box
  3. Click "Encode" or "Decode"
  4. View the result

Secure URL Handling

1. Prevent URL Injection

// ❌ Dangerous: directly concatenating user input
const url = `/api/users/${userId}`;

// ✅ Safe: validate + encode
function buildUserUrl(userId) {
  if (!/^\d+$/.test(userId)) {
    throw new Error('Invalid user ID');
  }
  return `/api/users/${encodeURIComponent(userId)}`;
}

2. Prevent Open Redirects

// ❌ Dangerous: users can specify any redirect URL
app.get('/login', (req, res) => {
  res.redirect(req.query.redirect);
});

// ✅ Safe: whitelist validation
function safeRedirect(url, allowedHosts) {
  try {
    const parsed = new URL(url, 'https://example.com');
    if (allowedHosts.includes(parsed.hostname)) {
      return url;
    }
  } catch {
    // Invalid URL
  }
  return '/'; // Fall back to the homepage
}

3. Prevent XSS via URL

// ❌ Dangerous: javascript: protocol
const url = 'javascript:alert(document.cookie)';

// ✅ Safe: only allow http/https protocols
function sanitizeUrl(url) {
  try {
    const parsed = new URL(url);
    if (['http:', 'https:'].includes(parsed.protocol)) {
      return url;
    }
  } catch {
    // Invalid URL
  }
  return 'about:blank';
}

The URLPattern API (New Standard)

// Route matching
const pattern = new URLPattern({ pathname: '/api/users/:id' });

const result = pattern.exec('https://example.com/api/users/123');
if (result) {
  console.log(result.pathname.groups.id); // "123"
}

// More complex patterns
const apiPattern = new URLPattern({
  protocol: 'https',
  hostname: ':env.example.com',
  pathname: '/api/:version/:resource/:id?',
});

const match = apiPattern.exec('https://prod.example.com/api/v2/users/456');
match.hostname.groups.env      // "prod"
match.pathname.groups.version  // "v2"
match.pathname.groups.resource // "users"
match.pathname.groups.id       // "456"

Query Parameter Building Best Practices

Using URLSearchParams

// ✅ Recommended: use URLSearchParams
const params = new URLSearchParams({
  q: 'search keywords',
  sort: 'desc',
  page: '1',
  limit: '20',
});

params.append('tags', 'javascript');
params.append('tags', 'css');

const url = `https://api.example.com/search?${params}`;
// "https://api.example.com/search?q=...&sort=desc&page=1&limit=20&tags=javascript&tags=css"

Common Array Parameter Conventions

Convention Example Server Framework
Repeated keys ?tags=js&tags=css Express, Koa
Bracket suffix ?tags[]=js&tags[]=css PHP, Rails
Indexed ?tags[0]=js&tags[1]=css PHP
Comma-separated ?tags=js,css Custom

FAQ

Why Is a Space Sometimes %20 and Sometimes + in URLs?

  • In URL paths: space = %20 (standard)
  • In query parameters: space = + or %20 (+ is the application/x-www-form-urlencoded convention)
  • Recommendation: always use %20 to avoid ambiguity

Is There a Maximum URL Length?

Context Limit
Chrome address bar 2MB
Firefox address bar No limit
IE address bar 2083 characters
HTTP GET requests Server-dependent (usually 8KB)
Safe upper bound 2048 characters (compatible with all browsers)

Parameters longer than 2048 characters should be sent via POST instead.

Summary

URLs are the foundation of the Web — understanding their structure, encoding rules, and secure handling is essential knowledge for every developer. The key takeaways: encode parameter values with encodeURIComponent, validate protocols to prevent XSS, and use whitelists to prevent open redirects. ToolsKu's URL Encoder/Decoder tool helps you handle URL encoding problems quickly.

#URL解析#URL编码#查询参数#Web开发#教程