Resource вместо File-кода

1. Внешние шаблоны в ContextFlow

Когда проект маленький, очень легко начать “прикручивать” текст прямо в Java: "... order created ..." здесь, "... cancelled ..." там. Пока строк две — всё терпимо. Но как только вы хотите нормальный текст уведомления, шапку отчёта и пару вариантов формулировок, код превращается в литературный кружок внутри @Service‑класса, а поддерживать это начинает быть так же “приятно”, как делать merge конфликт в файле на 2000 строк.

В ContextFlow уже есть логика уведомлений и отчётности. Это значит, что у нас появляются данные, которые живут рядом с приложением, но не обязаны быть частью Java‑кода. Самый простой пример — текст уведомления “заказ создан” и “заказ отменён”. Мы хотим хранить эти тексты в src/main/resources, чтобы они поставлялись вместе с приложением, были версионируемыми в Git и не требовали перекомпиляции, если поменялась формулировка.

Мы уже выносили наружу настройки и режимы сборки. С текстовыми артефактами логика та же: это часть приложения, но не часть бизнес-кода. Поэтому сначала отделим сам ресурс от обычного пути к файлу, а потом уже будем решать, как такой ресурс входит в wiring.

И тут важно поймать главный смысловой сдвиг дня. Мы хотим говорить не “вот путь до файла”, а “вот ресурс приложения: шаблон уведомления о создании заказа”. То есть думать не про то, где лежит файл, а про то, какое место этот текст занимает в системе. Это звучит почти философски, но на практике спасает от кучи глупых багов.

2. Хрупкость подхода с File

Если вы уже писали консольные приложения, рука автоматически тянется к чему-то вроде new File("..."). И это нормально: File кажется простым и честным. Но у File есть важное скрытое предположение: “ресурс — это файл в файловой системе”. А в приложении на Spring (и вообще в Java‑мире) это предположение довольно часто неверно.

Давайте посмотрим на типичный “невинный” код:

import java.io.File;

// ВАЖНО: путь относительный — он считается от текущей рабочей директории (user.dir),
// а не “от корня проекта” и не “от src/main/resources”.
File template = new File("src/main/resources/templates/notifications/order-created.txt");

System.out.println(template.exists()); // true (иногда), false (в другой вселенной)
System.out.println(template.getAbsolutePath()); // помогает понять, где JVM реально “ищет” файл

На вашем компьютере из IDE это может “случайно” работать. Обычно потому, что текущая рабочая директория (user.dir) совпадает с корнем проекта, и путь src/main/resources/... действительно существует. Но это не делает код правильным — это делает его зависимым от того, как именно вы запустили программу.

Чтобы почувствовать хрупкость, достаточно добавить одну строку:

// Диагностика: смотрим, откуда на самом деле считаются относительные пути.
System.out.println(System.getProperty("user.dir")); // например: /Users/you/projects/spring-core-contextflow

Сегодня user.dir — корень проекта. Завтра вы запускаете через Gradle из другой директории, или IDE решила стартовать с папки модуля, или тесты запускаются из CI, где структура другая. И ваш “путь к шаблону” превращается в тыкву.

Вторая (и ещё более важная) проблема: src/main/resources — это структура исходников, а не “папка, в которой приложение ищет ресурсы во время работы”. В собранном приложении src/main/resources может вообще не существовать. Когда вы делаете jar, ваши ресурсы попадают внутрь jar‑файла, а jar — это не папка в файловой системе в обычном смысле. Это архив. И там уже нельзя честно сказать: “дай мне File”. Можно сказать: “дай мне поток байтов”.

И вот здесь File начинает вести себя как друг, который обещал помочь с переездом, но внезапно “ой, я в отпуске”. Формально он не виноват: File просто не про это.

3. Resource в Spring: «ручка» к содержимому

Чтобы не строить приложение вокруг предположения “всё — файл”, Spring предлагает абстракцию Resource. Идея простая: ресурс — это не обязательно файл, но это то, откуда можно получить содержимое. Иногда оно лежит в classpath (внутри jar), иногда — в файловой системе, иногда — по URL. Наш код при этом не должен переписываться каждый раз, когда меняется способ доставки.

Технически это интерфейс org.springframework.core.io.Resource. Он не “читает текст за вас” и не превращает мир в радугу, но он даёт общий контракт: “я могу существовать”, “у меня есть описание”, “я могу дать InputStream”.

Самый минимальный пример с classpath‑ресурсом выглядит так:

import org.springframework.core.io.ClassPathResource;
import org.springframework.core.io.Resource;

// Путь задаём ВНУТРИ classpath (то есть относительно src/main/resources),
// без префикса src/main/resources.
Resource template = new ClassPathResource("templates/notifications/order-created.txt");

System.out.println(template.exists());         // true (если ресурс реально есть)
System.out.println(template.getDescription()); // удобно для отладки: откуда ресурс взяли

Обратите внимание: мы не говорим src/main/resources/.... Мы говорим путь внутри classpath. Это очень важная разница.

А вот ещё более “прикладной” мини‑пример, который показывает главное: Resource — это не текст, а вход в чтение:

import java.nio.charset.StandardCharsets;

import org.springframework.core.io.ClassPathResource;

var resource = new ClassPathResource("templates/notifications/order-created.txt");

// ВАЖНО: читаем через поток — так будет работать и для jar, и для файловой системы.
try (var in = resource.getInputStream()) { // try-with-resources гарантирует закрытие потока
    // ВАЖНО: явно задаём кодировку, чтобы не зависеть от платформы.
    String text = new String(in.readAllBytes(), StandardCharsets.UTF_8);
    System.out.println(text); // выведет содержимое шаблона (если он есть)
}

Да, здесь всё ещё есть I/O. И да, поток нужно закрывать. Но ключевой выигрыш в другом: этот код будет работать, даже если ресурс окажется внутри jar (то есть “не как файл”). Потому что “внутри jar” можно открыть поток, а “внутри jar” нельзя гарантировать File.

Чтобы закрепить в голове отличие, полезно сравнить File и Resource чуть более системно:

Можно сказать так: File — это “адрес дома”, а Resource — это “контакт, по которому можно получить посылку”. Посылка может приехать курьером, почтой или телепортом. Вам важна посылка.

4. Classpath и ресурсы в рантайме

Слово classpath звучит как заклинание из Java‑хогвартса, но на уровне здравого смысла всё довольно приземлённо. Classpath — это набор мест, где JVM ищет классы и ресурсы. Когда вы кладёте файлы в src/main/resources, Gradle (и IDE) делают так, чтобы эти файлы попали в classpath при запуске. Но в рантайме приложение не знает и не должно знать про src/main/resources как про папку исходников.

Полезно держать в голове “путь ресурса” через сборку:

flowchart TD
  A["src/main/resources исходники"] --> B["build/resources/main результат сборки"]
  B --> C["jar-файл упаковка"]
  C --> D["classpath в рантайме где JVM ищет ресурсы"]

Когда вы запускаете приложение из IDE, ресурсы часто лежат как обычные файлы в build/resources/main. Поэтому кажется, что “это же просто файл”. Но при запуске из jar это уже не “просто файл”, а запись внутри архива. Именно поэтому Resource и “потоковая” модель чтения — базовая.

Если хочется увидеть это глазами, можно так (чистая Java, без Spring):

var cl = Thread.currentThread().getContextClassLoader();
var url = cl.getResource("templates/notifications/order-created.txt");

// Важный момент: протокол может быть file: (ресурс на диске) или jar: (ресурс внутри jar).
System.out.println(url); // file:/.../build/resources/main/... или jar:file:/.../app.jar!/...

И вот тут обычно наступает момент просветления. URL может быть file: (когда ресурс реально как файл) или jar: (когда ресурс внутри jar). Оба варианта нормальны. Ненормально — если ваш код работает только с одним вариантом, а второй ломает приложение.

5. Шаблоны как зависимость Resource

В нашем проекте правильное направление — не разбрасывать по сервисам строки путей и new File(...), а хотя бы на уровне wiring описать ресурс как зависимость. Пока без чтения и кэша: здесь нам важно одно — класс должен просить у контейнера “шаблон создания заказа”, а не сам лазить в файловую систему.

Начнём с того, что зарегистрируем Resource как обычный bean в конфигурации. Да, Resource — это тоже объект, и его можно внедрять через конструктор как любую другую зависимость.

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;
import org.springframework.core.io.Resource;

@Configuration
public class TemplatesConfig {

    @Bean
    Resource orderCreatedTemplate() {
        // Resource-бины — нормальная практика: это “инфраструктурная зависимость”, а не бизнес-логика.
        return new ClassPathResource("templates/notifications/order-created.txt");
    }
}

Теперь сделаем маленький holder, который получает ресурс через конструктор. Когда таких ресурсов станет больше одного, @Qualifier — это нормальный способ явно показать, какой именно нужен.

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.core.io.Resource;
import org.springframework.stereotype.Component;

@Component
public class OrderCreatedTemplateRef {

    // Храним Resource как зависимость: это “ручка” к содержимому, а не путь к файлу.
    private final Resource orderCreatedTemplate;

    public OrderCreatedTemplateRef(
            // Qualifier фиксирует, какой именно Resource-бин нам нужен.
            @Qualifier("orderCreatedTemplate") Resource orderCreatedTemplate) {
        this.orderCreatedTemplate = orderCreatedTemplate;
    }
}

Пока мы ничего не читаем. Это важно: мы просто сделали модель зависимости правильной. Теперь класс не говорит “я залезу в файловую систему туда-то”, он говорит “мне нужен ресурс ‘шаблон создания заказа’”. Это ровно тот уровень абстракции, который делает код переносимым.

Если вам очень хочется проверить, что всё правда работает, можно (временно, для диагностики) вывести описание ресурса, не читая его содержимое:

import org.springframework.stereotype.Component;

@Component
public class TemplateDiagnostics {

    public TemplateDiagnostics(OrderCreatedTemplateRef templateRef) {
        // Диагностический “якорь”: позволяет убедиться, что контекст поднялся и зависимости провайрятся.
        System.out.println("Templates are wired."); // Templates are wired.
    }
}

Да, это “учебная заглушка”. Но смысл в том, что wiring уже выглядит правильно: Resource живёт в инфраструктуре и внедряется контейнером, а не создаётся через new File(...) где-нибудь глубоко в бизнес-методе. Чтение текста — это уже отдельная обязанность.

Самое приятное, что с этого момента вы можете поменять способ хранения шаблона, не переписывая сервисы. Сегодня это classpath, завтра — другой источник. (Мы не будем сейчас усложнять; главное — вы уже не заперли себя в File‑мире.)

6. Типичные ошибки при переходе от File к Resource

Когда вы впервые начинаете работать с Resource, мозг по инерции продолжает думать в категориях “папка/файл/путь”, и это нормально. Но есть несколько ошибок, которые появляются почти у всех, и лучше поймать их сейчас, пока они не превратились в “традиции проекта”.

Ошибка №1: использовать путь src/main/resources/... как “путь к ресурсу”.
Это путь к исходникам в репозитории, а не к ресурсу в рантайме. В рантайме нужно мыслить “путь внутри classpath”. Если вы видите строку src/main/resources внутри приложения — это почти всегда сигнал, что вы случайно привязались к структуре проекта, а не к модели поставки ресурса.

Ошибка №2: ожидать, что Resource — это обязательно File, и пытаться мыслить диском.
Психологически хочется: “ну раз ресурс — это файл, я возьму getFile() и буду жить спокойно”. Проблема в том, что classpath‑ресурс не обязан быть дисковым файлом. Он может быть внутри jar. Поэтому ваш безопасный “универсальный” путь — чтение через getInputStream().

Ошибка №3: держать пути к шаблонам прямо в бизнес‑сервисах.
Если OrderPlacementService знает, что шаблон лежит в templates/notifications/..., то бизнес‑сервис внезапно начинает зависеть от структуры ресурсов. Это почти то же самое, что заставить доменную модель знать, где лежит application.properties. Лучше пусть бизнес‑слой зависит от “каталога шаблонов”, а не от строк.

Ошибка №4: считать, что Resource “решил всё” и теперь можно не думать про I/O.
Resource — это отличный вход в чтение, но он не отменяет реальность: поток нужно закрывать, кодировку нужно выбирать, ошибки нужно обрабатывать. Если сделать вид, что чтение “не может упасть”, вы получите либо непонятные NPE, либо тихие пустые шаблоны, которые потом всплывут в самом неприятном месте (обычно в демо перед руководителем).