feat: add allowAbsoluteUrls option

Author: ModyQyW

README.md

@@ -288,10 +288,15 @@ const instance = un.create({
   // `url` 是用于请求的服务器 URL
   url: '/user',
 
-  // `baseUrl` 将自动加在 `url` 前面，除非 `url` 是一个绝对 URL
+  // `baseUrl` 将自动加在 `url` 前面，除非 `url` 是一个绝对 URL 且选项 `allowAbsoluteUrls` 为 true
   // 设置一个 `baseUrl` 便于为实例方法传递相对 URL
   baseUrl: 'https://some-domain.com/api/',
 
+  // 决定是否允许绝对 URL 覆盖配置的 `baseUrl`
+  // 当设置为 true（默认）时，绝对值的 `url` 会覆盖 `baseUrl`
+  // 当设置为 false 时，绝对值的 `url` 会始终被 `baseUrl` 前置
+  allowAbsoluteUrls?: boolean;
+
   // 自定义请求头
   // 不能设置 Referer
   headers: {

docs/api/request-config.md

@@ -7,10 +7,15 @@
   // `url` 是用于请求的服务器 URL
   url: "/user",
 
-  // `baseUrl` 将自动加在 `url` 前面，除非 `url` 是一个绝对 URL
+  // `baseUrl` 将自动加在 `url` 前面，除非 `url` 是一个绝对 URL 且选项 `allowAbsoluteUrls` 为 true
   // 设置一个 `baseUrl` 便于为实例方法传递相对 URL
   baseUrl: "https://some-domain.com/api/",
 
+  // 决定是否允许绝对 URL 覆盖配置的 `baseUrl`
+  // 当设置为 true（默认）时，绝对值的 `url` 会覆盖 `baseUrl`
+  // 当设置为 false 时，绝对值的 `url` 会始终被 `baseUrl` 前置
+  allowAbsoluteUrls?: boolean;
+
   // 自定义请求头
   // 不能设置 Referer
   headers: {

packages/core/src/core/Un.ts

@@ -286,6 +286,7 @@ export class Un<T = UnData, D = UnData> {
     const fullPath = buildFullPath(
       mergedConfig?.baseUrl ?? "",
       mergedConfig?.url ?? "",
+      mergedConfig?.allowAbsoluteUrls ?? true,
     );
     return buildUrl(
       fullPath,

packages/core/src/types/config.ts

@@ -24,8 +24,16 @@ export interface UnConfig<T = UnData, D = UnData> {
    * 默认为 'GET'
    */
   method?: UnMethod;
-  /** 自动加在 `url` 前面，除非 `url` 是一个绝对 URL */
+  /** 自动加在 `url` 前面，除非 `url` 是一个绝对 URL 且选项 `allowAbsoluteUrls` 为 true */
   baseUrl?: string;
+  /**
+   * 决定是否允许绝对 URL 覆盖配置的 `baseUrl`
+   *
+   * 当设置为 true（默认）时，绝对值的 `url` 会覆盖 `baseUrl`
+   *
+   * 当设置为 false 时，绝对值的 `url` 会始终被 `baseUrl` 前置
+   */
+  allowAbsoluteUrls?: boolean;
   /** 自定义请求头，不能设置 Referer */
   headers?: UnHeaders;
   /** 与请求一起发送的 URL 参数 */

packages/core/src/utils/buildDownloadConfig.ts

@@ -7,7 +7,11 @@ export const buildDownloadConfig = <T = UnData, D = UnData>(
 ) =>
   ({
     url: buildUrl(
-      buildFullPath(config.baseUrl ?? "", config.url ?? ""),
+      buildFullPath(
+        config.baseUrl ?? "",
+        config.url ?? "",
+        config.allowAbsoluteUrls ?? true,
+      ),
       config.params,
       config.paramsSerializer,
     ),

packages/core/src/utils/buildFullPath.test.ts

@@ -3,22 +3,36 @@ import { buildFullPath } from "./buildFullPath";
 
 describe("utils::buildFullPath", () => {
   it("should combine URLs when the requestedURL is relative", () => {
-    expect(buildFullPath("https://api.github.com", "/users")).toBe(
+    expect(buildFullPath("https://api.github.com", "/users", true)).toBe(
       "https://github.com/api/users",
     );
   });
 
-  it("should return the requestedURL when it is absolute", () => {
+  it("should not combine the URLs when the requestedURL is absolute", () => {
     expect(
-      buildFullPath("https://api.github.com", "https://api.example.com/users"),
+      buildFullPath(
+        "https://api.github.com",
+        "https://api.example.com/users",
+        true,
+      ),
     ).toBe("https://api.example.com/users");
   });
 
+  it("should combine the URLs when the requestedURL is absolute and allowAbsoluteUrls is false", () => {
+    expect(
+      buildFullPath(
+        "https://api.github.com",
+        "https://api.example.com/users",
+        false,
+      ),
+    ).toBe("https://github.com/api/https://api.example.com/users");
+  });
+
   it("should not combine URLs when the baseURL is not configured", () => {
-    expect(buildFullPath("", "/users")).toBe("/users");
+    expect(buildFullPath("", "/users", true)).toBe("/users");
   });
 
   it("should combine URLs when the baseURL and requestedURL are relative", () => {
-    expect(buildFullPath("/api", "/users")).toBe("/api/users");
+    expect(buildFullPath("/api", "/users", true)).toBe("/api/users");
   });
 });

packages/core/src/utils/buildFullPath.ts

@@ -1,8 +1,13 @@
 import { combineUrls } from "./combineUrls";
 import { isAbsoluteUrl } from "./isAbsoluteUrl";
 
-export const buildFullPath = (baseUrl: string, requestedUrl: string) => {
-  if (baseUrl && !isAbsoluteUrl(requestedUrl)) {
+export const buildFullPath = (
+  baseUrl: string,
+  requestedUrl: string,
+  allowAbsoluteUrls: boolean,
+) => {
+  const isRelativeUrl = !isAbsoluteUrl(requestedUrl);
+  if ((baseUrl && isRelativeUrl) || !allowAbsoluteUrls) {
     return combineUrls(baseUrl, requestedUrl);
   }
   return requestedUrl;

packages/core/src/utils/buildRequestConfig.ts

@@ -7,7 +7,11 @@ export const buildRequestConfig = <T = UnData, D = UnData>(
 ) =>
   ({
     url: buildUrl(
-      buildFullPath(config.baseUrl ?? "", config.url ?? ""),
+      buildFullPath(
+        config.baseUrl ?? "",
+        config.url ?? "",
+        config.allowAbsoluteUrls ?? true,
+      ),
       config.params,
       config.paramsSerializer,
     ),

packages/core/src/utils/buildUploadConfig.ts

@@ -7,7 +7,11 @@ export const buildUploadConfig = <T = UnData, D = UnData>(
 ) =>
   ({
     url: buildUrl(
-      buildFullPath(config.baseUrl ?? "", config.url ?? ""),
+      buildFullPath(
+        config.baseUrl ?? "",
+        config.url ?? "",
+        config.allowAbsoluteUrls ?? true,
+      ),
       config.params,
       config.paramsSerializer,
     ),