Écrire un fichier Java - Le guide complet pour maîtriser l'I/O

Écrire dans un fichier en Java semble trivial au premier regard, mais le bon choix dépend surtout du volume de texte, du besoin d’append, du format produit et du niveau de contrôle voulu sur l’encodage. Entre une chaîne courte, une suite de lignes ou un flux généré par une application backend, les bonnes API ne sont pas les mêmes. Je vais donc aller à l’essentiel: quelle méthode utiliser, comment éviter d’écraser un fichier par erreur, et quels réglages font vraiment la différence en pratique.

Quelle méthode utiliser selon le cas

Si je dois trancher vite, je pars d’une règle simple: texte court et déjà construit avec `Files.writeString`, écriture progressive ou volumineuse avec `Files.newBufferedWriter`, et liste de lignes prête avec `Files.write(...)`. `FileWriter` reste utilisable, mais il est moins explicite sur l’encodage et moins agréable à maintenir dans un codebase récent.

Cette grille me sert de filtre mental avant d’écrire la moindre ligne de code. Une fois la méthode choisie, le vrai sujet devient beaucoup plus concret: comment écrire proprement le contenu sans perdre de temps sur les détails invisibles comme le séparateur de lignes ou le charset.

Écrire directement un texte avec Files.writeString

Quand le contenu est déjà prêt sous forme de String, c’est la solution la plus nette. Le point important à retenir est simple: `writeString` écrit le texte tel quel. Si vous voulez plusieurs lignes, c’est à vous d’insérer les retours à la ligne dans la chaîne.

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;

public class Exemple {
    public static void main(String[] args) throws IOException {
        Path path = Path.of("rapport.txt");

        String contenu = "Premier bloc" + System.lineSeparator()
                + "Deuxième bloc";

        Files.writeString(path, contenu, StandardCharsets.UTF_8);
    }
}

Dans ce cas, le fichier est créé s’il n’existe pas, et son contenu est remplacé s’il existe déjà. C’est exactement ce qu’on veut pour un export, un fichier de configuration généré ou un résultat de traitement qui doit rester à l’état le plus récent. Si, au contraire, vous devez ajouter du texte sans effacer ce qui est déjà présent, il faut le dire explicitement avec les options d’ouverture.

Files.writeString(
    Path.of("rapport.txt"),
    "Nouvelle ligne" + System.lineSeparator(),
    StandardCharsets.UTF_8,
    java.nio.file.StandardOpenOption.CREATE,
    java.nio.file.StandardOpenOption.APPEND
);

Le piège classique ici, c’est d’oublier que Java n’ajoute pas magiquement de saut de ligne pour vous. Si vous n’en mettez pas dans la chaîne, vous obtiendrez une suite compacte de caractères. Dès qu’on passe d’un texte ponctuel à une génération plus longue, je bascule donc vers une écriture ligne par ligne, plus lisible et plus robuste.

Écrire ligne par ligne avec BufferedWriter

Pour un rapport, un journal applicatif ou un fichier texte construit progressivement, BufferedWriter est souvent le meilleur compromis. Le buffering réduit le nombre d’accès disque, et la méthode newLine() évite de bricoler à la main les séparateurs de lignes selon l’OS.

import java.io.BufferedWriter;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardOpenOption;
import java.util.List;

public class Rapport {
    public static void ecrireRapport(Path path, List lignes) throws IOException {
        try (BufferedWriter writer = Files.newBufferedWriter(
                path,
                StandardCharsets.UTF_8,
                StandardOpenOption.CREATE,
                StandardOpenOption.TRUNCATE_EXISTING)) {

            writer.write("Rapport d'analyse");
            writer.newLine();

            for (String ligne : lignes) {
                writer.write(ligne);
                writer.newLine();
            }
        }
    }
}

Je préfère cette approche quand le fichier peut grossir, quand la structure évolue au fil du traitement ou quand je veux garder une logique très lisible dans le code. Un détail compte ici: `newLine()` s’adapte au séparateur de ligne de la plateforme, ce qui est plus sain que de multiplier les "\n" écrits à la main. Et comme le writer est fermé dans un try-with-resources, le flush final est géré proprement sans code supplémentaire.

Choisir le bon encodage et les bonnes options d’ouverture

Le sujet de l’encodage est souvent sous-estimé, alors qu’il suffit d’un mauvais choix pour corrompre les accents, les apostrophes ou certains caractères techniques. En pratique, UTF-8 est le meilleur point de départ dans un projet moderne, surtout dans un contexte web ou backend où les fichiers circulent entre plusieurs machines.

Le comportement par défaut mérite d’être lu deux fois: sans options explicites, les API modernes ouvrent généralement le fichier en mode écriture avec création et troncature. Autrement dit, si vous ne faites rien de spécial, vous risquez surtout d’écraser. Pour ajouter du contenu, je conseille de penser en couple CREATE + APPEND dès que le fichier peut ne pas exister au lancement.

Un autre point concret concerne les retours à la ligne. Si vous produisez un fichier destiné à être relu sur plusieurs systèmes, n’écrivez pas de logique implicite autour d’un séparateur fixe. Utilisez soit BufferedWriter.newLine(), soit System.lineSeparator(), mais choisissez une seule stratégie et gardez-la cohérente.

Quand l’encodage et l’ouverture sont clairs, les erreurs les plus fréquentes deviennent bien plus faciles à repérer. C’est justement là que les projets Java gagnent en fiabilité, surtout quand plusieurs développeurs touchent au même code.

Les erreurs que je vois le plus souvent

Le premier piège, c’est l’écrasement involontaire. Beaucoup de développeurs testent leur code sur un petit fichier local, voient que tout fonctionne, puis découvrent plus tard qu’un export a remplacé des données utiles. Si le fichier doit rester un historique, l’option APPEND doit être explicite, pas supposée.

• Oublier le charset: sur une machine ça passe, sur une autre les accents se dégradent.
• Utiliser `FileWriter` sans buffering dans une boucle: ça fonctionne, mais c’est rarement le choix le plus propre.
• Confondre texte et binaire: pour une image, un PDF ou un fichier compressé, il faut écrire des octets, pas des chaînes.
• Ajouter des retours à la ligne à la main partout: le code devient vite moins portable et moins lisible.
• Ignorer le répertoire cible: si le dossier parent n’existe pas, l’écriture échoue.
• Flusher trop souvent: utile seulement si vous avez un besoin précis de visibilité immédiate, pas par réflexe.

Si le besoin dépasse la simple écriture d’un bloc de texte, je préfère encapsuler la logique dans une petite méthode dédiée plutôt que de disperser les options partout dans l’application. C’est plus lisible, et surtout plus facile à faire évoluer sans casser les appels existants.

Le modèle que je réutilise pour un backend Java

Quand je dois écrire un fichier dans un service backend, je pars souvent d’un helper très simple. Il centralise l’encodage, les options d’ouverture et la ligne finale, ce qui évite les variations accidentelles entre deux équipes ou deux points d’entrée du code.

import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardOpenOption;

public class Fichiers {

    public static void appendLine(Path path, String line) throws IOException {
        try (var writer = Files.newBufferedWriter(
                path,
                StandardCharsets.UTF_8,
                StandardOpenOption.CREATE,
                StandardOpenOption.APPEND)) {
            writer.write(line);
            writer.newLine();
        }
    }
}

Ce schéma marche bien pour des logs métiers, des traces d’audit ou des exports incrémentaux. Si, au contraire, le fichier doit être régénéré à chaque exécution, je remplace simplement APPEND par TRUNCATE_EXISTING. C’est cette simplicité qui me plaît: le code raconte son intention sans effort supplémentaire.

Au fond, écrire un fichier en Java n’est pas une question de syntaxe, mais de contrôle: savoir si l’on remplace, si l’on ajoute, si l’on écrit une ligne ou un bloc, et si l’on verrouille correctement l’encodage. Si vous retenez une seule règle, gardez celle-ci: `Files.writeString` pour le texte simple, `Files.newBufferedWriter` dès qu’il faut un vrai flux d’écriture. C’est le duo qui couvre la majorité des cas sans complexité inutile.