URL 工具 API

通过 createWURL(url: string) 创建 URL 工具对象。

使用指引（做什么、何时用）

• 域名信息：getMainDomain/getSubdomain/getOrigin/getProtocol/getPort → 统计、租户、同源判断
• 查询参数：parseQueryParams/addParamsToURL/replaceParams/setParam/removeParam → 搜索/分页/筛选
• 安全跳转：isSameOrigin(other) → 跳转前校验同源，避免钓鱼或跨站问题
• 哈希与路径：getHash/getPathname → 前端路由或锚点处理
• 调试头信息：getClientRequestHeaders() → 浏览器可近似的头（非真实请求头，仅调试）

提示

• 若用户输入 URL，可能无效：会抛出 Error('Invalid URL format')；请在调用前校验或捕获异常
• 合并查询参数时优先使用 replaceParams（覆盖为主），追加使用 addParamsToURL

导入

import { createWURL } from 'nex-lib';

createWURL(url: string)

返回对象包含：

• getMainDomain(): string 主域名（不含子域）
• getSubdomain(): string 子域名（如有，否则返回空字符串）
• getHostname(): string 主机名（含子域）
• getOrigin(): string 来源（协议+主机+端口）
• getProtocol(): string 协议（不带冒号）
• getQueryString(): string 查询字符串（含 ?）
• getHash(): string 哈希（含 #）
• parseQueryParams(): Record<string, string> 查询参数对象
• addParamsToURL(params: Record<string,string>): string 追加查询参数并返回新 URL 字符串
• setParam(key, value): string 设置单个参数
• removeParam(key): string 移除单个参数
• replaceParams(params): string 用新参数集合替换旧参数
• isHttps(): boolean 是否 HTTPS
• getPathname(): string 路径部分
• getPort(): string 端口号（未显式端口返回 '80'）
• isSameOrigin(other: string): boolean 与另一 URL 是否同源

const u = createWURL('https://sub.example.com:8080/path?foo=bar');
u.getMainDomain();            // 'example.com'
u.getSubdomain();             // 'sub'
u.getHostname();              // 'sub.example.com'
u.getOrigin();                // 'https://sub.example.com:8080'
u.getProtocol();              // 'https'
u.parseQueryParams();         // { foo: 'bar' }
u.addParamsToURL({ q: 'x' }); // 'https://sub.example.com:8080/path?foo=bar&q=x'
u.isHttps();                  // true
u.getPathname();              // '/path'
u.getPort();                  // '8080'

异常

• 当 url 无效时抛出 Error('Invalid URL format')

请求头（浏览器环境）

• getClientRequestHeaders(): Record<string,string> 返回浏览器环境下可近似的请求头信息
• 说明：受浏览器安全限制，无法直接读取真实请求头，仅返回近似值（User-Agent / Accept-Language / Referer / Origin / Host / Cookie）。

示例与输出（Examples & Output）

Example

import { createWURL } from 'nex-lib'
const u = createWURL('https://sub.example.com:8080/path?foo=bar')
u.getMainDomain()
u.getSubdomain()
u.getHostname()
u.getOrigin()
u.getProtocol()
u.parseQueryParams()
u.addParamsToURL({ q: 'x' })
u.isHttps()
u.getPathname()
u.getPort()

Output

example.com
sub
sub.example.com
https://sub.example.com:8080
https
{ "foo": "bar" }
https://sub.example.com:8080/path?foo=bar&q=x
true
/path
8080

Example

// 浏览器环境下近似请求头（值因环境不同而异）
const headers = u.getClientRequestHeaders()

Output

{
  "User-Agent": "Mozilla/5.0 ...",
  "Accept-Language": "zh-CN,zh,en-US,en",
  "Referer": "",
  "Origin": "https://sub.example.com:8080",
  "Host": "sub.example.com:8080",
  "Cookie": ""
}