node:url

O módulo node:url no Azion Runtime: análise e formatação de URLs, as APIs com suporte e exemplos de URL de requisição, query, validação e roteamento.

Última atualização

Ver como Markdown Configurar agente

O módulo node:url fornece os utilitários do Node.js para resolver, analisar e formatar URLs. Com ele, uma function lê as partes de uma URL de forma estruturada, altera essas partes e constrói URLs para roteamento e requisições de API. O Azion Runtime oferece o módulo por meio da compatibilidade com Node.js. Uma function pode usá-lo para analisar a URL da requisição recebida, ler os parâmetros de query dela e construir URLs ao fazer proxy ou redirecionar tráfego. No Azion Runtime, url.URL é o mesmo objeto que o global URL, e as funções legadas url.parse(), url.format() e url.resolve() funcionam em uma function após o deploy.

Exemplos

Cada exemplo é uma function completa que importa url de node:url. A resposta abaixo de cada exemplo é a que uma function com deploy feito retorna.

Análise e formatação de URL

Esta function cria uma URL com a classe global URL, constrói uma string de URL a partir de um objeto com url.format() e analisa essa string com url.parse():

JavaScript
01/**
02 * An example of using Node.js URL API in an Azion Function.
03 * Support:
04 * - Partially supported (Extended by library `url`)
05 * @module runtime-apis/nodejs/url/main
06 * @example
07 * // Build and run with the Azion CLI:
08 * azion build
09 * azion dev
10 */
11import url from "node:url";
12/**
13 * An example of using the Node.js URL API in an Azion Function.
14 * @param {*} event
15 * @returns {Promise<Response>}
16 */
17const main = async (event) => {
18 /**
19 * URL globalThis object
20 * https://developer.mozilla.org/en-US/docs/Web/API/URL
21 * if use URL in the browser, don't need to import
22 */
23 const newUrl = new URL("https://example.com/some/path?format=json&page=1");
24 console.log("newURL", newUrl);
25
26 const urlFormated = url.format({
27 protocol: "https",
28 hostname: "example.com",
29 pathname: "/some/path",
30 query: {
31 page: 1,
32 format: "json",
33 },
34 });
35
36 console.log(url.parse(urlFormated));
37
38 return new Response("Done!", { status: 200 });
39};
40
41export default main;

A function responde com Done!. Ela registra no log a URL, o aviso de API obsoleta que url.parse() exibe e o objeto analisado:

Texto
01newURL "https://example.com/some/path?format=json&page=1"
02[DeprecationWarning] [unenv] [node:url] DEP0169: `url.parse()` behavior is not standardized and prone to errors that have security implications. Use the WHATWG URL API instead. CVEs are not issued for `url.parse()` vulnerabilities.
03{"auth":null,"hash":null,"host":"example.com","hostname":"example.com","href":"https://example.com/some/path?page=1&format=json","path":"/some/path?page=1&format=json","pathname":"/some/path","protocol":"https:","search":"?page=1&format=json","slashes":true,"port":null,"query":"page=1&format=json"}

Análise da URL da requisição

Esta function lê os componentes da URL da requisição, reúne os parâmetros de query dela e divide o caminho em segmentos:

JavaScript
01// url module imported for legacy API demonstration
02// new URL() and URLSearchParams are available globally
03import url from "node:url";
04
05const main = async (event) => {
06 const request = event.request;
07 const requestUrl = new URL(request.url);
08
09 // Extract URL components
10 const urlInfo = {
11 href: requestUrl.href,
12 origin: requestUrl.origin,
13 protocol: requestUrl.protocol,
14 hostname: requestUrl.hostname,
15 port: requestUrl.port,
16 pathname: requestUrl.pathname,
17 search: requestUrl.search,
18 hash: requestUrl.hash
19 };
20
21 // Parse query parameters
22 const searchParams = requestUrl.searchParams;
23 const queryParams = {};
24 for (const [key, value] of searchParams) {
25 queryParams[key] = value;
26 }
27
28 // ⚠️ url.parse() is deprecated since Node.js v11.0.0
29 // Prefer the WHATWG URL API (new URL()) shown above
30 const parsedUrl = url.parse(request.url, true);
31 console.log("Parsed URL:", parsedUrl);
32
33 // Get path segments
34 const segments = requestUrl.pathname.split("/").filter(Boolean);
35
36 return new Response(JSON.stringify({
37 urlInfo,
38 queryParams,
39 segments,
40 parsedQuery: parsedUrl.query
41 }), {
42 headers: { "Content-Type": "application/json" }
43 });
44};
45
46export default main;

Para uma requisição GET para https://example.com/blog/post-1, a function responde com os componentes da URL, uma query vazia e os dois segmentos do caminho:

{"urlInfo":{"href":"https://example.com/blog/post-1","origin":"https://example.com","protocol":"https:","hostname":"example.com","port":"","pathname":"/blog/post-1","search":"","hash":""},"queryParams":{},"segments":["blog","post-1"],"parsedQuery":{}}

Construção dinâmica de URLs

Esta function constrói uma URL de API com parâmetros de query, uma URL de redirecionamento com url.format() e uma URL a partir das partes dela. Ela também resolve um caminho relativo duas vezes, com url.resolve() e com o construtor URL:

JavaScript
01import url from "node:url";
02
03const main = async (event) => {
04 // Build API URL with query parameters
05 const apiUrl = new URL("https://api.example.com/v1/users");
06 apiUrl.searchParams.set("page", "1");
07 apiUrl.searchParams.set("limit", "10");
08 apiUrl.searchParams.set("sort", "name");
09 apiUrl.searchParams.set("active", "true");
10
11 console.log("API URL:", apiUrl.toString());
12
13 // Build redirect URL
14 const redirectUrl = url.format({
15 protocol: "https",
16 hostname: "app.example.com",
17 pathname: "/dashboard",
18 query: {
19 ref: "login",
20 session: "abc123"
21 }
22 });
23
24 // Resolve relative URL
25 // ⚠️ url.resolve() is deprecated since Node.js v11.0.0
26 // Prefer: new URL(relativePath, baseUrl).href
27 const baseUrl = "https://example.com/docs/";
28 const relativePath = "../api/reference";
29 const resolvedUrl = url.resolve(baseUrl, relativePath);
30 console.log("Resolved URL (deprecated):", resolvedUrl);
31
32 // Modern alternative using URL constructor
33 const modernResolvedUrl = new URL(relativePath, baseUrl).href;
34 console.log("Resolved URL (modern):", modernResolvedUrl);
35
36 // Build URL from parts
37 const parts = {
38 protocol: "https:",
39 hostname: "cdn.example.com",
40 port: "443",
41 pathname: "/assets/images/logo.png"
42 };
43 const fullUrl = url.format(parts);
44
45 return new Response(JSON.stringify({
46 apiUrl: apiUrl.toString(),
47 redirectUrl,
48 resolvedUrl,
49 builtUrl: fullUrl
50 }), {
51 headers: { "Content-Type": "application/json" }
52 });
53};
54
55export default main;

A function responde com as quatro URLs. As duas formas de resolver o caminho relativo registram no log https://example.com/api/reference, e a URL construída a partir das partes mantém a porta 443:

{"apiUrl":"https://api.example.com/v1/users?page=1&limit=10&sort=name&active=true","redirectUrl":"https://app.example.com/dashboard?ref=login&session=abc123","resolvedUrl":"https://example.com/api/reference","builtUrl":"https://cdn.example.com:443/assets/images/logo.png"}

Manipulação de parâmetros de query

Esta function lê, verifica, altera e ordena os parâmetros de query da requisição e, em seguida, constrói uma segunda query string a partir de um objeto:

JavaScript
01import url from "node:url";
02
03const main = async (event) => {
04 const requestUrl = new URL(event.request.url);
05 const params = requestUrl.searchParams;
06
07 // Read parameters
08 const page = params.get("page") || "1";
09 const limit = params.get("limit") || "10";
10 const sort = params.get("sort");
11
12 console.log("Page:", page, "Limit:", limit, "Sort:", sort);
13
14 // Check if parameter exists
15 const hasFilter = params.has("filter");
16 console.log("Has filter:", hasFilter);
17
18 // Get all values for a parameter (multi-value)
19 const tags = params.getAll("tag");
20 console.log("Tags:", tags);
21
22 // Modify parameters
23 params.set("page", "2");
24 params.set("timestamp", Date.now().toString());
25 params.delete("debug");
26
27 // Iterate over parameters
28 const allParams = [];
29 for (const [key, value] of params) {
30 allParams.push({ key, value });
31 }
32
33 // Sort parameters alphabetically
34 params.sort();
35
36 // Convert to string
37 const queryString = params.toString();
38
39 // Create new URLSearchParams from object
40 const newParams = new URLSearchParams({
41 format: "json",
42 version: "2",
43 pretty: "true"
44 });
45
46 return new Response(JSON.stringify({
47 originalParams: { page, limit, sort },
48 hasFilter,
49 tags,
50 modifiedParams: allParams,
51 queryString,
52 newParamsString: newParams.toString()
53 }), {
54 headers: { "Content-Type": "application/json" }
55 });
56};
57
58export default main;

Para uma requisição sem query string, a function responde com os valores padrão, os parâmetros alterados e as duas query strings. O valor de timestamp vem de Date.now():

{"originalParams":{"page":"1","limit":"10","sort":null},"hasFilter":false,"tags":[],"modifiedParams":[{"key":"page","value":"2"},{"key":"timestamp","value":"1767268800000"}],"queryString":"page=2&timestamp=1767268800000","newParamsString":"format=json&version=2&pretty=true"}

Validação e normalização de URL

Esta function verifica uma lista de URLs com o construtor URL e, em seguida, normaliza cada URL válida: ela converte o hostname para minúsculas e remove uma porta padrão:

JavaScript
01import url from "node:url";
02
03const main = async (event) => {
04 const request = event.request;
05 // Note: In a real application, you might receive URLs from the request body
06 // const { urls: customUrls } = await request.json().catch(() => ({}));
07
08 // URLs to validate
09 const testUrls = [
10 "https://example.com/path",
11 "http://localhost:3000/api?query=test",
12 "HTTPS://EXAMPLE.COM/UPPERCASE",
13 "https://example.com:443/standard-port",
14 "https://user:pass@example.com/auth",
15 "not-a-url",
16 "ftp://files.example.com"
17 ];
18
19 const results = testUrls.map(testUrl => {
20 try {
21 const parsed = new URL(testUrl);
22 return {
23 original: testUrl,
24 valid: true,
25 normalized: parsed.href,
26 protocol: parsed.protocol,
27 hostname: parsed.hostname,
28 isHttps: parsed.protocol === "https:"
29 };
30 } catch (error) {
31 return {
32 original: testUrl,
33 valid: false,
34 error: error.message
35 };
36 }
37 });
38
39 // Normalize a URL (lowercase hostname, default port removal)
40 const normalizeUrl = (urlString) => {
41 try {
42 const parsed = new URL(urlString);
43 parsed.hostname = parsed.hostname.toLowerCase();
44
45 // Remove default ports
46 if (parsed.protocol === "https:" && parsed.port === "443") {
47 parsed.port = "";
48 }
49 if (parsed.protocol === "http:" && parsed.port === "80") {
50 parsed.port = "";
51 }
52
53 return parsed.href;
54 } catch {
55 return null;
56 }
57 };
58
59 const normalizedUrls = testUrls.map(normalizeUrl);
60
61 return new Response(JSON.stringify({
62 validationResults: results,
63 normalizedUrls
64 }), {
65 headers: { "Content-Type": "application/json" }
66 });
67};
68
69export default main;

A function responde com o resultado de cada URL e com a lista normalizada. O construtor URL rejeita not-a-url com a mensagem Invalid URL: 'not-a-url', e a lista normalizada contém null no lugar dela:

{"validationResults":[{"original":"https://example.com/path","valid":true,"normalized":"https://example.com/path","protocol":"https:","hostname":"example.com","isHttps":true},{"original":"http://localhost:3000/api?query=test","valid":true,"normalized":"http://localhost:3000/api?query=test","protocol":"http:","hostname":"localhost","isHttps":false},{"original":"HTTPS://EXAMPLE.COM/UPPERCASE","valid":true,"normalized":"https://example.com/UPPERCASE","protocol":"https:","hostname":"example.com","isHttps":true},{"original":"https://example.com:443/standard-port","valid":true,"normalized":"https://example.com/standard-port","protocol":"https:","hostname":"example.com","isHttps":true},{"original":"https://user:pass@example.com/auth","valid":true,"normalized":"https://user:pass@example.com/auth","protocol":"https:","hostname":"example.com","isHttps":true},{"original":"not-a-url","valid":false,"error":"Invalid URL: 'not-a-url'"},{"original":"ftp://files.example.com","valid":true,"normalized":"ftp://files.example.com/","protocol":"ftp:","hostname":"files.example.com","isHttps":false}],"normalizedUrls":["https://example.com/path","http://localhost:3000/api?query=test","https://example.com/UPPERCASE","https://example.com/standard-port","https://user:pass@example.com/auth",null,"ftp://files.example.com/"]}

Roteamento de URL e correspondência de caminhos

Esta function compara o caminho da requisição com uma tabela de rotas, incluindo uma rota com um parâmetro :id, e verifica se a rota aceita o método da requisição. Ela responde 404 quando nenhuma rota corresponde e 405 quando uma rota corresponde, mas os métodos dela não incluem o método da requisição:

JavaScript
01import url from "node:url";
02
03const main = async (event) => {
04 const requestUrl = new URL(event.request.url);
05 const pathname = requestUrl.pathname;
06
07 // Define routes
08 const routes = {
09 "/": { handler: "home", methods: ["GET"] },
10 "/api/users": { handler: "users", methods: ["GET", "POST"] },
11 "/api/users/:id": { handler: "userDetail", methods: ["GET", "PUT", "DELETE"] },
12 "/api/products": { handler: "products", methods: ["GET"] },
13 "/health": { handler: "health", methods: ["GET"] }
14 };
15
16 // Match route
17 const matchRoute = (path) => {
18 // Exact match
19 if (routes[path]) {
20 return { ...routes[path], params: {} };
21 }
22
23 // Pattern match for :id style routes
24 for (const [pattern, config] of Object.entries(routes)) {
25 if (pattern.includes(":")) {
26 const regex = new RegExp("^" + pattern.replace(/:\w+/g, "([^/]+)") + "$");
27 const match = path.match(regex);
28 if (match) {
29 const paramNames = pattern.match(/:\w+/g) || [];
30 const params = {};
31 paramNames.forEach((name, i) => {
32 params[name.slice(1)] = match[i + 1];
33 });
34 return { ...config, params };
35 }
36 }
37 }
38
39 return null;
40 };
41
42 const matchedRoute = matchRoute(pathname);
43 const method = event.request.method;
44
45 // Check if method is allowed
46 const methodAllowed = matchedRoute?.methods?.includes(method);
47
48 // Build response
49 const response = {
50 pathname,
51 method,
52 matched: matchedRoute ? {
53 handler: matchedRoute.handler,
54 params: matchedRoute.params,
55 methodAllowed
56 } : null,
57 query: Object.fromEntries(requestUrl.searchParams)
58 };
59
60 return new Response(JSON.stringify(response, null, 2), {
61 status: matchedRoute && methodAllowed ? 200 : matchedRoute ? 405 : 404,
62 headers: { "Content-Type": "application/json" }
63 });
64};
65
66export default main;

Para uma requisição GET para https://example.com/blog/post-1, um caminho que a tabela de rotas não lista, a function segue o ramo sem correspondência e responde com o status 404 e este corpo:

JSON
01{
02 "pathname": "/blog/post-1",
03 "method": "GET",
04 "matched": null,
05 "query": {}
06}

APIs com suporte

A tabela lista o status de cada API de node:url no Azion Runtime:

APIStatus
URL (global)🟢 Com suporte
URLSearchParams🟢 Com suporte
url.URL🟢 Com suporte
url.URLSearchParams🟢 Com suporte
url.format()🟢 Com suporte
url.parse()🟡 Com suporte (obsoleta, use new URL())
url.resolve()🟡 Com suporte (obsoleta, use new URL(relative, base))
url.domainToASCII()🟡 Suporte parcial
url.domainToUnicode()🟡 Suporte parcial
url.fileURLToPath()🟡 Suporte parcial
url.pathToFileURL()🟡 Suporte parcial
url.urlToHttpOptions()🟡 Suporte parcial

As APIs marcadas como 🟡 Suporte parcial têm funcionalidade limitada em comparação com a implementação completa do Node.js. Em uma function após o deploy, url.fileURLToPath("file:///tmp/x.txt") retorna /tmp/x.txt, url.pathToFileURL("/tmp/x.txt") retorna file:///tmp/x.txt e url.domainToASCII("español.com") retorna xn--espaol-zwa.com.

Uma function que chama url.parse() pode registrar no log este aviso de API obsoleta, como mostra o primeiro exemplo:

[DeprecationWarning] [unenv] [node:url] DEP0169: `url.parse()` behavior is not standardized and prone to errors that have security implications. Use the WHATWG URL API instead. CVEs are not issued for `url.parse()` vulnerabilities.

O Node.js marca url.parse(), url.resolve() e url.format() como obsoletas a partir da v11.0.0. Use as APIs WHATWG URL e URLSearchParams em vez delas: no Azion Runtime, as duas são globais e não precisam de import.

Recursos relacionados

APIs do Node.js

Cada módulo do Node.js que o Azion Runtime resolve e o status de url entre eles.

Use APIs do Node.js com polyfills

Como o build resolve node:url e os outros imports do Node.js para o Azion Runtime.

Documentação de url do Node.js

A referência do Node.js para cada API de node:url que a tabela lista.

Documentação da API URL no MDN

A referência Web da classe global URL que todos os exemplos usam.