Към съдържанието
Архитектура и бекенд17 мин

Структурата на един проект (6): кухнята, която се подготвя от предната вечер

От · съосновател и Chief Executive Officer на Hábil ·

Същото API за поръчки, от Spring Boot към Quarkus: какво се променя във всеки пакет, измерено време за стартиране и памет, и какво тази цифра не ви казва.

Структурата на един проект · част 6 от 7 · Quarkus

Сценарий: героите и историята са измислени. Техническите данни и цитатите са с източник в края.

За 1 минута

  • Това е същият ресторант от част 5: api е сервитьорът, service — готвачът, repository — килерът. Това, което се променя, е кухнята: инструментът на всяка роля.
  • Централната идея на Quarkus е да прави «at build-time what traditional frameworks do at runtime» [1]. Кухнята се подготвя от предната вечер и затова отваря бързо.
  • Измерено в шаблона, до първата създадена поръчка: Spring Boot — 2,2 s и 437 MiB; Quarkus в JVM (виртуалната машина, която изпълнява Java) — 1,2 s и 270 MiB; Quarkus, компилиран до native (изпълним файл, на който не му трябва JVM) — 46 ms и 60 MiB.
  • Да отвориш бързо не е да готвиш бързо. В теста за производителност от официалното ръководство native обслужва с ~59 % по-малко заявки в секунда от JVM [2]. Native се избира заради стартирането и паметта, с измерването в ръка.
  • Стрелките продължават да сочат навътре и същият архитектурен тест става червен, ако някой ги обърне. Има една грешка, която нито един тест на шаблона не вижда: откриваш я с grep.
  • За понеделник: потърси extends PanacheEntity в своя проект. Всеки резултат е архивна карта, която прави и работата на килер.

В тази статия

  1. Какво се случи в понеделник в 9:12?
  2. Какво се променя и какво не?
  3. Какво значи «от предната вечер»?
  4. Какво се променя във всеки пакет?
  5. Колко бързо отваря?
  6. Стрелките още ли сочат навътре?
  7. Кои са пет чести грешки?
  8. Упражнение: можеш ли да скриеш архивната карта в касовата бележка?
  9. Ключови изводи
  10. Какво следва?
  11. Шаблонът и курсът
  12. Какво прави Hábil?
  13. Източници

Какво се случи в понеделник в 9:12?

Иван видя как едно API стартира за 46 милисекунди и поиска да прехвърли всичко на native. Лусия му зададе два въпроса.

Понеделник, 9:05. Трети етаж.

Новото API за поръчки имаше обичайните папки: api, facade, service. Иван потърси сервитьора и намери PedidoResource. Нямаше @RestController, нямаше клас с main, а килерът не беше там, където го очакваше: живееше в model/.

Изгради го и го стартира. Дневникът каза:

pedidos 0.1.0 on JVM (powered by Quarkus 3.40.1.2) started in 1.540s.
Listening on: http://0.0.0.0:8080. Management interface listening on http://0.0.0.0:9000.

Два порта. Записа си въпроса и продължи.

Понеделник, 9:12.

Лусия мина покрай бюрото му с кафе в ръка.

— Сега го пусни така.

Даде му команда, на която ѝ трябваше повече от минута, за да завърши. Остави файл от 78 MiB в target/. Иван го изпълни, изпрати поръчка и поръчката се създаде. От пускането на процеса до първия отговор минаха 46 милисекунди.

— Четирийсет и шест? Това със Spring отнема две секунди. Трябва да прехвърлим всичко на това.

— Колко време отне компилирането?

— Минута и нещо.

— А колко поръчки в секунда обслужва?

Иван не знаеше. Никой не го беше измерил.

— Утре закусваме в закусвалнята отсреща — каза Лусия. — Ела рано.

Вторник, 7:30. Закусвалнята отсреща.

Кухнята още не беше отворила. Готвачката вече беше нарязала лука, направила салсите и сложила боба да се вари. В един часа щеше само да подрежда чинии.

— Кухнята се подготвя от предната вечер — каза Лусия. — Затова отваря бързо. Но да отвориш бързо не е да готвиш бързо.

Какво се променя и какво не?

Ресторантът не се променя: променят се инструментите на всяка роля.

Шаблонът на тази част, estructura-quarkus, е същото API от част 5: приема и показва поръчките на един магазин, пита доставчика на наличности колко бройки има и на каква цена и записва в H2, база в паметта. Коренният пакет е същият, mx.habil.pedidos, и ролите също. Правилата на готвача, точните мерки (Dinero, Correo) и този, който преписва на чисто, минаха почти без промени.

Какво се променя и какво не?
РоляВ Spring Boot (част 5)В Quarkus (тази част)
Сервитьорът, apiPedidoController, ResponseEntityPedidoResource, RestResponse
Килерътrepository/ със Spring Data: интерфейсmodel/repository/ с Panache: клас
Доставчикът, clientRestClient; лимит за време и повторен опит в конфигурациятаREST Client; @Timeout и @Retry в самия интерфейс
Книгата за оплаквания, exception@RestControllerAdviceExceptionMapper и разширението quarkus-http-problem
Здравето:8080/actuator/health:9000/q/health, на друг порт
Обзавеждането на заведениетоapplication.ymlapplication.yaml
Кой стартира всичкоPedidosApplication, със своя mainНикой: Quarkus го генерира
estructura-quarkus/
├── pom.xml · mvnw · .mvn/           bibliotecas, construcción y el Maven del proyecto
├── Dockerfile · docs/ARCHITECTURE.md
├── herramientas/
│   ├── probar-frontera.sh           la frontera que sabe fallar
│   └── medir-arranque.py            el arranque y la memoria
├── src/main/java/mx/habil/pedidos/
│   ├── api/            el mesero
│   ├── facade/         el jefe de cocina
│   ├── service/        el cocinero
│   ├── client/         el proveedor de afuera
│   ├── model/
│   │   ├── request/    la comanda
│   │   ├── response/   el ticket
│   │   ├── entity/     la ficha del archivo
│   │   ├── vo/         las medidas exactas
│   │   └── repository/ la despensa
│   ├── mapper/  config/  exception/  observability/  utils/
├── src/main/resources/application.yaml
└── src/test/java/mx/habil/pedidos/  el mismo árbol

Защо килерът се премести в model/repository/? Заради решение на къщата: стандартът на Hábil за Quarkus поставя хранилището на Panache до архивните карти, които то записва. Стрелките не се променят: само готвачът стига до килера.

Какво значи «от предната вечер»?

Че работата по подготовката на кухнята се върши при изграждането, а не при отварянето.

Когато едно приложение на Java стартира, някой трябва да прочете конфигурацията, да намери класовете, които са компоненти, да реши кой кого получава и да сглоби всичко това в паметта. В традиционна рамка това става всеки път, когато приложението отваря. Quarkus го казва в едно изречение: централната му идея е да прави «at build-time what traditional frameworks do at runtime: configuration parsing, classpath scanning, feature toggle based on classloading, and so on» [1].

В закусвалнята готвачката нарязва лука, преди да отвори. Quarkus преглежда класовете, когато изграждаш, и при стартиране вече знае кой е сервитьорът и кого вика.

Този преглед го прави ArC, неговият начин да свързва компоненти. Той следва спецификацията Jakarta CDI («based on the Jakarta Contexts and Dependency Injection 4.1 specification»), но не изцяло: «It implements the CDI Lite specification, with selected improvements on top, and passes the CDI Lite TCK. It does not implement CDI Full.» [10]. CDI е стандартът на Java за това, което в част 5 правеше контейнерът на Spring: ти обявяваш «сервитьорът има нужда от главен готвач» и някой му дава такъв.

В кода почти не се забелязва. Сервитьорът получава помощниците си през конструктора, както в част 5:

public PedidoResource(PedidoFacade facade, PedidoService service, PedidoMapper mapper) {

Променя се кога се решава това. Затова Quarkus няма нужда от клас с main: генерира го при изграждането. Входната врата е target/quarkus-app/quarkus-run.jar, в папка, а не един-единствен .jar.

И има още нещо, което може да се направи с кухня, подготвена от предната вечер: да се компилира цялата, предварително, до изпълним файл на операционната система. Това е native: програма, която върви без виртуалната машина на Java. Това даде Лусия на Иван.

Какво се променя във всеки пакет?

Сервитьорът, килерът, доставчикът, книгата за оплаквания и здравето ползват други инструменти. Всеки запазва своето «никога».

api, сервитьорът

@Path("/v1/pedidos")
public class PedidoResource {

    @POST
    @RunOnVirtualThread
    public RestResponse<PedidoResponse> crear(@Valid @NotNull CrearPedidoRequest comanda) {
        PedidoResponse creado = facade.crear(comanda);
        return RestResponse.ResponseBuilder.<PedidoResponse>create(RestResponse.Status.CREATED)
                .header(HttpHeaders.LOCATION, "/v1/pedidos/" + creado.id())
                .entity(creado)
                .build();
    }

Quarkus REST е «a new Jakarta REST (formerly known as JAX-RS) implementation» [4]: @Path, @POST и @GET са от този стандарт, а не от Quarkus. В Jakarta REST класът, който обслужва един маршрут, се нарича resource, ресурс. @RunOnVirtualThread иска виртуална нишка за всяка заявка, както в част 5, защото сервитьорът чака доставчика; ръководството поставя границата: «Virtual threads are useful for I/O-bound workloads only» [18].

Една измерена разлика: ако поискаш /v1/pedidos/hola, което не е идентификатор, част 5 отговаряше 400, а тази отговаря 404. Не е пропуск. Спецификацията на Jakarta REST го изисква: ако параметър от маршрута не може да се преобразува, «an implementation MUST generate an instance of NotFoundException (404 status)» [14]. За Jakarta REST този маршрут не съществува.

Никога не отива тук: бизнес правило. Както в част 5.

model/repository, килерът

@ApplicationScoped
public class PedidoRepository implements PanacheRepositoryBase<PedidoEntity, UUID> {
}

Panache е слоят на Quarkus за записване с Hibernate. Предлага два стила. В първия архивната карта се записва сама: entity класът наследява PanacheEntity и носи собствените си заявки, като Person.findByName(…). Това е шаблонът active record, активен запис. Вторият е този на шаблона: «the more classical repository pattern via PanacheRepository» [5]. Архивната карта е обикновен JPA entity клас, а килерът е друг клас. Ползва се PanacheRepositoryBase, защото идентификаторът е UUID; за това ръководството казва «extend PanacheRepositoryBase instead of PanacheRepository and specify your ID type» [5].

Защо килерът е отделно? Заради третото правило от част 5: това, което влиза, това, което се записва, и това, което излиза, са различни неща. Ако архивната карта също записва и търси, тя носи със себе си методи като persist(): всеки, който държи карта в ръка, би могъл да опита да пише в базата, дори сервитьорът, и в рамките на транзакция би успял [5]. С отделен килер само готвачът стига до него, а архитектурният тест следи за това.

Никога не отива тук: решение. И никога: extends PanacheEntity в архивната карта. Това е първата грешка от списъка и най-тихата.

client, външният доставчик

@RegisterRestClient(configKey = "inventario")
@Path("/productos")
public interface InventarioApi {

    @GET
    @Path("/{sku}.json")
    @Timeout(2000)
    @Retry(maxRetries = 2, delay = 200, jitter = 50,
            retryOn = {TimeoutException.class, ProcessingException.class})
    @ExponentialBackoff(factor = 2)
    InventarioClient.Producto producto(@PathParam("sku") String sku);
}

В част 5 клиентът беше клас, който извикваше по HTTP. Тук е интерфейс: ти обявяваш маршрута, а Quarkus пише извикването [6]. Адресът на доставчика е в application.yaml, под ключа inventario.

Двете обичайни предпазни мерки са в самия интерфейс, с анотации от MicroProfile Fault Tolerance. Разширението предлага няколко, като @CircuitBreaker [7]; този интерфейс ползва три: @Timeout, @Retry и @ExponentialBackoff. Две секунди лимит за време на опит и до два повторни опита: общо три опита. Повтаря се само при изтекло време или мрежова грешка. Едно «не съществува» от доставчика е отговор и не се повтаря. Измерено с изключен доставчик: API-то отговаря 503, с "error_code":"PROVEEDOR_NO_DISPONIBLE", за половин секунда (0.534s), след трите опита.

Никога не отива тук: правило за поръчката. Нито извикване без лимит за време.

exception, книгата за оплаквания

@Provider
public class PedidosExceptionMapper extends ExceptionMapperBase<PedidosException>
        implements ExceptionMapper<PedidosException> {

    @Override
    protected HttpProblem toProblem(PedidosException queja) {
        return queja.codigo().aProblema(queja.getMessage());
    }
}

Формата на отговора е като в част 5: Problem Details, RFC 9457 [16]. Дава я разширение от общността, quarkus-http-problem: «Unified error responses for Quarkus REST APIs via Problem Details for HTTP APIs (RFC9457 & RFC7807)» [15]. ExceptionMapper е частта от Jakarta REST, която превръща изключение в отговор [4]. Измерено, като се поискат четири чаши, когато има три:

{"type":"https://pedidos.example/errors/sin_existencias","status":409,
 "title":"No hay existencias suficientes","detail":"De TAZA-01 se pidieron 4 y hay 3",
 "instance":"/v1/pedidos","error_code":"SIN_EXISTENCIAS",
 "request_id":"e8cc3ea5-44a3-47ef-8e39-275e4e584861"}

request_id е същият като в заглавката X-Request-ID и в дневника: с него се намира посещението. Никога не отива тук: собствен формат за грешки.

Здравето, на друг порт

Quarkus публикува здравето на /q/health/live и /q/health/ready [8]. Шаблонът го изпраща, заедно с метриките [20], към интерфейса за управление: с quarkus.management.enabled=true тези маршрути излизат на порт 9000, а не на порта на API-то [9].

curl -s localhost:9000/q/health/ready

Отговаря (излиза на няколко реда; тук е събрано):

{"status":"UP","checks":[{"name":"Database connections health check","status":"UP","data":{"<default>":"UP"}}]}

Измерено: curl -s localhost:8080/q/health отговаря 404. Това, което е вътре, не излиза през вратата за клиентите. Като кухнята на закусвалнята: инспекторът влиза през служебния вход, а не през салона.

config, обзавеждането на заведението

application.yaml с разширението quarkus-config-yaml [11]. На първия си ред носи предупреждение, защото ни се случи: сгрешено написан ключ не спира Quarkus. Ще го видим в грешка 4.

Колко бързо отваря?

Измерено: native създава първата си поръчка за 46 милисекунди и тежи 60 MiB. Изграждането му отне 80 секунди и поиска 4 GiB.

Какво се измери. Времето от пускането на процеса до първия отговор 201 на POST /v1/pedidos. Не е достатъчно портът да се отвори: този отговор налага два пъти да се извика доставчикът на наличности и да се запише в H2. Веднага след като се получи този 201, с ps се отчита паметта, която процесът заема (RSS, resident set size: физическата памет, която държи). По пет поредни пускания на всяко и медианата. Скриптът е herramientas/medir-arranque.py и идва с шаблона, за да го повториш.

Къде. Mac с Apple Silicon (macOS arm64, 10 ядра, 32 GB), на 18 ноември 2026 г. Двете в JVM с Java 25 (Temurin 25.0.5+8), без опции за паметта; Quarkus 3.40.1.2 и Spring Boot 4.1.2, шаблонът от част 5.

Колко бързо отваря?
Същото API, в…Първи отговор (медиана от 5)Памет (RSS)Петте пускания
Spring Boot, JVM2 241 ms437 MiB2181, 2241, 2377, 2301, 2207 ms
Quarkus, JVM1 220 ms270 MiB1515, 1250, 1220, 1145, 1175 ms
Quarkus, native46 ms60 MiB150, 67, 46, 38, 44 ms

Повторихме серията на същия Mac, с Temurin 25.0.4+7: Spring Boot — 2 617 ms и 427 MiB; Quarkus в JVM — 1 378 ms и 266 MiB; native — 47 ms и 60 MiB. Милисекундите на JVM се местят от една серия към друга; редът — не.

Какво струва. Изграждането на native изиска GraalVM, компилаторът, който превръща подготвената кухня в изпълним файл. В SDKMAN се инсталира като кандидата 25.5.5.0+3-graalce [21]. На същия Mac отне 80 секунди (72 от тях — компилиране), стигна до 4,11 GiB памет и остави изпълним файл от 78 MiB, който работи само на системата, където е изграден: този от Mac не върви на Linux. Версията за JVM се изгражда за секунди. Официалното ръководство е съгласно: «native compilation takes minutes, JVM builds take seconds» [2].

Какво тази таблица не ти казва. Ръководството на Quarkus има собствено сравнение, със свое приложение и своя машина: в неговия тест native стига до първата заявка за 581 ms срещу 4 417 за JVM и заема 95 MiB срещу 304. Но обслужва 5 411 заявки в секунда срещу 13 265: «~59% below JVM» [2]. Причината я дава същото ръководство: в JVM компилаторът оптимизира, докато приложението върви, и при услуги, които работят дълго, това бие native [2]. Ние не мерихме заявки в секунда и затова не даваме своя цифра.

Това е въпросът на Лусия. Native отваря бързо и заема малко. Да готвиш бързо, с часове, е друго нещо.

Тогава кое? Шаблонът върви в JVM: изгражда се за секунди, проверява се с обичайните инструменти и стартира за малко повече от секунда, което за API, което живее с дни, не тежи. Native си струва, когато стартирането и паметта наистина тежат: функции, които се раждат с всяка заявка, много малки реплики, мащабиране от нула. В този шаблон кодът е същият: да решиш означава да смениш командата за изграждане, а не слоевете. В друго приложение може да се наложи да обявиш какво се зарежда чрез рефлексия [2][3]. А в Hábil това се решава писмено, с измерването, което го подкрепя.

Стрелките още ли сочат навътре?

Да, и същият тест следи за това. Този път скриптът засява четири грешки вместо една.

За Java това, че готвачът познава сервитьора, все още не е грешка: компилира се. Правилото го пази CapasTest, написан с ArchUnit, който проверява компилираните класове [17]. Слоевете са същите като в част 5:

.whereLayer("api").mayNotBeAccessedByAnyLayer()
.whereLayer("facade").mayOnlyBeAccessedByLayers("api")
.whereLayer("service").mayOnlyBeAccessedByLayers("api", "facade")
.whereLayer("repository").mayOnlyBeAccessedByLayers("service")
.whereLayer("client").mayOnlyBeAccessedByLayers("facade", "service")

И отделно правило: нито един клас от api не може да зависи от entity. Сервитьорът подава касовата бележка, никога архивната карта.

herramientas/probar-frontera.sh работи върху временно копие. Първо пуска контролата: проектът във вида, в който е, трябва да мине. После засява четири грешки, една по една. Всяка трябва да се компилира, а CapasTest трябва да се провали на едно-единствено правило, по точната причина. Това е реалният изход, съкратен:

1/5 control: el proyecto tal como está; el cocinero no conoce al mesero y el mesero no entrega la ficha
   ✅ compiló y CapasTest pasó: 4 reglas, 0 fallas
2/5 violación: se siembra en PedidoService un método que recibe un PedidoResource
   ✅ CapasTest falló en una sola regla, lasFlechasSoloVanHaciaAdentro
3/5 fuga: se siembra en PedidoResource un método que entrega la PedidoEntity tal cual
   ✅ CapasTest falló en una sola regla, elMeseroNoConoceLaFichaDelArchivo
4/5 fuga: la misma PedidoEntity, escondida en una List<PedidoEntity>
   ✅ CapasTest falló en una sola regla, elMeseroNoConoceLaFichaDelArchivo
5/5 fuga: la misma PedidoEntity, escondida en una RestResponse<PedidoEntity>
   ✅ CapasTest falló en una sola regla, elMeseroNoConoceLaFichaDelArchivo
✅ frontera: se sostiene (la violación y las tres fugas salieron en rojo, cada una por su razón)

А ако скриптът лъже? Саботирахме го. С правилото за архивната карта, насочено към друг пакет, той спира на червено при първото изтичане. Без правилото за слоя api спира при нарушението. Скрипт, който не може да се провали, не доказва нищо.

Тестовете са 82, преброени в отчетите в target/surefire-reports/, а не в BUILD SUCCESS. Тези, които вдигат приложението, ползват @QuarkusTest. Тези, които споделят профил, преизползват същата инстанция на Quarkus; тест с друг профил, като този с изключения доставчик, я рестартира [23].

Кои са пет чести грешки?

Три са на роля, която върши работата на друга, както в част 5. Две са нови: да объркаш отварянето с готвенето и да се довериш на това, което не предупреждава.

1. Архивната карта, която е и килер

Entity класът наследява PanacheEntity и се записва сам.

Това е формата, която ръководството на Panache учи първа [5], и тя работи. Измерихме го в клонинг на шаблона: накарахме PedidoEntity да наследява PanacheEntityBase и пуснахме всичко. 82 от 82 в зелено. Нито един тест на шаблона не го вижда, защото стрелките остават наред: архивната карта не импортира никого. Промяната е, че сега картата носи persist() и всеки, който я държи в ръка, в рамките на транзакция, би могъл да пише в базата.

Издава го едно търсене:

grep -rn 'extends PanacheEntity' src/main

Нула резултата — това искаш. Това е задачата за понеделник.

2. Всичко на native, защото отваря бързо

Да измериш стартирането и да правиш изводи за производителността.

Това е грешката на Иван. Native отваря за милисекунди, но в теста от официалното ръководство обслужва с ~59 % по-малко заявки в секунда, а изграждането му отнема минути и иска гигабайти памет [2]. Издава го един въпрос: какво наистина ти струва — отварянето или обслужването?

3. Бинарният файл, който стартира и умира при първата си поръчка

Да тестваш native със здравето, а не с истинска поръчка.

При компилиране до native влиза само това, което компилаторът вижда като използвано. Това, което една библиотека зарежда по име, в момента, може да остане отвън. Ръководството на Quarkus описва най-лошия случай: няма изключение, но «the JSON result would be completely empty» [3]. Здравето може да отговори UP, докато първата поръчка излиза празна. Затова шаблонът не приема native само защото стартира: иска му поръчка, която вика доставчика и записва в базата. Измерихме го така: native отговори 201, 404, 409, 422 и 400 със своя Problem Details и 503 с изключен доставчик.

4. Ключ, който се пренебрегва безшумно

Сгрешената конфигурация не се проваля: просто не прави нищо.

Случи ни се с шаблона. За да скъсим лимита за време в тестовете, написахме ключа с името на интерфейса, InventarioApi/producto. Quarkus не се оплака и лимитът за време остана 2 секунди. Правилният ключ носи името на класа, който Quarkus генерира за интерфейса, InventarioApi$$CDIWrapper/producto. Quarkus все пак предупреждава за ключ, който не разпознава, с «Unrecognized configuration key», но само за тези, които започват с quarkus.; измерено с по един фалшив ключ от всеки вид. Издава го тест, който зависи от този ключ: тестът за лимита за време става червен, ако ключът не се прилага.

5. Да копираш анотациите на Spring

Да търсиш @RestController, @Service и @Autowired в проект на Quarkus.

В Quarkus сервитьорът е resource на Jakarta REST, а компонентите се свързват с CDI [4][10]. Quarkus има разширения, които разбират някои анотации на Spring [19], но шаблонът не ги ползва: ако проектът е на Quarkus, се пише като Quarkus и който го чете после, намира това, което учи официалната документация. Ако един екип реши да ги ползва, нека е писмено, а не защото някой е копирал пример.

5. Да копираш анотациите на Spring
ГрешкаКакво я издаваИзточник
1. Архивната карта, която е и килерgrep -rn 'extends PanacheEntity' src/main[5] · измерване
2. Всичко на native, защото отваря бързоЗаявките в секунда, не само стартирането[2]
3. Native, който умира при първата си поръчкаИстинска поръчка, не здравето[3] · измерване
4. Ключ, който не прави нищоТест, който зависи от този ключизмерване
5. Анотации на Spring в Quarkus@RestController или @Autowired в src/main[4][10][19]

Упражнение: можеш ли да скриеш архивната карта в касовата бележка?

Ще накараш сервитьора да подаде архивната карта вътре в отговор, ще видиш, че Java го приема, и ще видиш как тестът и скриптът те предупреждават.

Трябват ти Java 25 (java -version), Git 2.23 или по-нов (заради git restore), bash и curl; около 25 минути. Maven — не: проектът го носи. Ако още нямаш Java 25, част 5 и README-то на шаблона обясняват как да го инсталираш със SDKMAN; в Windows ползвай WSL. Native не е нужен за упражнението.

Стъпка 1. Клонирай и провери, че всичко е зелено.

git clone https://github.com/HabilMX/estructura-quarkus
cd estructura-quarkus
./mvnw verify
bash herramientas/probar-frontera.sh

Първия път отнема време: изтегля Maven и библиотеките. Трябва да видиш Tests run: 82, Failures: 0, Errors: 0, Skipped: 0, после BUILD SUCCESS и, в края на скрипта, ✅ frontera: se sostiene.

Ползвай този клонинг само за упражнение. Така всяка промяна, която видиш в него, е от упражнението.

Стъпка 2. Предскажи, преди да пипнеш. Ще добавиш към сервитьора, PedidoResource, маршрут, който връща PedidoEntity вътре в RestResponse. Запиши си: компилира ли се? Какво казва CapasTest? А скриптът за границата?

Стъпка 3. Скрий архивната карта. Първият ред маха последната скоба на класа и оставя копие .bak; вторият добавя маршрута и затваря класа. Синтаксисът работи в macOS и в Linux; цялото упражнение е тествано в macOS.

sed -i.bak '$d' src/main/java/mx/habil/pedidos/api/PedidoResource.java
printf '    @GET\n    @Path("/{id}/ficha")\n    public org.jboss.resteasy.reactive.RestResponse<mx.habil.pedidos.model.entity.PedidoEntity> ficha(@PathParam("id") UUID id) {\n        return org.jboss.resteasy.reactive.RestResponse.ok(service.buscar(id));\n    }\n}\n' \
  >> src/main/java/mx/habil/pedidos/api/PedidoResource.java
./mvnw -q test-compile
./mvnw -q test -Dtest=CapasTest

test-compile завършва, без да каже нищо: компилира се. Тестът — не. Сред много редове, тези, които имат значение:

Tests run: 4, Failures: 1, Errors: 0, Skipped: 0
Method <mx.habil.pedidos.api.PedidoResource.ficha(java.util.UUID)> has generic return type <org.jboss.resteasy.reactive.RestResponse<mx.habil.pedidos.model.entity.PedidoEntity>> with type argument depending on <mx.habil.pedidos.model.entity.PedidoEntity> in (PedidoResource.java:0)

ArchUnit не гледа типа, който методът връща, а от какво зависи: архивната карта беше скрита в отговора и въпреки това я намери.

Стъпка 4. Попитай скрипта.

bash herramientas/probar-frontera.sh

Става червен, без да мине контролата:

❌ el control NO pasó: tu proyecto, tal como está, ya rompe una regla de CapasTest:

Това е контролата в действие: не може да докаже, че тестът може да се провали, ако проектът ти вече го проваля.

Стъпка 5. Върни само това, което пипна. Първо виж какво се промени:

git diff --stat -- src/main/java/mx/habil/pedidos/api/PedidoResource.java

Трябва да видиш 1 file changed, 5 insertions(+): новия маршрут. Ако видиш нещо друго, то е твое: запази го, преди да продължиш. Ако е само това от упражнението, върни този файл. git restore пипа само пътищата, които му дадеш [22]:

git restore src/main/java/mx/habil/pedidos/api/PedidoResource.java
bash herramientas/probar-frontera.sh
git status --short

Границата пак става зелена, а git status показва какво остава, копието, което направи sed:

?? src/main/java/mx/habil/pedidos/api/PedidoResource.java.bak

Пази го, докато не си сигурен, че не ти трябва. После го изтрий с rm -i, който пита преди това.

Как разбираш, че си го направил добре: пусна шест пъти и видя три изхода. Зелено, четири пъти: двата от стъпка 1, test-compile в стъпка 3 и границата в стъпка 5. Червено от теста, веднъж: Failures: 1 в стъпка 3. И червеното на скрипта, «el control NO pasó», в стъпка 4. Ако в стъпка 3 test-compile покаже грешка, провери дали PedidoResource.java завършва с една-единствена скоба }.

За да стигнеш по-далеч (по желание): превърни архивната карта в килер. В PedidoEntity накарай класа да наследява PanacheEntityBase (добави import io.quarkus.hibernate.orm.panache.PanacheEntityBase; и смени public class PedidoEntity { с public class PedidoEntity extends PanacheEntityBase {). Преди това предскажи: колко теста се провалят? Измерен отговор: нито един, 82 от 82. Пусни grep -rn 'extends PanacheEntity' src/main: той вече я намира. Върни го както в стъпка 5.

Ключови изводи

Три въпроса, които да зададеш на своето хранилище тази седмица.

  1. Колко архивни карти в проекта ти наследяват PanacheEntity? Всяка е entity клас, който носи собствени методи, за да се записва.
  2. Ако ползваш native, кое измерване го оправда: стартирането, паметта или заявките в секунда? Остана ли записано?
  3. Кой тест става червен, ако един ключ от конфигурацията ти престане да се прилага? Ако отговорът е «никой», този ключ може да не прави нищо от месеци.

Какво следва?

Ресторантът има и салон.

Един петък помолиха Иван да премести един бутон на екрана, където магазинът вижда поръчките си. Проектът беше на React. Той отвори папката src/ и намери осемдесет разхвърляни файла, всички на едно ниво: бутони, екрани, извиквания към API-то, всичко накуп.

Беше се научил да пита чия е всяка работа. Този път не намираше дори ролите. В неделя, 13 декември, в част 7, последната от поредицата: как се подрежда един frontend с React, какво отива във всяка папка и шаблонът, който го проверява.

Шаблонът и курсът

  • Шаблон: github.com/HabilMX/estructura-quarkus. Ползва се като шаблон в GitHub или се клонира. README-то обяснява всеки пакет с неговото «никога», пътя на една поръчка, какво се промени спрямо Spring Boot, как да се измерят стартирането и паметта, какво не включва (удостоверяване, истинска база, договор OpenAPI), кога да се добави всяко нещо и как да се махне примерът. Кодът е под MIT; текстът и обясненията — под CC BY-SA 4.0.
  • За да го видиш в действие: README-то дава командите curl. Примерният доставчик на наличности е папка с два JSON файла, сервирана с jwebserver, който JDK вече носи. Базата е H2, в паметта: най-простото, което тръгва от първия път; данните се изтриват при спиране. Здравето и метриките — на порт 9000.
  • Версии: Java 25 с Temurin 25.0.5+8. Quarkus 3.40.1.2: 3.40 е най-новата му версия с дългосрочна поддръжка [13], а версия с дългосрочна поддръжка се поддържа 12 месеца, като на всеки шест излиза нова [12]. Maven чрез Wrapper-а. GraalVM CE 25.5.5.0+3-graalce, само за native. Тествано в macOS arm64. В Linux — още не: CI е написан за Ubuntu и macOS и ще тръгне, когато публичното хранилище съществува.
  • Курсът по Java на Hábil: ако record, Maven или тестовете с JUnit са нови за теб, започни оттам: Курс по Java. А ако не си чел част 5, прочети я първо: тази приема ролите в ресторанта за известни.

Пиша от това, което виждаме всеки ден в Hábil, където изграждаме системи за банки, застраховане и компании в Мексико. Ако в работата или в университета ти и колегите ти попаднете на хранилище, за което никой не знае откъде да го хване, да поговорим: habil.mx

Какво прави Hábil?

Учим на програмиране със същото, с което изграждаме: тестван, обяснен и отворен код.

Тази поредица идва от същото място като нашите курсове. Курсът по Java учи днешния Java: типове, които изразяват модела, тестове, конкурентност и завършена програма, пакетирана в JAR, и го публикуваме отворено, с лиценз Creative Commons; урок 3 обяснява record, а урок 6 — проекта с Maven, същата основа, която използва шаблонът от тази статия. А в каталога има още курсове по програмиране, безплатни и с тестван и обяснен стъпка по стъпка код.

Разгледай Курса по Java и каталога Курсове по програмиране.

Ако екипът ти наследи система, за която никой не знае откъде да я хване, или трябва да изгради такава, която да може да се поддържа и занапред, правим и това: разгледай Изграждане на система по поръчка. Поискай първи разговор, без заплащане. В него преглеждаме дали си струва да се настрои това, което екипът ти вече има, да се ползва продукт или да се изгради, и какво би получил екипът във всеки случай. Пиши ни в WhatsApp.

Източниците са проверени на 18 ноември 2026 г. Цитатите на английски са възпроизведени дословно.

Източници

  1. Quarkus, «Container First»: «Build Time Processing». https://quarkus.io/container-first/
  2. Quarkus, «Building a Native Executable»: «Comparing JVM, Leyden AOT, and native modes» (тест от 21 април 2026 г., Quarkus 3.34.3, JDK 25.0.2, 4 CPU). https://quarkus.io/guides/building-native-image
  3. Quarkus, «Tips for writing native applications». https://quarkus.io/guides/writing-native-applications-tips
  4. Quarkus, «Writing REST Services with Quarkus REST»: «Exception mapping». https://quarkus.io/guides/rest
  5. Quarkus, «Simplified Hibernate ORM with Panache»: «Solution 1: using the active record pattern» и «Solution 2: using the repository pattern». https://quarkus.io/guides/hibernate-orm-panache
  6. Quarkus, «Using the REST Client». https://quarkus.io/guides/rest-client
  7. Quarkus, «SmallRye Fault Tolerance». https://quarkus.io/guides/smallrye-fault-tolerance
  8. Quarkus, «SmallRye Health». https://quarkus.io/guides/smallrye-health
  9. Quarkus, «Management interface reference». https://quarkus.io/guides/management-interface-reference
  10. Quarkus, «Contexts and Dependency Injection» (справочник за ArC). https://quarkus.io/guides/cdi-reference
  11. Quarkus, «YAML configuration». https://quarkus.io/guides/config-yaml
  12. M. Rydahl Andersen, «Long-Term Support (LTS) for Quarkus», блогът на Quarkus, 6 юли 2023 г. https://quarkus.io/blog/lts-releases/
  13. G. Smet, «Quarkus 3.40 LTS - new LTS version», блогът на Quarkus, 30 септември 2026 г. https://quarkus.io/blog/quarkus-3-40-released/
  14. Eclipse Foundation, «Jakarta RESTful Web Services 3.1», преобразуване на параметри. https://jakarta.ee/specifications/restful-ws/3.1/jakarta-restful-ws-spec-3.1
  15. Quarkiverse, «quarkus-http-problem», GitHub. https://github.com/quarkiverse/quarkus-http-problem
  16. M. Nottingham, E. Wilde и S. Dalal, «RFC 9457: Problem Details for HTTP APIs», IETF, юли 2023 г. https://www.rfc-editor.org/rfc/rfc9457.html
  17. ArchUnit, «ArchUnit User Guide»: «Layer Checks». https://www.archunit.org/userguide/html/000_Index.html
  18. Quarkus, «Virtual thread support reference». https://quarkus.io/guides/virtual-threads
  19. Quarkus, «Quarkus extension for Spring DI API». https://quarkus.io/guides/spring-di
  20. Quarkus, «Micrometer Metrics». https://quarkus.io/guides/telemetry-micrometer
  21. SDKMAN, кандидати за Java за macOS arm64 (25.5.5.0+3-graalce). https://api.sdkman.io/2/candidates/java/darwinarm64/versions/list?installed=
  22. Git, «git-restore». https://git-scm.com/docs/git-restore
  23. Quarkus, «Testing your application». https://quarkus.io/guides/getting-started-testing

Вашата дейност среща ли тези предизвикателства?

Да обсъдим вашия проект

Предпочитате имейл? Пишете ни на hola@habil.mx