API Platform多应用环境下Swagger文档缓存冲突问题解析

问题背景

在使用API Platform构建多应用系统时，开发者可能会遇到一个棘手的问题：当系统包含多个独立应用（每个应用都有自己的API文档）时，首次加载各应用的Swagger文档显示正常，但在刷新页面后，所有应用的文档会显示相同内容。

问题现象

在多应用架构中（例如基于Symfony的多内核配置），每个应用都有自己独立的API文档配置。初始状态下：

1. 应用A的Swagger文档正确显示A应用的API接口
2. 应用B的Swagger文档正确显示B应用的API接口

但在刷新任意一个应用的页面后：

1. 所有应用的Swagger文档都会显示相同内容（通常是最后加载的那个应用的API接口）

问题根源

经过深入分析，发现问题的根源在于API Platform的缓存机制。具体表现为：

1. API Platform使用CachedResourceNameCollectionFactory来缓存资源名称集合
2. 默认的缓存键生成策略没有考虑应用之间的区分
3. 导致不同应用在访问Swagger文档时，可能读取到相同的缓存结果

解决方案

方案一：自定义缓存键生成策略

通过继承并重写CachedResourceNameCollectionFactory类，可以修改缓存键的生成逻辑，确保每个应用有独立的缓存空间：

namespace Shared\ApiPlatform\Metadata\Resource\Factory;

use ApiPlatform\Metadata\Resource\Factory\CachedResourceNameCollectionFactory as BaseCachedResourceNameCollectionFactory;
use Symfony\Component\HttpFoundation\RequestStack;

class CachedResourceNameCollectionFactory extends BaseCachedResourceNameCollectionFactory
{
    private $requestStack;
    
    public function __construct($cache, $decorated, RequestStack $requestStack)
    {
        parent::__construct($cache, $decorated);
        $this->requestStack = $requestStack;
    }
    
    protected function getCacheKey(): string
    {
        // 添加主机名作为缓存键的一部分
        $request = $this->requestStack->getCurrentRequest();
        return $request ? $request->getHost().parent::getCacheKey() : parent::getCacheKey();
    }
}

方案二：服务配置覆盖

在服务配置中覆盖默认的缓存工厂服务：

services:
    api_platform.metadata.resource.name_collection_factory.cached:
        class: Shared\ApiPlatform\Metadata\Resource\Factory\CachedResourceNameCollectionFactory
        arguments:
            - '@api_platform.cache.metadata.resource'
            - '@api_platform.metadata.resource.name_collection_factory.cached.inner'
            - '@request_stack'

实现原理

这种解决方案的核心思想是通过在缓存键中加入应用特定的标识（如主机名），确保：

1. 不同应用的API文档请求会生成不同的缓存键
2. 每个应用独立维护自己的API文档缓存
3. 避免了缓存冲突问题

最佳实践建议

1. 明确应用边界：在多应用架构中，确保每个应用有明确的域名或路径区分
2. 缓存隔离：不仅API文档，其他缓存也应考虑应用隔离
3. 环境区分：开发、测试、生产环境的缓存也应相互隔离
4. 监控机制：建立缓存命中/失效的监控，确保缓存机制正常工作

总结

API Platform作为强大的API开发框架，在多应用环境下使用时需要注意缓存隔离问题。通过自定义缓存键生成策略，可以有效地解决Swagger文档在多应用间的冲突问题，确保每个应用能够正确显示自己的API文档。这种解决方案不仅适用于Swagger文档，也可以推广到其他需要应用隔离的缓存场景中。