- Quick Start
- API Reference
This document covers naming conventions for the code. Some of these conventions are used by the framework and code generation, and as such are required. Others are our recommendations that we find useful for making the code easier to understand.
Proto files are named using the
snake_case, as defined by Protobuf. There are several special
kinds of files.
Commands and events reference model entities using their identifiers.
Having typed identifiers makes a model type safe.
Although the framework also supports
Long as valid ID types,
we strongly recommend defining custom ID types like
and others. You can find similar cases in the framework API which has
TenantId, and others.
We find it convenient to define ID types in one file called
A typical project is likely to have more than one Bounded Context, thus you will have several
Each of them resides under the directory with proto files defining the data model of the
corresponding Bounded Context.
Commands are defined in a file ending with
It can be simply
commands.proto but usually commands are handled by different entities.
Thus, it is convenient to name such a file after the type of the target entity,
for example, an aggregate:
Similarly to commands, events are defined in files which names have the
Rejection is a special “negative” kind of events supported by the framework.
A rejection is thrown if a command cannot be handled. You may think of them as of exceptions with
Similarly to events, rejections are defined in files ending with
For each aggregate you are likely to have all three kinds of files because a command leads to an event, and it is likely there are conditions under which a command cannot be handled.
We recommend gathering definition of related entity states in a file named after a business model
thing. Suppose we have a
TaskDetails projections, and
a Process Manager which is responsible for movement of a task from one project to another, there
task.proto file, with all Task-related data types definitions. A project-related data
types would be defined in a
As it was already mentioned,
ProjectId are defined in the
project.proto import this file.
Data types are defined as Protobuf messages using
Identifiers are usually defined after the name of the entity with the
You will find such naming pattern in the framework API. For example,
TenantId, and others.
This convention is not a requirement. We find
Id suffix short yet meaningful for
building a rich type-safe API. You can also select another convention that fits your domain
best. Please note that future version of the framework tools will use the
Id suffix of the
_id suffix of proto field names for code scaffolding and improving intelligence of
A command is defined as an imperative:
Events are named as facts formulated as past participles, for example:
A rejection is named after a reason of why a command cannot be handled. In fact, rejection notifies on a state of the domain model, for example:
Protobuf messages for entity states are defined using nouns, for example:
Avoid using suffixes like
ProcessManager when defining a proto type for
the following reasons:
- You may want to use such word when creating an entity Java class which uses a generated data type for holding the state of the entity.
- Such data structure does not represent a whole
ProcessManagerthing anyway. It is just data.
For details on aggregates usage, refer to a Defining Aggregate Guide.
Packages allow to form namespaces for types and avoid clashes. It is customary to have a “root” package for an organization or a service name. Most likely each Bounded Context would have a dedicated package.
Examples in this guide assume that a fictitious company called
Acme Corporation creates a SaaS solution.
The company has a web presence site with the domain name
The solution is a task management application called “Todo List”
which will be hosted at
Packages in Protobuf do not follow the reverse Internet domain name convention, which is customary in Java. It would make sense to have a root package for all types defined in an organization under the root package with a lowercase company name.
For the fictitious SaaS project of the Acme Corporation it would be:
Java does not have the notion of package nesting. Packages in Java are separated namespaces, which seem hierarchical for convenience. When it comes to placing source code files in a project, there is usually nesting formed by the directories in a file system.
Spine framework uses this notion of “nesting” for marking multiple packages of a server-side code belonging to a Bounded Context easier. But this is a convenience feature, not a requirement.
Please see our recommendations for organizing generated and handcrafted code in sections below.
Have package per data type
It is easier to see everything related to a type, if all the generated code comes under a “home” package of a data type. For example:
This package would be a part of API shared between client- and server-side code of your application.
We recommend putting command classes under a package which ends with
The package name is singular because it reads better in a fully-qualified class name of a command message.
Similarly to commands, we recommend putting events generated by an entity under the
Similarly to events, rejections are placed under the package called
Unlike commands and events, rejection messages are generated under a file named
The class is placed into a
rejection package of the corresponding type.
The package also contains generated
Throwable top-level classes that match rejection messages.
These classes are used in the
throws clause of command handling methods.
The arrangement with message classes nested under
Rejections class and top-level
is required to avoid name clashes while keeping these generated classes under the same package.
For details on rejections usage, refer to Defining Rejections Guide.
To avoid unwanted dependencies we find it useful to put server-side code under
a sub-package called
server with sub-packages for corresponding entity types:
Handcrafted Java Classes
When naming entities we find it natural to start with a name of a state class and then add a suffix which tells the type of the entity:
The suffix helps for observing together with other entities in a package.
For process managers it may be enough to have the
Process suffix dropping
which frequently worked for us too. Other options for suffixes are
It would be a good idea to decide on such suffix as a team standard before you start coding.
We recommend not using a type infix for naming repository classes. Alphabetical sorting would
make a repository class be next to an entity class, and you would not deal much with repository
classes anyway. Thus, it is just
SomethingRepository rather than
Bounded Contexts names follow
TitleCapitalization favoring plurals:
Although, singular names are perfectly fine too, for example:
If a name of a Bounded Context is used in a package, its name is transformed according to the rules of a programming language.
A Java class that creates and configures an instance of a
BoundedContext is named after the
name of the context with the