Files
2026-11-14 19:16:24 +05:00

135 lines
4.2 KiB
Markdown

# Domains
All domains must conform to the generic domain interface located in `internal/application`:
```go
type Domain interface{
// Configure performs domain configuration. Called after ConnectDependencies().
Configure() error
// ConnectDependencies gets necessary dependencies (other domains) from application singleton's
// registry. Called on application start after all needed domains are registered with singleton.
ConnectDependencies() error
// Initialize initializes internal state. Called when RegisterDomain() is issued.
Initialize() error
// LaunchStartupTasks launches tasks that should perform some actions on start or when these tasks
// should work in background (in separate goroutine). Called after ConnectDependencies() and Configure().
LaunchStartupTasks() error
// Name returns domain name.
Name() string
// Shutdown performs shutdown actions for domain.
Shutdown() error
}
```
## Domains categories
Every domain MUST have proper categorisation. Currently this document defines some standard categories:
- `core` - core/low-level functionality (e.g. HTTP server, database connection handling, low-level local disk storage handling).
- `features` - business code itself (e.g. working with users).
- `integrations` - third-party integrations proxy domains (e.g. integration with third-party API).
This isn't a comprehensive list, as specific application might require own domain category not described here, for example, `protocols` category where chat protocols lie (for a multi-protocol messaging app).
## Domains registration
Domains should register themselves in `Initialize(app *application.Application) error` function which should be called in `main()` function of binary. It should be done like that:
in main.go:
```go
package main
import "log/slog"
func main() {
app := application.New()
lgr := app.Logger("module", "main")
checkError(lgr, somedomain.Initialize(app))
checkError(lgr, app.Start())
<-app.ShutdownChan
if errs := app.Shutdown(); errs != nil {
lgr.Error("Failed to shutdown app!", "errors", errs)
os.Exit(2)
}
}
func checkError(lgr *slog.Logger, err error) {
if err == nil {
return
}
lgr.Error("Failed to start app!", "error", err.Error())
//revive:disable-next-line:deep-exit
os.Exit(1)
}
```
in `internal/domains/core/somedomain/somedomain.go`:
```go
var errDomain = errors.New(core.DomainNameSomeDomain)
type domain struct {
app *application.Application
}
func Initialize(app *application.Application) error {
dmn := &domain{
app: app,
}
if err := app.RegisterDomain(dmn); err != nil {
return fmt.Errorf("%w: %w", errDomain, err)
}
return nil
}
```
On application singleton's side function `(a *Application) RegisterDomain(domain Domain) error` should be implemented (see above).
## Domain-specific data
Domain-specific data should be placed in `domainname.go` file within category, e.g. `internal/domains/core/config.go` for configuration domain `internal/domains/core/config`. It should look like that:
```go
package core
import (
"errors"
"internal/domains/core/config/dto"
)
// DomainNameConfig is a configuration handling domain name.
const DomainNameConfig = "core/config"
// ErrConfigIsInvalid indicates that configuration domain implementation isn't conforming to its interface.
var ErrConfigIsInvalid = errors.New(DomainNameConfig + " implementation is invalid")
// Config is an interface for configuration handling implementations.
type Config interface{
Get() *dto.Config
}
```
Where:
- `DomainNameConfig` is a constant with domain's name that is returned by `Name() string` function of that domain.
- `ErrConfigIsInvalid` is a domain's error that should be exported for later use by other domains in any way (checking for presence or even returning it). There can be more than one error here.
- `Config` is a domain-specific interface that can be used by other domains.
## Domain-specific interface
In addition to domains common interface described above, every domain might have own interface which discloses inter-domain API. That API should use only DTOs (see [DTOs and models](dtos-models.md)).
All signatures here should have comments describing what this function does, as these comments will be shown to end users in IDEs or editors with LSPs attached when using autocomplete or documentation browser.