Stubs Reference

Stub files are template files used by Spring-Hex CLI to generate code. This reference documents all available stubs, their purpose, and the placeholders they support.

Table of Contents

  1. Stubs Reference
    1. Overview
      1. Customizing Stubs
    2. Domain Stubs
      1. Model and Entity Stubs
        1. model.stub
        2. entity.stub
        3. aggregate.stub
        4. aggregate-root.stub
      2. CQRS Stubs
        1. command.stub
        2. command-handler.stub
        3. command-handler-interface.stub
        4. query.stub
        5. query-handler.stub
        6. query-handler-interface.stub
      3. Event Stubs
        1. domain-event.stub
      4. Value Object Stubs
        1. value-object.stub
        2. value-object-id.stub
      5. Port Stubs
        1. input-port.stub
        2. output-port.stub
        3. use-case-port.stub
        4. repository-port.stub
      6. DTO Stubs
        1. request.stub
        2. response.stub
    3. Infrastructure Stubs
      1. Controller Stubs
        1. controller.stub
      2. Persistence Stubs
        1. jpa-entity.stub
        2. jpa-repository.stub
        3. mongo-document.stub
        4. spring-data-mongo-repository.stub
        5. redis-hash-entity.stub
        6. redis-repository.stub
      3. Adapter Stubs
        1. adapter.stub
        2. repository-adapter.stub
        3. mongo-repository-adapter.stub
        4. redis-repository-adapter.stub
        5. event-listener.stub
      4. Mapper Stubs
        1. mapper.stub
      5. Configuration Stubs
        1. domain-config.stub
        2. bean-method-handler.stub
        3. bean-method-handler-events.stub
        4. bean-method-service.stub
    4. Mediator Stubs
      1. CommandBus.stub
      2. SimpleCommandBus.stub
      3. QueryBus.stub
      4. SimpleQueryBus.stub
      5. MediatorConfig.stub
    5. MVC Stubs
    6. Migration Stubs
      1. Flyway Stubs
        1. flyway-sql.stub
        2. flyway-revert-sql.stub
      2. Liquibase Stubs
        1. liquibase-changeset-sql.stub
        2. liquibase-changeset-xml.stub
        3. liquibase-changeset-yaml.stub
        4. liquibase-master-xml.stub
        5. liquibase-master-yaml.stub
    7. Data Seeding Stubs
      1. factory.stub
      2. seeder.stub
      3. seeder-interface.stub
      4. seed-runner.stub
    8. Test Stubs
      1. unit-test.stub
      2. feature-test.stub
    9. Placeholder Reference
    10. Customization Guide
      1. Creating Custom Stubs
      2. Best Practices
      3. Testing Custom Stubs

Overview

Stubs are text files containing boilerplate code with placeholder variables. When you run a generation command, the CLI:

  1. Loads the appropriate stub file
  2. Replaces placeholders with actual values
  3. Writes the result to your project

Customizing Stubs

You can customize any stub by creating a .hex/stubs/ directory in your project and copying the stub files you want to modify. Spring-Hex CLI will use your custom stubs instead of the defaults.

mkdir -p .hex/stubs/domain
# Copy and modify the command.stub file
cp /path/to/default/stubs/command.stub .hex/stubs/domain/command.stub

Domain Stubs

Stubs for core domain layer components in hexagonal architecture.

Model and Entity Stubs

model.stub

Domain

Generates a domain model class representing business entities.

Used by: make:model, make:aggregate

Key Placeholders:

  • `` - Root application package
  • `` - Target package for the model
  • `` - Lowercase aggregate name
  • `` - Capitalized aggregate name
  • `` - Model class name

Example Output:

package com.app.domain.order.model;

public class Order {
    private OrderId id;

    public Order() {
    }

    public OrderId getId() {
        return id;
    }

    public void setId(OrderId id) {
        this.id = id;
    }
}

entity.stub

Domain

Generates a domain entity (similar to model but with entity-specific characteristics).

Used by: make:entity (for domain entities, not JPA entities)

Key Placeholders:

  • `` - Entity class name
  • `` - Target package
  • `` - Aggregate name

aggregate.stub

Domain

Generates a domain aggregate class.

Used by: make:aggregate

Key Placeholders:

  • `` - Aggregate class name
  • `` - Target package

Example Output:

package com.app.domain.order;

import com.app.domain.order.model.OrderId;

public class Order {
    private final OrderId id;

    public Order(OrderId id) {
        this.id = id;
    }

    public OrderId getId() {
        return id;
    }
}

aggregate-root.stub

Domain

Generates an aggregate root with enhanced capabilities (event sourcing, domain event support).

Used by: make:aggregate (advanced mode)

Key Placeholders:

  • `` - Aggregate root class name
  • `` - Domain root package

CQRS Stubs

command.stub

CQRS

Generates a CQRS command class.

Used by: make:command

Key Placeholders:

  • `` - Command class name (e.g., CreateOrderCommand)
  • `` - Command package
  • `` - Aggregate name

Example Output:

package com.app.domain.order.command;

public class CreateOrderCommand {
    // Command properties
}

command-handler.stub

CQRS

Generates a command handler implementation.

Used by: make:command

Key Placeholders:

  • `` - Command class name
  • `` - Handler package
  • `` - Aggregate name
  • `` - CQRS package for imports

Example Output:

package com.app.domain.order.command;

public class CreateOrderCommandHandler implements CreateOrderCommandHandlerInterface {

    @Override
    public void handle(CreateOrderCommand command) {
        // Implementation
    }
}

command-handler-interface.stub

CQRS

Generates a command handler interface.

Used by: make:command

Key Placeholders:

  • `` - Command class name
  • `` - Handler package

query.stub

CQRS

Generates a CQRS query class.

Used by: make:query

Key Placeholders:

  • `` - Query class name (e.g., GetOrderByIdQuery)
  • `` - Query package
  • `` - Aggregate name

query-handler.stub

CQRS

Generates a query handler implementation.

Used by: make:query

Key Placeholders:

  • `` - Query class name
  • `` - Query return type
  • `` - Handler package
  • `` - Aggregate name

Example Output:

package com.app.domain.order.query;

public class GetOrderByIdQueryHandler implements GetOrderByIdQueryHandlerInterface {

    @Override
    public OrderDTO handle(GetOrderByIdQuery query) {
        // Implementation
        return null;
    }
}

query-handler-interface.stub

CQRS

Generates a query handler interface.

Used by: make:query

Key Placeholders:

  • `` - Query class name
  • `` - Query return type
  • `` - Handler package

Event Stubs

domain-event.stub

Events

Generates a domain event class.

Used by: make:event

Key Placeholders:

  • `` - Event class name (e.g., OrderCreatedEvent)
  • `` - Event package
  • `` - Aggregate name

Example Output:

package com.app.domain.order.event;

import java.time.Instant;

public class OrderCreatedEvent {
    private final Instant occurredOn;

    public OrderCreatedEvent() {
        this.occurredOn = Instant.now();
    }

    public Instant getOccurredOn() {
        return occurredOn;
    }
}

Value Object Stubs

value-object.stub

Domain

Generates a value object class.

Used by: make:value-object

Key Placeholders:

  • `` - Value object class name
  • `` - Target package
  • `` - Aggregate name

Example Output:

package com.app.domain.order.model;

import java.util.Objects;

public class Money {
    private final double amount;
    private final String currency;

    public Money(double amount, String currency) {
        this.amount = amount;
        this.currency = currency;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) return true;
        if (o == null || getClass() != o.getClass()) return false;
        Money money = (Money) o;
        return Double.compare(money.amount, amount) == 0 &&
               Objects.equals(currency, money.currency);
    }

    @Override
    public int hashCode() {
        return Objects.hash(amount, currency);
    }
}

value-object-id.stub

Domain

Generates an ID value object (typically for aggregate IDs).

Used by: make:aggregate

Key Placeholders:

  • `` - Aggregate name for ID class (e.g., OrderId)
  • `` - Target package

Port Stubs

input-port.stub

Ports

Generates an input port interface (application service interface).

Used by: make:port --in

Key Placeholders:

  • `` - Port interface name
  • `` - Input port package
  • `` - Aggregate name

Example Output:

package com.app.domain.order.port.in;

public interface CreateOrderUseCase {
    void execute(CreateOrderCommand command);
}

output-port.stub

Ports

Generates an output port interface (typically for repositories or external services).

Used by: make:port (default)

Key Placeholders:

  • `` - Port interface name
  • `` - Output port package
  • `` - Aggregate name

Example Output:

package com.app.domain.order.port.out;

import com.app.domain.order.model.Order;
import java.util.Optional;

public interface OrderRepository {
    Optional<Order> findById(OrderId id);
    void save(Order order);
}

use-case-port.stub

Ports

Generates a use case port interface.

Used by: Advanced port generation scenarios

Key Placeholders:

  • `` - Use case interface name
  • `` - Input port package

repository-port.stub

Ports

Generates a repository port interface with standard CRUD operations.

Used by: make:repository

Key Placeholders:

  • `` - Repository interface name
  • `` - Entity type
  • `` - Output port package

DTO Stubs

request.stub

DTOs

Generates a request DTO for API endpoints.

Used by: make:request

Key Placeholders:

  • `` - Request class name (e.g., CreateOrderRequest)
  • `` - DTO package
  • `` - Aggregate name

Example Output:

package com.app.infrastructure.order.controller.dto;

import javax.validation.constraints.NotNull;

public class CreateOrderRequest {

    @NotNull
    private String customerId;

    public String getCustomerId() {
        return customerId;
    }

    public void setCustomerId(String customerId) {
        this.customerId = customerId;
    }
}

response.stub

DTOs

Generates a response DTO for API endpoints.

Used by: make:response

Key Placeholders:

  • `` - Response class name (e.g., OrderDetailsResponse)
  • `` - DTO package
  • `` - Aggregate name

Infrastructure Stubs

Stubs for infrastructure layer components.

Controller Stubs

controller.stub

Infrastructure

Generates a REST controller.

Used by: make:controller, make:crud

Key Placeholders:

  • `` - Controller class prefix (e.g., OrderController)
  • `` - Controller package
  • `` - Aggregate name (for URL mapping)
  • `` - Model package for imports

Example Output:

package com.app.infrastructure.order.controller;

import org.springframework.web.bind.annotation.*;

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    @GetMapping("/{id}")
    public ResponseEntity<?> getById(@PathVariable String id) {
        return ResponseEntity.ok().build();
    }

    @PostMapping
    public ResponseEntity<?> create(@RequestBody @Valid CreateOrderRequest request) {
        return ResponseEntity.ok().build();
    }
}

Persistence Stubs

jpa-entity.stub

JPA

Generates a JPA entity class.

Used by: make:entity, make:crud

Key Placeholders:

  • `` - Entity class name
  • `` - Database table name
  • `` - Entity package

Example Output:

package com.app.infrastructure.order.persistence;

import javax.persistence.*;

@Entity
@Table(name = "orders")
public class OrderEntity {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;

    public Long getId() {
        return id;
    }

    public void setId(Long id) {
        this.id = id;
    }
}

jpa-repository.stub

JPA

Generates a Spring Data JPA repository interface.

Used by: make:repository (with JPA), make:crud

Aliases: spring-data-repository.stub

Key Placeholders:

  • `` - Entity class name
  • `` - Repository package

Example Output:

package com.app.infrastructure.order.persistence;

import org.springframework.data.jpa.repository.JpaRepository;

public interface OrderJpaRepository extends JpaRepository<OrderEntity, Long> {
}

mongo-document.stub

MongoDB

Generates a MongoDB document entity.

Used by: make:entity (with MongoDB store)

Key Placeholders:

  • `` - Document class name
  • `` - Collection name
  • `` - Document package

Example Output:

package com.app.infrastructure.order.persistence;

import org.springframework.data.mongodb.core.mapping.Document;
import org.springframework.data.annotation.Id;

@Document(collection = "orders")
public class OrderDocument {

    @Id
    private String id;

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }
}

spring-data-mongo-repository.stub

MongoDB

Generates a Spring Data MongoDB repository interface.

Used by: make:repository -s mongodb

Key Placeholders:

  • `` - Document class name
  • `` - Repository package

redis-hash-entity.stub

Redis

Generates a Redis hash entity.

Used by: make:entity (with Redis store)

Key Placeholders:

  • `` - Hash class name
  • `` - Redis key prefix
  • `` - Entity package

Example Output:

package com.app.infrastructure.session.persistence;

import org.springframework.data.redis.core.RedisHash;
import org.springframework.data.annotation.Id;

@RedisHash("sessions")
public class SessionHash {

    @Id
    private String id;

    public String getId() {
        return id;
    }

    public void setId(String id) {
        this.id = id;
    }
}

redis-repository.stub

Redis

Generates a Spring Data Redis repository interface.

Used by: make:repository -s redis

Adapter Stubs

adapter.stub

Infrastructure

Generates a generic adapter implementing a port.

Used by: make:adapter

Key Placeholders:

  • `` - Adapter class name
  • `` - Port interface name
  • `` - Adapter package
  • `` - Port package for imports

Example Output:

package com.app.infrastructure.order.adapter;

import com.app.domain.order.port.out.OrderRepository;
import org.springframework.stereotype.Component;

@Component
public class JpaOrderRepositoryAdapter implements OrderRepository {

    @Override
    public Optional<Order> findById(OrderId id) {
        // Implementation
        return Optional.empty();
    }
}

repository-adapter.stub

Infrastructure

Generates a repository adapter with Spring Data integration.

Used by: make:repository

Key Placeholders:

  • `` - Adapter class name
  • `` - Entity/domain model name
  • `` - Repository port interface
  • `` - Adapter package

mongo-repository-adapter.stub

MongoDB

Generates a MongoDB-specific repository adapter.

Used by: make:repository -s mongodb

redis-repository-adapter.stub

Redis

Generates a Redis-specific repository adapter.

Used by: make:repository -s redis

event-listener.stub

Events

Generates a domain event listener.

Used by: make:event

Key Placeholders:

  • `` - Event class name
  • `` - Listener package
  • `` - Event package for imports

Example Output:

package com.app.infrastructure.order.event;

import com.app.domain.order.event.OrderCreatedEvent;
import org.springframework.context.event.EventListener;
import org.springframework.stereotype.Component;

@Component
public class OrderCreatedEventListener {

    @EventListener
    public void handle(OrderCreatedEvent event) {
        // Handle event
    }
}

Mapper Stubs

mapper.stub

Infrastructure

Generates a mapper for converting between domain models and persistence entities.

Used by: make:mapper, make:crud

Key Placeholders:

  • `` - Entity name
  • `` - Mapper package
  • `` - Domain model package
  • `` - Aggregate name

Example Output:

package com.app.infrastructure.order.mapper;

import com.app.domain.order.model.Order;
import org.springframework.stereotype.Component;

@Component
public class OrderMapper {

    public OrderEntity toEntity(Order domain) {
        if (domain == null) return null;

        OrderEntity entity = new OrderEntity();
        // Mapping logic
        return entity;
    }

    public Order toDomain(OrderEntity entity) {
        if (entity == null) return null;

        Order domain = new Order();
        // Mapping logic
        return domain;
    }
}

Configuration Stubs

domain-config.stub

Configuration

Generates a Spring configuration class for domain beans.

Used by: make:module

Key Placeholders:

  • `` - Configuration class name
  • `` - Config package

bean-method-handler.stub

Configuration

Generates a bean method for registering command/query handlers.

Used by: Internal configuration generation

bean-method-handler-events.stub

Configuration

Generates a bean method for event handlers.

Used by: Internal configuration generation

bean-method-service.stub

Configuration

Generates a bean method for services.

Used by: make:crud (service configuration)

Mediator Stubs

Stubs for CQRS mediator infrastructure.

CommandBus.stub

Mediator

Generates the command bus interface.

Used by: make:mediator

Example Output:

package com.app.application.mediator;

public interface CommandBus {
    <C> void dispatch(C command);
}

SimpleCommandBus.stub

Mediator

Generates the simple command bus implementation.

Used by: make:mediator

QueryBus.stub

Mediator

Generates the query bus interface.

Used by: make:mediator

Example Output:

package com.app.application.mediator;

public interface QueryBus {
    <Q, R> R dispatch(Q query);
}

SimpleQueryBus.stub

Mediator

Generates the simple query bus implementation.

Used by: make:mediator

MediatorConfig.stub

Mediator

Generates Spring configuration for mediator beans.

Used by: make:mediator

MVC Stubs

Stubs for traditional MVC/CRUD architecture.

These stubs are simplified versions of their hexagonal counterparts, designed for rapid CRUD development:

  • model.stub - Simple entity model without domain logic
  • entity.stub - JPA entity for CRUD operations
  • repository.stub - Spring Data repository interface
  • mapper.stub - Simple DTO mapper
  • service.stub - Service layer with CRUD operations
  • controller.stub - REST controller with CRUD endpoints

Used by: make:crud

Migration Stubs

Stubs for database migration files.

Flyway Stubs

flyway-sql.stub

Flyway

Generates a Flyway SQL migration file.

Used by: make:migration (default)

Key Placeholders:

  • `` - Migration description
  • `` - Timestamp for version

Example Output:

-- Migration: create_orders_table
-- Created: 2026-02-10 12:30:45

CREATE TABLE orders (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

File naming: V20260210123045__create_orders_table.sql

flyway-revert-sql.stub

Flyway

Generates a Flyway undo migration file (for Teams/Pro).

Used by: make:migration (with undo support)

Example Output:

-- Undo Migration: create_orders_table

DROP TABLE IF EXISTS orders;

File naming: U20260210123045__create_orders_table.sql

Liquibase Stubs

liquibase-changeset-sql.stub

Liquibase

Generates a Liquibase SQL changeset.

Used by: make:migration --liquibase --format sql

Key Placeholders:

  • `` - Unique changeset identifier
  • `` - Migration description

Example Output:

--liquibase formatted sql

--changeset author:create_orders_table-1
CREATE TABLE orders (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

liquibase-changeset-xml.stub

Liquibase

Generates a Liquibase XML changeset.

Used by: make:migration --liquibase --format xml

Example Output:

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
    http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.0.xsd">

    <changeSet id="create_orders_table-1" author="spring-hex">
        <createTable tableName="orders">
            <column name="id" type="BIGINT" autoIncrement="true">
                <constraints primaryKey="true"/>
            </column>
            <column name="created_at" type="TIMESTAMP" defaultValueComputed="CURRENT_TIMESTAMP"/>
        </createTable>
    </changeSet>
</databaseChangeLog>

liquibase-changeset-yaml.stub

Liquibase

Generates a Liquibase YAML changeset.

Used by: make:migration --liquibase --format yaml

Example Output:

databaseChangeLog:
  - changeSet:
      id: create_orders_table-1
      author: spring-hex
      changes:
        - createTable:
            tableName: orders
            columns:
              - column:
                  name: id
                  type: BIGINT
                  autoIncrement: true
                  constraints:
                    primaryKey: true
              - column:
                  name: created_at
                  type: TIMESTAMP
                  defaultValueComputed: CURRENT_TIMESTAMP

liquibase-master-xml.stub

Liquibase

Generates a master XML changelog file.

Used by: make:migration --liquibase (initial setup)

Example Output:

<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
    http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-4.0.xsd">

    <include file="db/changelog/changelog-20260210-create-orders.xml"/>
</databaseChangeLog>

liquibase-master-yaml.stub

Liquibase

Generates a master YAML changelog file.

Used by: make:migration --liquibase --format yaml (initial setup)

Data Seeding Stubs

Stubs for data factories, seeders, and seeding infrastructure.

factory.stub

Data

Generates a factory @Component with make() (in-memory) and create() (persisted) methods using Datafaker.

Used by: make:factory

Key Placeholders:

  • `` - Entity class name (e.g., UserEntity)
  • `` - Resolved persistence package for entity and repository imports

Example Output:

package com.app.infrastructure.factory.user;

import com.app.infrastructure.persistence.user.UserEntity;
import com.app.infrastructure.persistence.user.UserEntityRepository;
import net.datafaker.Faker;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Component;

import java.util.ArrayList;
import java.util.List;

@Component
@RequiredArgsConstructor
public class UserEntityFactory {

    private final UserEntityRepository repository;
    private static final Faker faker = new Faker();

    public UserEntity make() {
        return UserEntity.builder()
                // TODO: Set fields using faker
                .build();
    }

    public List<UserEntity> make(int count) { ... }

    public UserEntity create() {
        return repository.save(make());
    }

    public List<UserEntity> create(int count) {
        return repository.saveAll(make(count));
    }
}

seeder.stub

Data

Generates a database seeder component that implements the Seeder interface.

Used by: make:seeder

Key Placeholders:

  • `` - Seeder class name
  • `` - Entity class name for factory import
  • `` - Resolved factory package

Example Output:

package com.app.infrastructure.seeder;

import com.app.infrastructure.factory.user.UserEntityFactory;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;

@Component
@RequiredArgsConstructor
@Slf4j
public class UserSeeder implements Seeder {

    private final UserEntityFactory factory;

    @Override
    public void seed() {
        log.info("UserSeeder: seeding...");
        // factory.create(50) saves to database
        log.info("UserSeeder: done");
    }
}

seeder-interface.stub

Data

Generates the Seeder interface that all seeders implement. Auto-generated once on the first make:seeder call.

Used by: make:seeder (auto-generated)

Example Output:

package com.app.infrastructure.seeder;

public interface Seeder {

    void seed();
}

seed-runner.stub

Data

Generates the SeedRunner component that dispatches --seed= arguments to the appropriate seeders. Auto-generated once on the first make:seeder call.

Used by: make:seeder (auto-generated)

Key Features:

  • db:seed --all runs seeders in the order listed in SEEDERS
  • db:seed <SeederName> runs a single seeder by bean name
  • Developers control execution order by arranging the SEEDERS list

Example Output:

package com.app.infrastructure.seeder;

import org.springframework.boot.CommandLineRunner;
import org.springframework.context.ApplicationContext;
import org.springframework.stereotype.Component;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;

import java.util.List;

@Component
@RequiredArgsConstructor
@Slf4j
public class SeedRunner implements CommandLineRunner {

    private final ApplicationContext context;

    // Add your seeders here in the order they should run.
    // Independent entities first, then entities that depend on them.
    private static final List<Class<? extends Seeder>> SEEDERS = List.of(
            // AuthorSeeder.class,
            // BookSeeder.class
    );

    @Override
    public void run(String... args) throws Exception {
        // Dispatches --seed=all or --seed=<SeederName>
    }
}

Test Stubs

Stubs for test class generation.

unit-test.stub

Testing

Generates a JUnit unit test class.

Used by: make:test --unit

Key Placeholders:

  • `` - Test class name
  • `` - Test package

Example Output:

package com.app.domain.order;

import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.BeforeEach;
import static org.junit.jupiter.api.Assertions.*;

class OrderServiceTest {

    private OrderService orderService;

    @BeforeEach
    void setUp() {
        orderService = new OrderService();
    }

    @Test
    void testExample() {
        // Test implementation
    }
}

feature-test.stub

Testing

Generates a Spring Boot integration/feature test.

Used by: make:test (default)

Example Output:

package com.app.infrastructure.order;

import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.test.web.servlet.MockMvc;

import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*;

@SpringBootTest
@AutoConfigureMockMvc
class OrderControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @Test
    void testEndpoint() throws Exception {
        // Test implementation
    }
}

Placeholder Reference

Complete reference of all placeholder variables used in stubs.

Placeholder Description Used In Example Value
`` Root application package All stubs com.mycompany.app
`` Target package for generated file All stubs com.mycompany.app.domain.order.command
`` Lowercase aggregate name Hexagonal stubs order
`` Capitalized aggregate name Hexagonal stubs Order
`` Entity class name Entity/Model stubs OrderEntity
`` Command class name Command stubs CreateOrderCommand
`` Query class name Query stubs GetOrderByIdQuery
`` Event class name Event stubs OrderCreatedEvent
`` Database table name Entity/Migration stubs orders
`` Port interface name Port/Adapter stubs OrderRepository
`` Adapter class name Adapter stubs JpaOrderRepositoryAdapter
`` Value object name Value object stubs Money
`` Request DTO name Request stubs CreateOrderRequest
`` Response DTO name Response stubs OrderDetailsResponse
`` Query handler return type Query handler stubs OrderDTO
`` Resolved model package All hexagonal stubs com.app.domain.order.model
`` Resolved input port package Port/Use case stubs com.app.domain.order.port.in
`` Resolved output port package Port/Adapter stubs com.app.domain.order.port.out
`` Resolved CQRS package Command/Query stubs com.app.domain.order.command
`` Resolved mediator package Mediator stubs com.app.application.mediator
`` Resolved event package Event stubs com.app.domain.order.event
`` Resolved domain root package Aggregate stubs com.app.domain.order
`` Test package Test stubs com.app.domain.order
`` Test class name Test stubs OrderServiceTest
`` Seeder class name Seeder stubs UserSeeder
`` Resolved factory package Seeder stubs com.app.infrastructure.factory.user
`` Resolved repository package Seeder stubs com.app.infrastructure.persistence.user
`` Migration name Migration stubs create_orders_table
`` Liquibase changeset ID Liquibase stubs create_orders_table-1
`` Current timestamp Flyway stubs 20260210123045

Customization Guide

Creating Custom Stubs

  1. Create the stubs directory: 
    mkdir -p .hex/stubs/domain
  2. Copy the default stub you want to customize: 
    # Assuming default stubs are in the tool installation
cp default-stubs/command.stub .hex/stubs/domain/command.stub
  3. Edit the stub with your customizations: ```java package ;

import .common.Command; import lombok.Data;

/**

  • Command:
  • Aggregate: */ @Data public class implements Command { // Your custom template } ```
  1. The CLI will now use your custom stub for all command generation.

Best Practices

  1. Keep placeholders consistent - Use the documented placeholder names
  2. Add comments - Include helpful comments in your stubs
  3. Import common dependencies - Pre-populate common imports (Lombok, validation, etc.)
  4. Follow project conventions - Match your team’s coding style
  5. Version control stubs - Commit .hex/stubs/ to your repository
  6. Document customizations - Note why you customized specific stubs

Testing Custom Stubs

Generate code with the --output flag to test stubs without affecting your main codebase:

spring-hex make:command TestCommand -a test -o /tmp/test-output

Review the generated file to ensure your customizations work as expected.

Back to top

Spring Hex CLI — Hexagonal Architecture scaffolding for Spring Boot

This site uses Just the Docs, a documentation theme for Jekyll.