JavaScript轻量级URL构建库urlcat：自动处理路径拼接与参数转义

urlcat 是一个轻量级的 JavaScript 工具库，旨在简化 URL 的构建过程，同时有效规避常见的拼接错误。

该库具备以下核心特性：

• API 设计简洁易用
• 零外部依赖
• 压缩后体积仅为 0.8KB
• 内置 TypeScript 类型定义

2. 使用方法

在调用 HTTP API 时，往往需要在 URL 中动态插入参数。

const API_URL = 'https://api.example.com/';

function getUserPosts(id, blogId, limit, offset) {
  const requestUrl = `${API_URL}/users/${id}/blogs/${blogId}/posts?limit=${limit}&offset=${offset}`;
  // send HTTP request
}

如前文示例所示，即使是最简单的拼接场景，手动构建 URL 也极易导致代码可读性下降。此外，这种写法还容易引发错误：

• 若疏忽了 API_URL 常量末尾的斜杠，将导致生成包含重复斜杠的URL(https://api.example.com//users)。
• 嵌入路径的值必须通过 encodeURIComponent 进行编码转义。

虽然可以使用内置的 URL 类来避免重复斜杠，并利用 URLSearchParams 处理查询字符串，但路径参数仍需手动转义。

const API_URL = 'https://api.example.com/';

function getUserPosts(id, blogId, limit, offset) {
  const escapedId = encodeURIComponent(id);
  const escapedBlogId = encodeURIComponent(blogId);
  const path = `/users/${escapedId}/blogs/${escapedBlogId}`;
  const url = new URL(path, API_URL);
  url.search = new URLSearchParams({ limit, offset });
  const requestUrl = url.href;
  // send HTTP request
}

如此简单的任务却难以阅读且编写繁琐，这正是 urlcat 库所解决的问题：

const API_URL = 'https://api.example.com/';

function getUserPosts(id, limit, offset) {
  const requestUrl = urlcat(API_URL, '/users/:id/posts', { id, limit, offset });
  // send HTTP request
}

使用该库的代码示例如下：

• 自动对所有参数进行转义处理
• 自动拼接各部分（确保各部分间恰好有一个 / 和 ?）

ParamMap

目前，该软件包通过 npm 进行分发。（后续将支持 Zip 下载和 CDN 接入）。

npm install --save urlcat

在 Node.js 环境中的使用

官方支持 Node 10 及更高版本。由于代码内部依赖 URL 和 URLSearchParams 类，这些类在 v10 以下版本不可用，因此无法支持更早的版本。

构建完整 URL（最常见的使用场景）：

const urlcat = require('urlcat').default;

单独使用任一实用函数：

const { query, subst, join } = require('urlcat');

使用所有导出的函数：

const { default: urlcat, query, subst, join } = require('urlcat');

在 TypeScript 环境中的使用

官方支持 TypeScript 2.1 及更高版本。

构建完整 URL（最常见的使用场景）：

import urlcat from 'urlcat';

单独使用任一实用函数：

import { query, subst, join } from 'urlcat';

使用所有导出的函数：

import urlcat, { query, subst, join } from 'urlcat';

在 Deno 环境中的使用

import urlcat from 'https://deno.land/x/urlcat/src/index.ts';

console.log(urlcat('https://api.foo.com', ':name', { id: 25, name: 'knpwrs' }));

3. API 文档

ParamMap：包含字符串键的对象

例如：{ firstParam: 1, 'second-param': 2 } 是一个有效的 ParamMap。

urlcat：构建完整 URL

function urlcat(baseUrl: string, pathTemplate: string, params: ParamMap): string
function urlcat(baseUrl: string, pathTemplate: string): string
function urlcat(baseTemplate: string, params: ParamMap): string

示例如下：

urlcat('https://api.example.com', '/users/:id/posts', { id: 123, limit: 10, offset: 120 }) → 'https://api.example.com/users/123/posts?limit=10&offset=120' urlcat('http://example.com/', '/posts/:title', { title: 'Letters & "Special" Characters' }) → 'http://example.com/posts/Letters%20%26%20%22Special%22%20Characters' urlcat('https://api.example.com', '/users') → 'https://api.example.com/users' urlcat('https://api.example.com/', '/users') → 'https://api.example.com/users' urlcat('http://example.com/', '/users/:userId/posts/:postId/comments', { userId: 123, postId: 987, authorId: 456, limit: 10, offset: 120 }) → 'http://example.com/users/123/posts/987/comments?authorId=456&limit=10&offset=120'

query：构建查询字符串

根据指定的键值对构建查询字符串。键和值会被自动转义，随后由 '&' 字符连接。

示例如下：

subst：替换路径参数

使用模板字符串中的值替换参数。模板可包含 0 个或多个参数占位符。占位符以冒号 (:) 开头，后跟仅包含大小写字母的参数名称。模板中找到的任何占位符都将替换为 params 中相应键下的值。

示例如下：

join：使用分隔符连接两个字符串

仅使用一个分隔符连接两部分。如果 part1 的末尾或 part2 的开头存在该分隔符，则先将其移除，然后再使用分隔符连接两部分。

示例如下：

以上就是对 JavaScript 库 urlcat 之 URL 构建器库的详细介绍，更多相关 JavaScript URL 构建器库的内容请搜索本站以前的文章或继续浏览下面的相关文章，希望大家以后多多支持本站！