gongdear

在 Mapbox GL JS 中，transformRequest 允许开发者在地图加载时拦截并修改即将发出的 HTTP 请求。这在需要对请求进行安全性、认证、或其他定制化处理时非常有用。下面结合代码示例详细讲解其使用方法和常见使用场景。

transformRequest 的基本用法

在初始化地图时，可以通过配置项传入 transformRequest 回调函数。该函数会在 Mapbox GL JS 发起每一个网络请求之前被调用，其基本函数签名为：

transformRequest: (url, resourceType) => {
    // 可以在这里检查请求的 URL 或资源类型，并返回新的请求配置
}

• 参数说明：
  • url ：原始请求的 URL。
  • resourceType ：表示请求资源的类型，可能的取值包括Style、Source、Tile、Sprite、Glyphs 等。根据资源类型，你可以有针对性地修改某些请求。
• 返回值：
  • 如果返回一个对象，该对象可以包含以下属性：
    • url ：修改后的 URL。例如，可以将不安全的http 协议替换为https。
    • headers ：附加的 HTTP 请求头。可以用于添加 API key、认证令牌等。
    • credentials ：设置是否包含凭证（如 cookies）。例如，值可以为'include' 以便跨域请求中发送 cookies。

如果回调函数返回 undefined，则该请求将使用原始配置发出，不进行任何修改。

代码示例讲解

下面是一个示例代码：

const map = new Map({
    container: 'map',
    style: 'mapbox://styles/mapbox/streets-v11',
    transformRequest: (url, resourceType) => {
        if (resourceType === 'Source' && url.indexOf('http://myHost') > -1) {
            return {
                url: url.replace('http', 'https'),
                headers: {'my-custom-header': true},
                credentials: 'include'  // Include cookies for cross-origin requests
            };
        }
    }
});

代码说明：

1. 判断资源类型和 URL：
   • 通过判断resourceType === 'Source'，此代码仅针对请求类型为Source 的资源生效。这样可以避免影响样式、图标或字体等其他类型的请求。
   • 同时检查 URL 中是否包含"http://myHost"，以确保只有访问特定域名的请求才被修改。
2. 修改请求 URL：
   • 使用url.replace('http', 'https') 将 URL 中的http 替换为https。注意，为了更加精确，通常建议写成url.replace('http://', 'https://')，以免意外修改到 URL 中其他位置的 “http” 字符串。
3. 添加自定义请求头：
   • 增加了一个名为'my-custom-header' 的请求头，并设置其值为true。这在需要向服务器传递额外的认证信息或控制标记时非常有用。
4. 配置凭证发送：
   • 设置credentials: 'include'，确保跨域请求时会发送 cookies。这对于访问受保护的资源（例如需要登录状态）是必要的。

使用场景举例

1. 强制使用 HTTPS：

   • 当你使用的某些数据源仅支持 HTTPS 访问，而原始配置中可能包含 HTTP 链接时，可以通过 transformRequest 将 HTTP 改为 HTTPS，确保请求的安全性。

2. 添加认证信息：

   • 如果你从一个私有服务器或 API 获取地图数据，服务器可能需要一个 API 密钥或者认证令牌。通过在 transformRequest 中添加自定义 header，你可以满足服务器的认证要求。

   transformRequest: (url, resourceType) => {
       if (url.includes('privateDataSource')) {
           return {
               headers: {
                   'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
               }
           };
       }
   }
   

3. 跨域请求处理：

   • 某些服务要求跨域请求必须附带凭证（例如 cookies 或者其他身份验证信息）。使用credentials: 'include' 可确保在跨域请求时自动附带这些信息。

4. 动态修改请求 URL：

   • 当你有多个环境（如开发、测试、生产）时，可能需要动态改变请求 URL，例如从本地服务器切换到远程服务器。transformRequest 允许在运行时做出这样的调整。

5. 代理或调试用途：

   • 在开发过程中，你可以使用 transformRequest 来代理请求到一个调试服务器，或记录所有请求以便排查问题。

总结

transformRequest 是 Mapbox GL JS 提供的一个强大工具，它使开发者能够在请求发出前对 URL、HTTP 头和凭证等进行定制化处理。这不仅提升了安全性（例如强制 HTTPS），还能够满足特定业务场景下的认证和数据访问要求。结合代码示例，我们可以看到如何针对特定资源类型和 URL 进行条件判断，并返回修改后的请求配置，从而实现灵活的网络请求控制。