Lors du développement d'une fonctionnalité d'upload de fichiers, il est fréquent de rencontrer des erreurs de dépassement de capacité lorsque la taille des fichiers augmente. Par exemple, un transfert de 80 Mo peut rester en attente (pending) avant de se solder par une absence de réponse ou un messagee d'erreur spécifique côté serveur : The field file exceeds its maximum permitted size.

Configuraton de la passerelle Nginx

Avant d'analyser le code de l'application, il est nécessaire de s'assurer que le serveur mandataire (proxy) ne bloque pas la requête. Par défaut, Nginx limite souvent le corps des requêtes à 1 Mo. Voici les directives à ajuster dans le bloc http ou server de votre configuration Nginx :

client_max_body_size 100M;
client_header_timeout 60s;
client_body_timeout 60s;
proxy_connect_timeout 180s;
proxy_read_timeout 180s;
proxy_send_timeout 180s;

Limites natives de Spring Boot

Spring Boot impose ses propres restrictions sur les données multipart. Si ces limites sont atteintes, l'exception MaxUploadSizeExceededException est levée. La syntaxe de configuration dépend de la version du framework utilisée.

Pour Spring Boot 2.x et versions ultérieures :

# application.properties
spring.servlet.multipart.max-file-size=100MB
spring.servlet.multipart.max-request-size=100MB

Pour Spring Boot 1.4 à 1.5 :

# application.properties
spring.http.multipart.max-file-size=100MB
spring.http.multipart.max-request-size=100MB

Configuration programmatique via un Bean

Dans certains cas, notamment lorsque les propriétés standards ne sont pas prises en compte à cause d'une configuration personnalisée du conteneur de servlets, il est nécessaire de définir explicitement un bean MultipartConfigElement. Cette approche permet une gestion plus fine et dynamique des paramètres.

import org.springframework.boot.web.servlet.MultipartConfigFactory;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.util.unit.DataSize;
import javax.servlet.MultipartConfigElement;

@Configuration
public class UploadConfiguration {

    @Bean
    public MultipartConfigElement configurerLimitesUpload() {
        MultipartConfigFactory factory = new MultipartConfigFactory();
        
        // Définition de la taille maximale d'un fichier individuel
        factory.setMaxFileSize(DataSize.ofMegabytes(100));
        
        // Définition de la taille maximale totale de la requête (fichiers + paramètres)
        factory.setMaxRequestSize(DataSize.ofMegabytes(120));
        
        return factory.createMultipartConfig();
    }
}

Identification des configurations personnalisées

Il arrive que des projets existants utilisent des clés de configuraton non standard injectées via l'annotation @Value dans une classe de configuration. Si les modifications dans application.properties ne produisent aucun effet, il convient de rechercher dans le code source toute instanciation de MultipartConfigFactory pour identifier si des propriétés personnalisées (ex: app.upload.limit) sont utilisées à la place des clés natives de Spring.