Designing Commands, Events & Queries

A command represents wanting something to happen. Its name should read as a request for action — CreateCustomerCommand, UpdateCustomerCommand — and by convention it's typically immutable: a set of final fields, a constructor, and getters, with no setters.

The one field every command needs that a plain data class wouldn't is the aggregate identifier: the field marked @TargetAggregateIdentifier. This tells Axon which specific aggregate instance the command is meant for. Without it, Axon has no way to know whether a CreateCustomerCommand should be routed to a brand-new aggregate instance or an existing one, or which existing one, when a system might have millions of customers.

Critically, a command can be rejected. If business rules don't allow it — say, an empty email address, or an attempt to create a customer that already exists — the command simply fails and nothing in the system changes as a result. That rejection logic doesn't live in the command class itself; the command is just a plain, immutable description of the request. The actual accept-or-reject decision happens where the command is handled, one level deeper in the system.

public class CreateCustomerCommand {

    @TargetAggregateIdentifier // tells Axon which aggregate instance this command is FOR
    private final String customerId;
    private final String name;
    private final String email;

    public CreateCustomerCommand(String customerId, String name, String email) {
        this.customerId = customerId;
        this.name = name;
        this.email = email;
    }

    public String getCustomerId() { return customerId; }
    public String getName() { return name; }
    public String getEmail() { return email; }
    // commands are typically immutable — no setters
}

An event represents something that has already, definitively happened. Its name should read as a completed fact in the past tense — CustomerCreatedEvent, CustomerUpdatedEvent — never as a request or an in-progress action. An event is never rejected: by the time an event object exists, whatever it describes has already occurred. There's no field on an event marked @TargetAggregateIdentifier for this reason; the routing decision already happened back when the corresponding command was accepted.

A query represents a question, and answering it changes nothing. FindCustomerQuery below carries only what's needed to look an answer up — no aggregate identifier field at all, because queries aren't routed to an aggregate. Aggregates only handle commands and their own events; a query gets answered somewhere else entirely, by a component built purely to serve fast reads.

// The event a successful CreateCustomerCommand results in.
public class CustomerCreatedEvent {
    private final String customerId;
    private final String name;
    private final String email;

    public CustomerCreatedEvent(String customerId, String name, String email) {
        this.customerId = customerId;
        this.name = name;
        this.email = email;
    }

    public String getCustomerId() { return customerId; }
    public String getName() { return name; }
    public String getEmail() { return email; }
}

// A query for one customer's details — no @TargetAggregateIdentifier at all.
public class FindCustomerQuery {
    private final String customerId;

    public FindCustomerQuery(String customerId) {
        this.customerId = customerId;
    }

    public String getCustomerId() { return customerId; }
}

The most common early mistake is the tense confusion already flagged: naming events in the present tense instead of the past tense. It seems minor, but it actively misleads anyone reading the codebase later — a class named UpdateCustomer reads as a request, even if it's actually being used as an already-happened fact.

A second, subtler mistake is putting mutable setters on command or event classes "just in case." Both are meant to be immutable value objects; a command describes one specific request, and an event describes one specific fact, and neither should be mutated after construction. Making them mutable opens the door to a handler accidentally changing a command's fields mid-processing, which makes reasoning about what a handler actually saw much harder.

A third mistake is forgetting @TargetAggregateIdentifier on a command's identifying field. Without it, Axon has no reliable way to route the command to the right aggregate instance, and you'll typically see a runtime error rather than the command silently going to the wrong place — which is a safer failure mode, but still one worth avoiding by getting the annotation right the first time.