Maplibre GL JS 中动态更新 WMS 请求认证令牌的技术实践

在使用 Maplibre GL JS 进行地图开发时，经常会遇到需要为 WMS 图层请求添加认证令牌的场景。本文将深入探讨如何正确处理认证令牌的动态更新问题，避免因令牌过期导致的 401 未授权错误。

问题背景

在基于 Maplibre GL JS 开发的地图应用中，当 WMS 服务需要 OAuth2 认证时，开发者通常会使用 transformRequest 方法在请求头中添加 Bearer Token。然而，很多开发者会遇到一个常见问题：当令牌过期后，即使应用已经获取了新令牌，地图仍然继续使用旧令牌发起请求，导致后续 WMS 请求失败。

核心问题分析

这个问题的根源在于 Maplibre GL JS 对 transformRequest 方法的处理机制。transformRequest 方法仅在初始化地图时被调用并缓存，后续请求会直接使用缓存的配置，而不会重新执行 transformRequest 方法。这意味着：

1. 初始令牌被固化在请求处理流程中
2. 令牌更新后，地图实例不会自动感知变化
3. 后续请求继续使用已过期的令牌

解决方案

Maplibre GL JS 提供了 setTransformRequest 方法来解决这个问题。正确的做法是：

1. 在令牌更新时，主动调用 setTransformRequest 方法
2. 传入新的 transformRequest 函数
3. 确保新函数使用最新的有效令牌

实现示例

// 创建令牌更新函数
function updateMapToken(mapInstance, newToken) {
  const newTransformRequest = (url) => {
    if (url.startsWith(`${window.location.protocol}//${window.location.host}`) || 
        url.startsWith("/")) {
      return {
        url,
        headers: { Authorization: `Bearer ${newToken}` }
      };
    }
    return { url };
  };
  
  // 关键步骤：更新地图实例的请求转换函数
  mapInstance.setTransformRequest(newTransformRequest);
}

最佳实践建议

1. 令牌生命周期管理：建立令牌有效期监控机制，在令牌即将过期前主动更新
2. 错误处理：监听地图的 error 事件，特别处理 401 错误，触发令牌更新流程
3. 性能优化：避免频繁调用 setTransformRequest，只在令牌确实变化时更新
4. 状态同步：确保应用其他部分（如 API 调用）与地图使用相同的令牌版本

总结

通过正确使用 setTransformRequest 方法，开发者可以确保 Maplibre GL JS 地图应用能够动态更新 WMS 请求的认证令牌，避免因令牌过期导致的服务中断。这一机制不仅适用于 OAuth2 认证场景，也可推广到其他需要动态修改请求头的应用场景中。