SpringDoc OpenAPI 中基于请求头动态定制服务器基础URL的实践方案

在现代微服务架构中，API网关作为统一入口负责路由转发和请求处理是常见的设计模式。本文将以SpringDoc OpenAPI项目为例，深入探讨如何根据请求头信息动态调整API文档中的服务器基础URL(serverBaseUrl)，特别是在网关剥离路径前缀场景下的解决方案。

一、问题背景

在微服务架构中，我们通常会遇到这样的场景：

1. 网关统一处理所有/services/*路径的请求
2. 网关在转发时会剥离/services前缀
3. 需要让生成的OpenAPI文档正确反映完整的访问路径

传统方案中，开发者需要手动处理X-Forwarded-Prefix等请求头信息来重建完整的访问URL。SpringDoc OpenAPI虽然提供了ServerBaseUrlCustomizer接口，但在WebFlux环境下，特别是使用多组API时，现有的定制方案存在局限性。

二、技术方案演进

2.1 MVC模式下的解决方案

对于传统的Spring MVC应用，可以通过定义请求作用域的Bean来实现：

@RequestScope
@Bean
public ServerBaseUrlCustomizer microserviceBaseUrlCustomizer(HttpServletRequest request) {
    return serverBaseUrl -> {
        String forwardedPrefix = request.getHeader("X-Forwarded-Prefix");
        return forwardedPrefix == null 
            ? serverBaseUrl
            : UriComponentsBuilder.fromUriString(serverBaseUrl)
                .path(forwardedPrefix)
                .build()
                .toString();
    };
}

这种方案利用了Spring的请求作用域和现有的ServerBaseUrlCustomizer接口，实现简单直接。

2.2 WebFlux基础方案

对于响应式WebFlux应用，当不使用API分组时，可以通过继承OpenApiWebfluxResource类来覆盖默认行为：

@RestController
public class CustomOpenApiWebfluxResource extends OpenApiWebfluxResource {
    // 构造器注入省略...
    
    @Override
    protected String getServerUrl(ServerHttpRequest serverHttpRequest, String apiDocsUrl) {
        String serverBaseUrl = super.getServerUrl(serverHttpRequest, apiDocsUrl);
        List<String> forwardedPrefix = serverHttpRequest.getHeaders().get("X-Forwarded-Prefix");
        if (!forwardedPrefix.isEmpty()) {
            return UriComponentsBuilder.fromUriString(serverBaseUrl)
                .path(forwardedPrefix.get(0))
                .build()
                .toString();
        }
        return serverBaseUrl;
    }
}

2.3 WebFlux多组API的挑战

当应用使用API分组功能时，上述方案就无法满足需求了，因为：

1. 每个API组可能有不同的基础路径
2. 现有的定制接口无法访问请求对象
3. 需要更灵活的定制方式

三、最佳实践方案

经过社区讨论和贡献，SpringDoc OpenAPI现已支持更灵活的定制方式。推荐的技术方案是：

3.1 新增定制接口

针对不同技术栈，新增了两个专用接口：

对于WebFlux应用：

@FunctionalInterface
public interface ServerBaseUrlRequestCustomizer {
    String customize(ServerHttpRequest serverBaseUrl);
}

对于Servlet应用：

@FunctionalInterface
public interface ServerBaseUrlRequestCustomizer {
    String customize(HttpServletRequest serverBaseUrl);
}

3.2 实现原理

1. 请求上下文感知：新接口直接接收请求对象作为参数
2. 灵活定制：开发者可以基于完整的请求信息进行URL构建
3. 兼容性：与现有API设计保持兼容，不会破坏现有实现

四、应用场景扩展

这种动态URL定制方案不仅适用于网关前缀场景，还可应用于：

1. 多租户系统的租户路径识别
2. 区域化部署的区域前缀处理
3. 蓝绿部署的版本路径区分
4. 基于请求特征的动态路由

五、总结

SpringDoc OpenAPI通过引入请求感知的URL定制接口，为复杂部署环境下的API文档生成提供了更强大的灵活性。这一改进特别适合现代云原生架构下的微服务系统，使得API文档能够准确反映实际的访问路径，提升开发者体验。

对于正在实施微服务架构的团队，建议评估自身的路由策略和API文档需求，适时采用这种动态URL定制方案，以确保内外接口定义的一致性。