Common Feign Pitfalls and How to Solve Them

In a Spring Cloud architecture, microservice communication often relies on Feign. The article first compares two ways to declare Feign clients: (1) defining the client in the producer's API and autowiring it in the consumer, which is simple but can lead to a cluttered interface list and requires scanning multiple packages; (2) creating a dedicated API module that both producer and consumer depend on, allowing consumers to customize their clients and control circuit‑breaker logic, at the cost of some code duplication. The author recommends the second approach for clearer responsibilities.

Feign Interface Packaging

When a backend returns a unified response object (e.g., ResultData) to the frontend, Feign callers end up wrapping and unwrapping this object repeatedly, violating the DRY principle. To avoid this, the article proposes using ResponseBodyAdvice to automatically wrap responses only for gateway calls while returning raw entities for Feign calls.

Two detection methods are discussed:

Custom annotation on Feign interfaces (e.g., @Inner) to identify Feign requests.

Feign interceptor that adds a special request header ( T_REQUEST_ID) to mark Feign calls.

The interceptor implementation:

@Bean
public RequestInterceptor requestInterceptor() {
    return requestTemplate -> {
        ServletRequestAttributes attrs = (ServletRequestAttributes) RequestContextHolder.getRequestAttributes();
        if (attrs != null) {
            HttpServletRequest request = attrs.getRequest();
            Map<String, String> headers = getRequestHeaders(request);
            for (Map.Entry<String, String> e : headers.entrySet()) {
                requestTemplate.header(e.getKey(), e.getValue());
            }
            if (request.getHeader(T_REQUEST_ID) == null) {
                requestTemplate.header(T_REQUEST_ID, UUID.randomUUID().toString());
            }
        }
    };
}

The corresponding ResponseBodyAdvice checks this header and either returns the raw object (for Feign) or wraps it in ResultData.success(...) (for gateway calls):

@RestControllerAdvice(basePackages = "com.javadaily")
public class BaseResponseAdvice implements ResponseBodyAdvice<Object> {
    @Autowired
    private ObjectMapper objectMapper;

    @Override
    public boolean supports(MethodParameter methodParameter, Class<? extends HttpMessageConverter<?>> aClass) {
        return true;
    }

    @Override
    public Object beforeBodyWrite(Object body, MethodParameter methodParameter, MediaType mediaType,
                                Class<? extends HttpMessageConverter<?>> aClass,
                                ServerHttpRequest request, ServerHttpResponse response) {
        boolean isFeign = request.getHeaders().containsKey(OpenFeignConfig.T_REQUEST_ID);
        if (isFeign) {
            return body;
        }
        if (body instanceof String) {
            return objectMapper.writeValueAsString(ResultData.success(body));
        }
        if (body instanceof ResultData) {
            return body;
        }
        return ResultData.success(body);
    }
}

Feign Exception Handling

Producers may throw a business exception ( BizException) which is normally caught by a global exception handler and wrapped into ResultData. When Feign receives this 200‑OK response, the client cannot deserialize the payload into the expected entity, resulting in null values.

Solution 1: let the global handler return a non‑200 status for business errors using @ResponseStatus(HttpStatus.INTERNAL_SERVER_ERROR). This allows Feign to treat the response as an error.

Solution 2: rewrite Feign's ErrorDecoder to extract the original BizException from the wrapped ResultData and re‑throw it, so the consumer can handle the business exception directly.

@Slf4j
public class OpenFeignErrorDecoder implements ErrorDecoder {
    @Override
    public Exception decode(String methodKey, Response response) {
        try {
            String body = Util.toString(response.body().asReader(Charset.defaultCharset()));
            ResultData<?> result = JSON.parseObject(body, ResultData.class);
            if (!result.isSuccess()) {
                return new BizException(result.getStatus(), result.getMessage());
            }
        } catch (IOException e) {
            e.printStackTrace();
        }
        return new BizException("Feign client call exception");
    }
}

The custom decoder is registered in a Feign configuration class:

@Configuration
@ConditionalOnClass(Feign.class)
public class OpenFeignConfig {
    @Bean
    public ErrorDecoder errorDecoder() {
        return new OpenFeignErrorDecoder();
    }
}

After applying these changes, Feign calls return the raw entity on success, and business exceptions propagate correctly without double wrapping.