Структурата на един проект (5): слоят, който не правеше нищо
От Dorian Chávez · съосновател и Chief Executive Officer на Hábil ·
Четири слоя и facade, която само препраща извикването. Какво отива във всеки пакет на API със Spring Boot, кога facade е излишна, и шаблон, който го пази.
Структурата на един проект · част 5 от 7 · Java със Spring Boot
Сценарий: героите и историята са измислени. Техническите данни и цитатите са с източник в края.
За 1 минута
- Spring Boot не изисква никакъв начин за подреждане на кода [1]. Слоевете са решение; ето това на шаблона, с неговото «защо».
- Всеки пакет е роля в ресторант:
apiе сервитьорът,service— готвачът,repository— килерът. И всяка роля има нещо, което никога не прави. facade, главният готвач, се оправдава, когато координира двама или повече. Ако методът ѝ само извиква друг, тя е излишна.- За Java това, че готвачът познава сервитьора, не е грешка: компилира се. Открива го архитектурен тест [12].
- Взимаш шаблон, който тръгва от първия път, със скрипт, който доказва тази граница, като става червен, когато трябва.
- За понеделник: отвори своята
facadeи преброй колко метода само извикват друг.
В тази статия
- Какво се случи в четвъртък в 16:40?
- Какво отива във всеки пакет?
- Кога да има facade и кога не?
- Кои са трите правила?
- Кои са пет чести грешки?
- Упражнение: можеш ли да накараш готвача да извика сервитьора?
- Ключови изводи
- Какво следва?
- Шаблонът и курсът
- Какво прави Hábil?
- Източници
Какво се случи в четвъртък в 16:40?
Иван добави поле към един отговор, пипна четири файла и откри слой, който не правеше нищо.
Четвъртък, 16:05. Трети етаж.
Месец след псевдонима. Първото API на Java, със Spring Boot: поръчките на един магазин. Задачата се побираше в един ред: «Справката за поръчка да казва и кога е създадена».
Проектът го беше оставил някой друг. Четири папки с имена на слоеве:
src/main/java/…/pedidos/
api/
facade/
service/
repository/Данните вече бяха в таблицата. За да стигнат до JSON-а, Иван пипна четири файла, по един във всяка папка. В три от тях копира полето от един клас в друг. В четвъртия, facade, се спря:
public PedidoResponse buscar(UUID id) {
return service.buscar(id);
}Метод, който само извикваше друг. Получаваше същото и връщаше същото. Прегледа останалите методи на класа: бяха шест, и пет правеха това.
Четвъртък, 16:40.
Компилира се. Тестовете минаха. Преди да качи промяната, писа на Лусия.
— Четири файла, за да преместя едно поле. А един слой не прави нищо: вика следващия и толкова. Да го махна ли?
— Колко извиква този метод? — отговори тя.
— Един. Услугата.
— А този, който създава поръчка?
Иван го отвори. Той беше различен: първо питаше друга система за цената, а после извикваше услугата.
— Два.
— Значи в единия главният готвач е излишен, а в другия — не.
— Какъв главен готвач?
— Утре ще обядваме в закусвалнята отсреща. Гледай кой какво прави.
Иван погледна четирите папки. Беше си мислил, че са четири задължителни стъпки. Бяха четири занаята.
Какво отива във всеки пакет?
Това, което се пада на една роля в ресторант, и нищо повече. Слоевете не ги изисква Spring Boot: те са решение.
Документацията на Spring Boot го казва още в началото: «Spring Boot does not require any specific code layout to work» [1]. Собственият ѝ пример дори не подрежда по слоеве: слага една папка за клиентите и друга за поръчките [1]. Това, което препоръчва, е къде да стои класът, който стартира приложението: «in a root package above other classes» [1]. От този пакет надолу Spring търси компонентите и обектите (entities).
Откъде тогава идват api, service и repository? От навик, който Spring носи в анотациите си: @Controller, @Service и @Repository съществуват за слоевете «persistence, service, and presentation» [2]. В Hábil това е практика на къщата: по един пакет за роля и зависимости само в една посока. Не е единственият правилен начин. Това е един, който се побира в един обяд.
Шаблонът на тази част, estructura-java-spring-boot, е API-то за поръчките на един магазин. Основният му пакет е mx.habil.pedidos: домейнът наобратно и името на приложението [1].
estructura-java-spring-boot/
├── pom.xml bibliotecas y construcción
├── mvnw · .mvn/ el Maven del proyecto
├── Dockerfile la imagen
├── docs/ARCHITECTURE.md las capas y las decisiones
├── herramientas/probar-frontera.sh
├── src/main/java/mx/habil/pedidos/
│ ├── PedidosApplication.java aquí arranca todo
│ ├── api/ el mesero
│ ├── facade/ el jefe de cocina
│ ├── service/ el cocinero
│ ├── repository/ la despensa
│ ├── client/ el proveedor de afuera
│ ├── model/ los papeles que pasan de mano en mano
│ │ ├── request/ la comanda
│ │ ├── response/ el ticket
│ │ ├── entity/ la ficha del archivo
│ │ └── vo/ las medidas exactas
│ ├── mapper/ el que pasa en limpio
│ ├── config/ la instalación del local
│ ├── exception/ el libro de quejas
│ ├── observability/ las cámaras y la bitácora
│ └── utils/ el cajón de herramientas
├── src/main/resources/application.yml
└── src/test/java/mx/habil/pedidos/ el mismo árbolsrc/main и src/test са стандартната подредба на Maven, инструмента, който изгражда проекта: тя позволява на човек, който познава един проект, да «immediately feel at home in another» [14]. mvnw е Maven Wrapper: изтегля версията на Maven, която проектът обявява, и никой не я инсталира на ръка [15].
Да вървим роля по роля. Всяка идва със своя пример от шаблона и един ред: какво никога не отива там.
Кой обслужва?
api, сервитьорът. Приема поръчката, проверява дали е попълнена добре и я предава. Не готви.
@PostMapping
public ResponseEntity<PedidoResponse> crear(@Valid @RequestBody CrearPedidoRequest comanda) {
PedidoResponse creado = facade.crear(comanda);
return ResponseEntity.created(URI.create("/v1/pedidos/" + creado.id())).body(creado);
}Всичко, което е HTTP, живее тук: пътят, глаголът, 201. @Valid е проверката: ако поръчката е попълнена зле, Spring хвърля MethodArgumentNotValidException [5] и кухнята дори не разбира. Никога не отива тук: бизнес правило. Един if върху данни от поръчката е работа на готвача.
service, готвачът. Тук живеят правилата. Шаблонът има две: поръчка не се приема, ако липсва бройка, и сумата е цена по количество.
if (linea.cantidad() > linea.existencias()) {
throw new PedidosException(CodigoError.SIN_EXISTENCIAS,
"De %s se pidieron %d y hay %d".formatted(linea.sku(), linea.cantidad(), linea.existencias()));
}
total = total.mas(linea.importe());Никога не отива тук: нито HTTP, нито JSON. Готвачът не знае дали поръчката е дошла от приложение или по телефона; затова тестовете му вървят без сървър и без база данни.
repository, килерът. Прибира и носи.
public interface PedidoRepository extends JpaRepository<PedidoEntity, UUID> {
}Това е целият интерфейс. Spring Data се грижи за «creating Repository implementations directly from interfaces» [7]. Никога не отива тук: решение. Дали една поръчка може да се запише, казва готвачът.
client, външният доставчик. Друга система, на друга машина. В шаблона това е складовата наличност: колко бройки има и на каква цена. Вика се с две предпазни мерки. Лимит за време: application.yml обявява една секунда за свързване и две за четене [8]. И повторен опит, само при мрежова грешка от тези, които Spring нарича ResourceAccessException; един 404 от доставчика е отговор и не се повтаря. Spring Framework 7 вече носи повторните опити в ядрото си [9]. Два повторни опита са три извиквания: «total attempts = 1 initial attempt + maxRetries attempts» [9]. Никога не отива тук: правило на поръчката. Нито извикване без лимит за време.
facade, главният готвач. Координира. Това е въпросът на Иван и има свой раздел.
Кои документи минават от ръка на ръка?
request е поръчката, response — касовата бележка, а entity — архивната карта. Три документа, макар да казват почти едно и също.
public record CrearPedidoRequest(
@NotBlank @Email @Size(max = 254) String correo,
@NotEmpty @Size(max = 20) List<@Valid @NotNull Linea> lineas) {Поръчката и касовата бележка са record: класове, които само носят данни, с финални полета [16]. Анотациите са от Jakarta Validation [6]. Поръчката не носи цена: цената я слага доставчикът, не клиентът. Касовата бележка не носи имейла: никой не го е поискал. Архивната карта, PedidoEntity, има формата на таблицата и е обикновен клас, защото спецификацията на JPA казва, че един record «may not be designated as an entity» [17]. Никога: архивната карта да излезе през вратата. Сервитьорът предава касовата бележка.
А останалите пакети?
vo, точната мярка. vo означава value object, обект-стойност: разпознава се по това, което струва, а не по id; два Dinero от 100 сентавос са една и съща сума. Dinero не е самотен long: това е сума в сентавос, която никога не е отрицателна. Ако съществува, вече е валидна и никой не я проверява отново. Същото и с Correo. Никога не отива тук: нещо от Spring или от друг слой.
mapper, този, който преписва на чисто. Копира от архивната карта в касовата бележка, поле по поле. Никога не отива тук: if, който решава нещо.
config, обзавеждането на заведението. Часовникът, телефонът за обаждане на доставчика, колко пъти се прави повторен опит. Нарежда се веднъж, при отварянето. Никога не отива тук: нито правила, нито пътища.
exception, книгата за оплаквания. Всичко, което може да се обърка, има код в каталог, и само едно място сглобява отговора. Формата не е наша: това е Problem Details, RFC 9457, който съществува «to avoid the need to define new error response formats for HTTP APIs» [4], и Spring вече го носи [3]. Измерено в шаблона, като се поискат четири чаши, когато има три:
{"detail":"De TAZA-01 se pidieron 4 y hay 3","instance":"/v1/pedidos","status":409,
"title":"No hay existencias suficientes",
"type":"https://pedidos.example/errors/sin_existencias","error_code":"SIN_EXISTENCIAS"}Никога не отива тук: собствен формат за грешки.
observability, камерите и дневникът. Всяка заявка получава номер, който излиза на всеки ред от дневника и се връща на клиента в X-Request-ID. Никога не отива тук: лични данни в явен вид. Измерено: pedido f6bd398a-… recibido de a***@tienda.mx por $424.00.
utils, чекмеджето с инструменти. Mascara.correo скри този имейл. Никога не отива тук: нещо, което знае какво е поръчка. Ако го знае, мястото му е в друг пакет.
По какъв път минава една поръчка?
Навътре, от вратата до килера; и по прекия път, когато няма какво да се координира.
POST /v1/pedidos GET /v1/pedidos/{id}
│ │
▼ ▼
api (mesero) revisa la comanda api (mesero)
│ │
▼ │ el atajo: lo atiende
facade (jefe de cocina) │ un solo servicio
├──► client (proveedor) ¿hay? │
▼ ▼
service (cocinero) las reglas ◄──────────────┘
│
▼
repository (despensa) guarda la fichaНа връщане архивната карта се преписва на чисто и излиза касовата бележка.
Кога да има facade и кога не?
Да, когато координира две или повече услуги или клиенти. Не, когато методът ѝ само извиква друг.
Петък, 14:10. Закусвалнята отсреща.
Лусия поръча дневното меню. Иван — само вода от хибискус. Сервитьорът остави поръчката за менюто на плота на кухнята и една жена я прочете на глас: супата от едната страна, яхнията от другата, да излязат заедно. Водата я поиска направо от този, който я наливаше.
— Ето — каза Лусия. — За менюто участват двама и някой трябва да каже реда. За водата — не.
В шаблона създаването на поръчка е дневното меню. Участват доставчикът и готвачът, в този ред:
public PedidoResponse crear(CrearPedidoRequest comanda) {
List<LineaCotizada> cotizadas = new ArrayList<>();
for (CrearPedidoRequest.Linea linea : comanda.lineas()) {
InventarioClient.Producto producto = inventario.consultar(linea.sku())
.orElseThrow(() -> new PedidosException(CodigoError.PRODUCTO_NO_EXISTE,
"No hay un producto con el sku " + linea.sku()));
cotizadas.add(new LineaCotizada(linea.sku(), linea.cantidad(), producto.existencias(),
new Dinero(producto.precioCentavos())));
}
PedidoEntity pedido = pedidos.crear(new Correo(comanda.correo()), cotizadas);
return mapper.aResponse(pedido);
}Пита, предава и доставя. Не смята и не решава: това е на готвача. Никога не отива тук: изчисление, бизнес правило, пряка заявка към базата, нито метод, който само препраща извикването към една-единствена услуга.
Справката за поръчка е водата. Обслужва я една-единствена услуга и сервитьорът отива направо:
@GetMapping("/{id}")
public PedidoResponse buscar(@PathVariable UUID id) {
return mapper.aResponse(service.buscar(id));
}Колко струва една излишна facade? Един файл повече при всяка промяна: четирите на Иван. И в шаблона никой тест не я издава, защото стрелките остават правилни. Решава се с четене: колко координира този метод?
В понеделник Иван изтри пет метода. facade остана с един.
Кои са трите правила?
Всеки със своето; стрелките сочат само навътре; и това, което влиза, това, което се пази, и това, което излиза, са различни неща.
- Всеки със своето. Ако не знаеш къде отива един ред, попитай чия е работата.
- Стрелките сочат само навътре.
api → facade → service → repositoryилиclient. Готвачът никога не вика сервитьора. - Това, което влиза, това, което се пази, и това, което излиза, са различни неща.
request,entityиresponse, макар днес да си приличат.
Третото ни ухапа, докато тествахме шаблона. В macOS всичките 71 теста от онзи момент минаваха. В Linux един падна: току-що създадената поръчка казваше "creado_en":"2026-11-17T21:30:32.024605370Z", а същата поръчка, проверена веднага след това, "2026-11-17T21:30:32.024605Z". Това, което беше излязло, и това, което беше запазено, вече не бяха едно и също: базата беше запазила по-малко десетични знаци. Поправката беше правило на готвача — часът да се отрязва до милисекунда, — с тест. Затова днес са 72.
Как разбирам, че стрелките сочат навътре?
Защото един тест чете компилираните класове и пада, когато някой от тях сочи навън. И защото един скрипт проверява, че този тест може да се провали.
За Java класовете от един и същ проект могат да се импортират помежду си. Ако готвачът импортира сервитьора, компилира се. Правилото го пази CapasTest, написан с ArchUnit, библиотека «for checking the architecture of your Java code», която работи, като «analyzing given Java bytecode» [12]: преглежда компилирания код, а не текста. Разбира Java 25 от версия 1.4.1 [13]; шаблонът ползва 1.5.1.
.whereLayer("api").mayNotBeAccessedByAnyLayer()
.whereLayer("facade").mayOnlyBeAccessedByLayers("api")
.whereLayer("service").mayOnlyBeAccessedByLayers("api", "facade")
.whereLayer("repository").mayOnlyBeAccessedByLayers("service")
.whereLayer("client").mayOnlyBeAccessedByLayers("facade", "service")Но тест, който винаги минава, не доказва нищо. herramientas/probar-frontera.sh работи върху временно копие и пуска CapasTest два пъти:
- Контрола, с проекта такъв, какъвто е. Трябва да тръгне и да мине. Ако не, експериментът е сглобен зле или проектът ти вече има стрелка навън, и скриптът спира в червено.
- Нарушение. В
PedidoServiceсе засажда метод, който получаваPedidoController. Трябва да се компилира, аCapasTestтрябва да падне, на едно-единствено правило и по точната причина.
Това е истинският изход:
1/2 control: el proyecto tal como está; el cocinero (service) no conoce al mesero (api)
✅ compiló y CapasTest pasó: 4 reglas, 0 fallas
2/2 violación: se siembra en PedidoService un método que recibe un PedidoController
✅ compiló sin una queja: para Java, que el cocinero conozca al mesero no es un error
Method <mx.habil.pedidos.service.PedidoService.avisar(mx.habil.pedidos.api.PedidoController)> has parameter of type <mx.habil.pedidos.api.PedidoController>
✅ CapasTest falló en una sola regla, lasFlechasSoloVanHaciaAdentro: las flechas solo van hacia adentro
✅ frontera: se sostieneСчупихме го по седем начина и седемте излязоха червени. Три казват много: с изтритото правило от CapasTest — ❌ PASÓ; с нарушение, което не се компилира, казва, че това «no demuestra la frontera»; с Java 21 вместо 25 спира на контролата.
Кои са пет чести грешки?
Петте идват от едно и също: една роля, която върши работата на друга.
1. Сервитьорът, който готви
Бизнес правило в контролера.
Работи и се забелязва по-късно: за да тестваш правилото, трябва да вдигнеш уеб частта. Тестът на контролера в шаблона ползва @WebMvcTest, който оставя навън останалите компоненти: «Regular @Component and @ConfigurationProperties beans are not scanned» [22]. Този на услугата върви само с Java и нищо повече.
2. Главният готвач, който само подава чинията
Facade, чийто метод само извиква друг.
Това е грешката на Иван. Архитектурният тест не я отбелязва: стрелките са наред. Издава я броенето: колко услуги или клиенти координира всеки метод?
3. Да предадеш архивната карта
Контролерът връща entity.
Компилира се и отговаря повече от нужното. Измерено в шаблона, като се промени един-единствен метод: от 72 теста падат 3. Един го казва направо:
Expected no value at JSON path "$.correo" but found: 'ana@tienda.mx'Имейлът на клиента излезе в отговор, който никога не е трябвало да го носи. Един от трите е CapasTest: той пита дали някой клас от api зависи от entity, а не какъв тип връща един метод. Затова става червен и ако архивната карта е скрита в List<PedidoEntity> или в ResponseEntity<PedidoEntity>; измерено и с двете.
4. Да викаш доставчика без лимит за време
Ако доставчикът увисне, твоето API увисва с него.
В шаблона лимитът за време е един ред в application.yml [8]. Измерено: без този ред тестът, който очаква 504, става червен. И внимавай какво се опитва повторно: едно «не съществува» от доставчика е отговор. Шаблонът повтаря само при мрежова грешка и може да го прави, защото справката е GET: да питаш два пъти колко чаши има не променя нищо. Едно записване, като плащане, не се опитва повторно така: първо трябва да стане идемпотентно — повторението му да дава същото, като еднократното изпълнение.
5. Да копираш import-ите от стар урок
Spring Boot 4 ползва Jackson 3 по подразбиране, а класовете му смениха пакета си.
Jackson е библиотеката, която превръща обекти в JSON. В Spring Boot 4 версия 3 е «the preferred and default library» [10]; версия 2 остава временно, за миграция, и шаблонът не я ползва. И ръководството за миграция предупреждава: пакетите минават от com.fasterxml.jackson към tools.jackson, с едно изключение — анотациите, които остават в com.fasterxml.jackson.annotation [11]. Измерено в шаблона, с import от старите:
package com.fasterxml.jackson.databind does not exist| Грешка | Какво я издава | Източник |
|---|---|---|
| 1. Сервитьорът, който готви | if върху данни от поръчката в api | [2][22] |
| 2. Facade, която само подава чинията | Метод, който само извиква друг | правило на шаблона |
| 3. Да предадеш архивната карта | Поле в повече в JSON-а | измерване |
| 4. Без лимит за време | Бавен отговор, който все пак пристига | [8][9] |
5. import от стар урок | package … does not exist | [10][11] |
Упражнение: можеш ли да накараш готвача да извика сервитьора?
Ще засадиш стрелка навън, ще видиш, че Java я приема, и ще видиш как тестът и скриптът те предупреждават.
Трябват ти Java 25 (java -version), Git, bash и curl; около 25 минути. Maven — не: проектът го носи.
- В Linux и в macOS инсталирай Java със SDKMAN [23]. В Linux преди това трябват
curl,zipиunzip(измерено в Ubuntu 24.04, основата на Linux Mint 22 [28]):
sudo apt install curl zip unzip
curl -s "https://get.sdkman.io" | bashОтвори друг терминал, влез в папката на шаблона (тази от стъпка 1) и пусни sdk env install. Отвори още един терминал (в този, в който инсталира, java още не се намира; измерено) и в тази папка пусни sdk env. Урок 1 от курса по Java го обяснява стъпка по стъпка. - В Windows ползвай WSL.
Стъпка 1. Клонирай и провери, че всичко е зелено.
git clone https://github.com/HabilMX/estructura-java-spring-boot
cd estructura-java-spring-boot
./mvnw verify
bash herramientas/probar-frontera.shПървия път отнема време: изтегля Maven и библиотеките. Трябва да видиш Tests run: 72, Failures: 0, Errors: 0, Skipped: 0, после BUILD SUCCESS и, в края на скрипта, ✅ frontera: se sostiene.
Ползвай този клонинг само за упражнение. Така всяка промяна, която видиш в него, е от упражнението.
Стъпка 2. Предскажи, преди да пипаш. Ще добавиш към готвача, PedidoService, метод, който получава сервитьора, PedidoController. Запиши си: компилира ли се? Какво казва CapasTest? А скриптът за границата?
Стъпка 3. Засади стрелката. Първият ред маха последната фигурна скоба на класа и оставя копие .bak; вторият добавя метода и затваря класа. Работят еднакво в Linux и в macOS.
sed -i.bak '$d' src/main/java/mx/habil/pedidos/service/PedidoService.java
printf ' public void avisar(mx.habil.pedidos.api.PedidoController mesero) {\n }\n}\n' \
>> src/main/java/mx/habil/pedidos/service/PedidoService.java
./mvnw -q test-compile
./mvnw -q test -Dtest=CapasTesttest-compile завършва, без да каже нищо: компилира се. Тестът — не. Сред многото редове, важните са:
Tests run: 4, Failures: 1, Errors: 0, Skipped: 0
Method <mx.habil.pedidos.service.PedidoService.avisar(mx.habil.pedidos.api.PedidoController)> has parameter of type <mx.habil.pedidos.api.PedidoController> in (PedidoService.java:0)Стъпка 4. Попитай скрипта.
bash herramientas/probar-frontera.shСтава червен, без да стигне до втората стъпка:
❌ el control NO pasó: tu proyecto, tal como está, ya rompe una regla de CapasTest:Това е контролата в действие: не може да докаже, че тестът може да се провали, ако проектът ти вече го проваля.
Стъпка 5. Върни само това, което пипна. Упражнението промени един файл. Преди да го върнеш, виж какво се е променило в него:
git diff -- src/main/java/mx/habil/pedidos/service/PedidoService.javaТрябва да видиш два нови реда: метода avisar и неговата скоба. Ако видиш нещо друго, то е твое: запази го, преди да продължиш. Ако има само това от упражнението, върни този файл. git restore пипа само пътищата, които му дадеш [24]:
git restore src/main/java/mx/habil/pedidos/service/PedidoService.java
bash herramientas/probar-frontera.sh
git status --shortГраницата пак става зелена, а git status показва какво остава: копието, което направи sed.
?? src/main/java/mx/habil/pedidos/service/PedidoService.java.bakПази го, докато не си сигурен, че не ти трябва. После го изтрий с rm -i, който пита преди това. Не ползвай команда, която чисти цялата папка: ще отнесе и бележките ти.
Как разбираш, че си го направил правилно: пусна шест пъти и видя три изхода. Зелено, четири пъти: двете от стъпка 1, test-compile в стъпка 3 и границата в стъпка 5. Червено от теста, веднъж: Failures: 1 в стъпка 3. И червеното на скрипта, «el control NO pasó», в стъпка 4. Ако в стъпка 3 test-compile покаже грешка, провери дали PedidoService.java завършва с една-единствена скоба }.
За да стигнеш по-далеч (по желание): накарай сервитьора да предаде архивната карта. В PedidoController промени метода buscar, така че да връща mx.habil.pedidos.model.entity.PedidoEntity и да връща service.buscar(id), без да минава през mapper-а. Преди това предскажи: компилира ли се? Колко теста падат? Отговор: компилира се, а ./mvnw -q test завършва с Tests run: 72, Failures: 3 (измерено). Върни го както в стъпка 5: git diff на този файл и git restore с пътя му.
Ключови изводи
Три въпроса, които да зададеш на хранилището си тази седмица.
- Колко метода от твоята
facadeсамо извикват друг? Всеки е един файл повече при следващата промяна. - Някой контролер връща ли
entity? Ако да, кое поле от таблицата излиза, без никой да го е поискал? - Какво те предупреждава, ако утре една услуга импортира контролер? Ако отговорът е «прегледът на кода», зависи от това някой да го види.
Какво следва?
Ресторантът не зависи от марката на печката.
Две седмици по-късно на Иван дадоха друго API за поръчки. Отвори проекта и позна папките: api, facade, service, repository. Потърси @RestController, за да започне от сервитьора.
Нямаше нито един.
Нямаше го и класа, който стартира приложението. Нито един import от Spring. И въпреки това слоевете бяха същите и стрелките сочеха навътре. В неделя, 6 декември, в част 6: същият ресторант, друга, по-бърза кухня. Същите слоеве в Quarkus, какво се променя във всеки пакет и колко е бърза, измерено.
Шаблонът и курсът
- Шаблон: github.com/HabilMX/estructura-java-spring-boot. Ползва се като шаблон в GitHub или се клонира [26]. README-то обяснява всеки пакет с неговото «никога», пътя на една поръчка, какво не включва (удостоверяване, истинска база, договор OpenAPI), кога да се добави всяко нещо и как да се махне примерът. Кодът е под MIT; текстът и обясненията — под CC BY-SA 4.0.
- За да го видиш в действие: README-то дава командите
curl. Примерният доставчик на наличности е папка с два JSON файла, сервирана сjwebserver, минимален сървър, който JDK вече носи [25]. Базата е H2, в паметта [7]: най-простото, което тръгва от първия път; данните се изтриват при спиране. Здравето отговаря на/actuator/health, а от Actuator не се публикува нищо друго [21]. - Версии: Java 25, актуалната версия с дългосрочна поддръжка (LTS) [20], с Temurin 25.0.5+8. Spring Boot 4.1.2, актуалната към 17 ноември [19], която приема от Java 17 до Java 27 [18]; шаблонът остава на 25 и не позволява изграждане с друга. Maven 3.9.16, чрез Wrapper-а [15]. ArchUnit 1.5.1 [13]. Тествано в macOS arm64 (и със системния
/bin/bash) и в Linux arm64 (контейнерubuntu:24.04). Linux x86-64 още не е тестван. CI е написан за Ubuntu и macOS с Temurin 25, при всяка промяна и всеки понеделник; ако публичното хранилище остане 60 дни без активност, GitHub изключва понеделнишкото изпълнение [27]. - Курсът по Java на Hábil: ако
record, Maven или тестовете с JUnit са нови за теб, започни оттам: Курс по Java · Урок 3, Records, enums и запечатани типове · Урок 6, Проект с Maven.
Пиша от това, което виждаме всеки ден в Hábil, където изграждаме системи за банки, застраховане и компании в Мексико. Ако в работата или в университета ти и колегите ти попаднете на хранилище, за което никой не знае откъде да го хване, да поговорим: habil.mx
Какво прави Hábil?
Учим на програмиране със същото, с което изграждаме: тестван, обяснен и отворен код.
Тази поредица идва от същото място като нашите курсове. Курсът по Java учи днешния Java: типове, които изразяват модела, тестове, конкурентност и завършена програма, пакетирана в JAR, и го публикуваме отворено, с лиценз Creative Commons; урок 3 обяснява record, а урок 6 — проекта с Maven, който използва шаблонът от тази статия. А в каталога има още курсове по програмиране, безплатни и с тестван и обяснен стъпка по стъпка код.
Разгледай Курса по Java и каталога Курсове по програмиране.
Ако екипът ти наследи система, за която никой не знае откъде да я хване, или трябва да изгради такава, която да може да се поддържа и занапред, правим и това: разгледай Изграждане на система по поръчка. Поискай първи разговор, без заплащане. В него преглеждаме дали си струва да се настрои това, което екипът ти вече има, да се ползва продукт или да се изгради, и какво би получил екипът във всеки случай. Пиши ни в WhatsApp.
Източниците са проверени на 17 ноември 2026 г. Цитатите на английски са възпроизведени дословно.
Източници
- Spring Boot 4.1.2, «Structuring Your Code». https://docs.spring.io/spring-boot/reference/using/structuring-your-code.html
- Spring Framework, «Classpath Scanning and Managed Components»:
@Componentи стереотипните анотации. https://docs.spring.io/spring-framework/reference/core/beans/classpath-scanning.html - Spring Framework, «Error Responses». https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-ann-rest-exceptions.html
- M. Nottingham, E. Wilde и S. Dalal, «RFC 9457: Problem Details for HTTP APIs», IETF, юли 2023 г.. https://www.rfc-editor.org/rfc/rfc9457.html
- Spring Framework, «Validation» (Spring MVC, методи на контролер). https://docs.spring.io/spring-framework/reference/web/webmvc/mvc-controller/ann-validation.html
- Eclipse Foundation, «Jakarta Validation 3.1». https://jakarta.ee/specifications/bean-validation/3.1/
- Spring Boot 4.1.2, «SQL Databases»: «Embedded Database Support» и хранилищата (repositories) на Spring Data. https://docs.spring.io/spring-boot/reference/data/sql.html
- Spring Boot 4.1.2, «REST Clients»:
spring.http.clients.connect-timeoutиread-timeout. https://docs.spring.io/spring-boot/reference/io/rest-client.html - Spring Framework, «Resilience Features». https://docs.spring.io/spring-framework/reference/core/resilience.html
- Spring Boot 4.1.2, «JSON» («Jackson 3 is the preferred and default library»). https://docs.spring.io/spring-boot/reference/features/json.html
- Spring Boot, «Spring Boot 4.0 Migration Guide»: «Upgrading Jackson». https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Migration-Guide
- ArchUnit, «ArchUnit User Guide»: «Introduction» и «Layer Checks». https://www.archunit.org/userguide/html/000_Index.html
- TNG, «ArchUnit», версии 1.4.1 («Support Java 25») и 1.5.1, GitHub. https://github.com/TNG/ArchUnit/releases
- Apache Maven, «Introduction to the Standard Directory Layout». https://maven.apache.org/guides/introduction/introduction-to-the-standard-directory-layout.html
- Apache Maven, «Maven Wrapper». https://maven.apache.org/tools/wrapper/
- Oracle, «Record Classes», Java Language Updates, Java SE 25. https://docs.oracle.com/en/java/javase/25/language/records.html
- Eclipse Foundation, «Jakarta Persistence 3.2», раздел «The Entity Class». https://jakarta.ee/specifications/persistence/3.2/jakarta-persistence-spec-3.2
- Spring Boot 4.1.2, «System Requirements». https://docs.spring.io/spring-boot/system-requirements.html
- Spring, версии на Spring Boot (API на spring.io): 4.1.2, актуалната. https://api.spring.io/projects/spring-boot/releases
- Eclipse Adoptium, «Support» («Java 25 (LTS)»). https://adoptium.net/support/
- Spring Boot 4.1.2, «Endpoints» (Actuator). https://docs.spring.io/spring-boot/reference/actuator/endpoints.html
- Spring Boot 4.1.2, «Testing Spring Boot Applications»:
@WebMvcTest. https://docs.spring.io/spring-boot/reference/testing/spring-boot-applications.html - SDKMAN, «Usage»:
sdk env. https://sdkman.io/usage/ - Git, «git-restore» («Restore specified paths in the working tree»). https://git-scm.com/docs/git-restore
- Oracle, «The jwebserver Command», Java SE 25. https://docs.oracle.com/en/java/javase/25/docs/specs/man/jwebserver.html
- GitHub Docs, «Creating a template repository». https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository
- GitHub Docs, «Disabling and enabling a workflow». https://docs.github.com/en/actions/how-tos/manage-workflow-runs/disable-and-enable-workflows
- Linux Mint, «Linux Mint 22 Release Notes» («Linux Mint 22.x is based on Ubuntu 24.04»), linuxmint.com. https://www.linuxmint.com/rel_wilma.php
Вашата дейност среща ли тези предизвикателства?
Предпочитате имейл? Пишете ни на hola@habil.mx