SpringDoc OpenAPI 中 ServerBaseUrl 线程安全问题分析与解决方案

问题背景

在使用 SpringDoc OpenAPI 进行 API 文档生成时，开发者可能会遇到一个关于服务器基础 URL(ServerBaseUrl)的线程安全问题。这个问题主要出现在需要根据请求动态定制服务器 URL 的场景中，比如多租户系统或不同网络环境下的 URL 适配。

问题现象

当多个请求同时访问 Swagger UI 时，后到达的请求可能会覆盖先到达请求设置的服务器基础 URL，导致返回的 API 文档中服务器地址出现混乱。例如：

1. 用户A通过 http://localhost:8080 访问 Swagger UI
2. 用户B通过 http://127.0.0.1:8080 访问 Swagger UI
3. 用户A最终看到的 API 文档中服务器地址变成了 http://127.0.0.1:8080

问题根源分析

这个问题的根本原因在于 OpenAPIService 类中的 serverBaseUrl 成员变量是以非线程安全的方式被共享和修改的。具体来看：

1. OpenAPIService 是一个单例 Bean，被所有请求共享
2. setServerBaseUrl 方法直接修改成员变量 serverBaseUrl，没有使用任何同步机制
3. 当多个请求并发调用时，后执行的请求会覆盖前面请求设置的值

技术影响

这种线程安全问题会导致以下不良影响：

1. API 文档中显示的服务器地址不可靠，可能显示错误的地址
2. 在多租户系统中，可能导致租户间的 URL 信息泄露
3. 在负载均衡环境下，可能导致客户端连接到错误的服务器

解决方案

针对这个问题，有以下几种可行的解决方案：

方案一：使用线程局部变量

将 serverBaseUrl 改为使用 ThreadLocal 存储，确保每个线程有自己的副本：

private final ThreadLocal<String> serverBaseUrl = new ThreadLocal<>();

方案二：移除成员变量，改为方法参数传递

重构代码，将服务器基础 URL 作为方法参数传递，而不是存储在成员变量中：

public OpenAPI calculateOpenApi(..., String serverBaseUrl) {
    // 使用传入的 serverBaseUrl 而不是成员变量
}

方案三：同步访问

对 serverBaseUrl 的访问添加同步控制：

private final Object lock = new Object();
private String serverBaseUrl;

public void setServerBaseUrl(String url) {
    synchronized(lock) {
        this.serverBaseUrl = url;
    }
}

最佳实践建议

在实际项目中，建议采用以下最佳实践：

1. 对于需要根据请求动态确定服务器 URL 的场景，优先考虑方案一或方案二
2. 避免在单例 Bean 中存储请求特定的状态
3. 如果必须共享状态，确保使用适当的线程安全机制
4. 考虑使用不可变对象来避免并发修改问题

总结

SpringDoc OpenAPI 中的 serverBaseUrl 线程安全问题是一个典型的共享状态并发访问问题。通过分析问题根源，我们了解了多种解决方案。在实际开发中，开发者应根据具体场景选择最适合的解决方案，确保 API 文档生成的正确性和可靠性。