SpringDoc OpenAPI 中的并发安全问题分析与解决方案

问题背景

SpringDoc OpenAPI 是一个流行的 Spring Boot 集成 OpenAPI/Swagger 的工具库。在项目使用过程中，开发人员报告了一个 ArrayIndexOutOfBoundsException 异常问题，该问题出现在 SwaggerUiConfigParameters 类中，特别是在处理 Swagger UI 配置参数时。

问题现象

异常主要发生在以下场景：

1. 当多个并发请求同时访问 Swagger UI 相关端点时
2. 在服务器初始启动阶段，首次加载 API 文档时
3. 使用 GroupedOpenApi 配置多个 API 分组时

异常堆栈显示问题出现在 SwaggerUiConfigParameters 类的 getConfigParameters 方法中，具体是在对配置参数进行流式处理和收集时发生的数组越界错误。

根本原因分析

经过深入分析，发现问题的根本原因在于以下几个方面：

1. 线程安全问题：SwaggerWelcomeWebFlux 类作为单例，但其 oauthPrefix 字段（UriComponentsBuilder 类型）被多个线程共享和修改。UriComponentsBuilder 本身不是线程安全的类。

2. 并发修改集合：SwaggerUiConfigParameters 类中的 urls 集合（HashSet 类型）在多线程环境下被同时读取和修改，没有适当的同步机制。

3. 状态流操作：在流式处理配置参数时使用了排序等有状态操作，这些操作在多线程环境下可能产生不可预期的行为。

解决方案

针对上述问题，社区提出了几种解决方案：

1. 线程局部变量：对于需要在请求间共享但又需要线程安全访问的变量，使用线程局部存储或每次请求创建新实例。

2. 线程安全集合：将 HashSet 替换为 CopyOnWriteArraySet 等线程安全集合实现，或者在使用集合时进行防御性拷贝。

3. 同步控制：在关键代码段使用 synchronized 或 ReentrantLock 进行同步控制，确保同一时间只有一个线程能修改共享状态。

4. 不可变对象：尽可能使用不可变对象和不可变集合，避免共享状态被意外修改。

最佳实践建议

基于此问题的解决经验，建议在使用 SpringDoc OpenAPI 时注意以下几点：

1. 版本选择：建议使用 2.7.0 及以上版本，其中已包含相关修复。

2. 并发测试：对于生产环境应用，建议进行高并发场景下的测试，特别是应用启动后的首次请求。

3. 配置简化：尽量减少动态配置的使用，特别是那些需要在运行时根据请求修改的配置。

4. 监控机制：实施适当的监控和告警机制，及时发现和解决类似问题。

总结

SpringDoc OpenAPI 中的这个并发安全问题展示了在开发库时考虑线程安全的重要性。通过分析这个问题，我们不仅解决了具体的异常，也加深了对 Spring 生态中并发编程的理解。这类问题的解决往往需要综合考虑性能、正确性和代码复杂度等因素，找到最适合的平衡点。

对于库的维护者来说，这类问题的解决也提醒我们需要更加重视并发场景下的测试，确保库在各种使用场景下都能稳定工作。对于使用者来说，则需要注意及时更新库版本，并在自己的应用中实施适当的并发控制策略。