urlcat：JavaScript的URL構建器庫

杭州程式設計師張張發表於2022-02-21
JavaScript

urlcat 是一個小型的 JavaScript 庫，它使構建 URL 非常方便並防止常見錯誤。

特性：

  • 友好的 API
  • 無依賴
  • 壓縮後0.8KB大小
  • 提供TypeScript型別

為什麼用？

在呼叫 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
}

正如你所看到的，這個最小的例子已經很難閱讀了。這也是不正確的：

  • 我忘記了 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
}

如此簡單的任務，卻又很難讀，寫也很乏味！這是這個小型庫可以幫助您的地方：

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
}

這個庫會這樣處理：

  • 轉義所有引數
  • 將所有部分連線起來（它們之間總是正好有一個 / 和 ?）

如何使用？

目前，該軟體包通過 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' }));

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：構建查詢字串

使用指定的鍵值對構建查詢字串。鍵和值被轉義，然後由 '&' 字元連線。

例如：

paramsresult
{}''
{ query: 'some text' }'query=some%20text'
{ id: 42, 'comment-id': 86 }'id=42&comment-id=86'
{ id: 42, 'a name': 'a value' }'id=42&a%20name=a%20value'

subst：替換路徑引數

用模板字串中的值替換引數。模板可能包含 0 個或多個引數佔位符。佔位符以冒號 (:) 開頭，後跟只能包含大寫或小寫字母的引數名稱。在模板中找到的任何佔位符都將替換為 params 中相應鍵下的值。

例如

templateparamsresult
':id'{ id: 42 }'42'
'/users/:id'{ id: 42 }'/users/42'
'/users/:id/comments/:commentId'{ id: 42, commentId: 86 }'/users/42/comments/86'
'/users/:id'{ id: 42, foo: 'bar' }'/users/42'

join：使用一個分隔符連線兩個字串

僅使用一個分隔符連線兩個部分。如果分隔符出現在 part1 的末尾或 part2 的開頭，則將其刪除，然後使用分隔符連線兩個部分。

例如：

part1separatorpart2result
'first'',''second''first,second'
'first,'',''second'
'first'','',second'
'first,'','',second'

Github庫地址：https://github.com/balazsboto...

相關文章