Spring Boot WebFlux集成HAPI FHIR Client调用API时遭遇Jackson文档嵌套深度超出限制错误

看起来你遇到的是Jackson序列化HAPI FHIR模型时的嵌套深度超限问题，咱们一步步来分析和解决：

问题背景回顾 #

你使用Spring Boot WebFlux + OpenJDK 23，通过HAPI FHIR Client调用FHIR R4的Patient资源，除了HAPI官方的sandbox外，其他所有FHIR端点都返回嵌套深度超限的错误。先把你的配置和核心代码整理出来：

依赖配置（pom.xml）

<!-- HAPI FHIR JPA Server Dependency -->
<dependency>
    <groupId>ca.uhn.hapi.fhir</groupId>
    <artifactId>hapi-fhir-client-okhttp</artifactId>
    <version>6.2.5</version>
</dependency>
<!-- Jackson for JSON parsing -->
<dependency>
    <groupId>com.fasterxml.jackson.core</groupId>
    <artifactId>jackson-databind</artifactId>
</dependency>
<!-- HAPI FHIR R4 Dependency -->
<dependency>
    <groupId>ca.uhn.hapi.fhir</groupId>
    <artifactId>hapi-fhir-structures-r4</artifactId>
    <version>6.2.5</version>
</dependency>

核心调用代码

public Mono<Patient> getPatient() {
    return Mono.deferContextual(context -> {
        String labViewStateId = context.get(Constant.REQUEST_STATE_ID);
        return cacheManager.get(labViewStateId, SmartApp.class)
                .flatMap(smartApp -> {
                    if (smartApp == null) {
                        return Mono.error(new IllegalArgumentException("Invalid Application ID"));
                    }
                    IGenericClient fhirClient = createFhirClient(smartApp);
                    return Mono.fromCallable(() -> fhirClient.read()
                            .resource(Patient.class)
                            .withId(smartApp.getAuthToken().getPatientIdentifier())
                            .execute());
                });
    });
}

private IGenericClient createFhirClient(SmartApp smartApp) {
    IGenericClient fhirClient = fhirContext.newRestfulGenericClient(smartApp.getIssuer());
    fhirClient.registerInterceptor(new BearerTokenAuthInterceptor(smartApp.getAuthToken().getAccessToken()));
    fhirClient.registerInterceptor(new LoggingInterceptor(true));
    
    return fhirClient;
}

报错信息核心片段

Caused by: com.fasterxml.jackson.core.exc.StreamConstraintsException: Document nesting depth (1001) exceeds the maximum allowed (1000, from `StreamWriteConstraints.getMaxNestingDepth()`)

问题原因分析 #

这个错误的本质是：Jackson 2.18+默认限制了JSON序列化的最大嵌套深度为1000，而你调用的第三方FHIR端点返回的Patient资源，其HAPI模型的嵌套结构（比如多层扩展、嵌套的引用元素、重复的内部结构）深度超过了这个阈值。HAPI官方sandbox返回的资源结构相对简单，所以没有触发这个限制。

另外需要注意：HAPI FHIR的Patient等Resource模型是为FHIR规范设计的专用模型，直接用Jackson默认序列化会遍历其所有内部属性，很容易导致嵌套深度超限，这并不是最优的序列化方式。

解决方案 #

下面提供两种可行的解决思路，你可以根据自己的需求选择：

方案1：调整Jackson的最大嵌套深度限制

通过定制Jackson的ObjectMapper，提高允许的最大嵌套深度。创建一个配置类即可：

@Configuration
public class JacksonCustomConfig {

    @Bean
    public Jackson2ObjectMapperBuilderCustomizer jackson2ObjectMapperBuilderCustomizer() {
        return builder -> builder.postConfigurer(objectMapper -> {
            // 调整最大嵌套深度为2000（可根据实际返回的资源结构调整）
            StreamWriteConstraints writeConstraints = StreamWriteConstraints.builder()
                    .maxNestingDepth(2000)
                    .build();
            objectMapper.getFactory().setStreamWriteConstraints(writeConstraints);
        });
    }
}

方案2：使用HAPI FHIR自带的序列化器（更推荐）

HAPI FHIR本身提供了针对FHIR规范优化的序列化器，比Jackson默认序列化更适合处理FHIR模型。你可以修改代码，直接返回序列化后的JSON字符串：

// 注入HAPI的FhirContext实例
@Autowired
private FhirContext fhirContext;

public Mono<String> getPatient() {
    return Mono.deferContextual(context -> {
        String labViewStateId = context.get(Constant.REQUEST_STATE_ID);
        return cacheManager.get(labViewStateId, SmartApp.class)
                .flatMap(smartApp -> {
                    if (smartApp == null) {
                        return Mono.error(new IllegalArgumentException("Invalid Application ID"));
                    }
                    IGenericClient fhirClient = createFhirClient(smartApp);
                    return Mono.fromCallable(() -> {
                        // 调用FHIR API获取Patient
                        Patient patient = fhirClient.read()
                                .resource(Patient.class)
                                .withId(smartApp.getAuthToken().getPatientIdentifier())
                                .execute();
                        // 用HAPI自带的序列化器转为符合FHIR规范的JSON字符串
                        return fhirContext.newJsonParser().encodeResourceToString(patient);
                    });
                });
    });
}

这种方式不仅能避免嵌套深度问题，还能保证序列化结果严格符合FHIR JSON规范，避免Jackson默认序列化可能带来的格式问题。

如果希望继续返回Mono<Patient>而不是字符串，你可以配置Spring WebFlux使用HAPI的自定义消息转换器，让框架自动处理序列化：

@Configuration
public class FhirHttpMessageConverterConfig implements WebFluxConfigurer {

    private final FhirContext fhirContext;

    public FhirHttpMessageConverterConfig(FhirContext fhirContext) {
        this.fhirContext = fhirContext;
    }

    @Override
    public void configureHttpMessageConverters(List<HttpMessageConverter<?>> converters) {
        // 添加HAPI FHIR的JSON消息转换器
        converters.add(new FhirHttpMessageConverter(fhirContext, MediaType.APPLICATION_JSON));
        // 如需支持XML，可添加对应的转换器
        converters.add(new FhirHttpMessageConverter(fhirContext, MediaType.APPLICATION_XML));
    }

    // 自定义HAPI FHIR消息转换器
    static class FhirHttpMessageConverter extends AbstractHttpMessageConverter<Resource> {

        private final IParser parser;

        public FhirHttpMessageConverter(FhirContext fhirContext, MediaType mediaType) {
            super(mediaType);
            // 根据媒体类型选择对应的解析器
            if (mediaType.equals(MediaType.APPLICATION_JSON)) {
                this.parser = fhirContext.newJsonParser();
            } else if (mediaType.equals(MediaType.APPLICATION_XML)) {
                this.parser = fhirContext.newXmlParser();
            } else {
                throw new IllegalArgumentException("Unsupported media type: " + mediaType);
            }
        }

        @Override
        protected boolean supports(Class<?> clazz) {
            return Resource.class.isAssignableFrom(clazz);
        }

        @Override
        protected Resource readInternal(Class<? extends Resource> clazz, HttpInputMessage inputMessage) throws IOException {
            return parser.parseResource(clazz, inputMessage.getBody());
        }

        @Override
        protected void writeInternal(Resource resource, HttpOutputMessage outputMessage) throws IOException {
            parser.encodeResourceToStream(resource, outputMessage.getBody());
        }
    }
}

配置完成后，Spring WebFlux会自动用HAPI的序列化器处理Patient对象，无需修改业务代码。

备注：内容来源于stack exchange，提问作者Hi10