Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

command

/command

Definiuje komendę Protean, niezmienny DTO opisujący zamiar zmiany stanu agregatu, nazywany czasownikiem w trybie rozkazującym (PlaceOrder, RegisterUser, CancelReservation).

Repozytorium
protean ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
11
Skrypty
5
Komentarze HTML
0
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co sprawdzić przed instalacją
  • 5 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.

Skrypty: assets/command_inheritance.py, assets/command_simple.py, assets/command_validation.py, assets/command_with_value_object.py, assets/submitting_commands.py

Co robi i kiedy

Definiuje komendę Protean, niezmienny DTO opisujący zamiar zmiany stanu agregatu, nazywany czasownikiem w trybie rozkazującym (PlaceOrder, RegisterUser, CancelReservation).

Wyzwalacze z opisu

create a commanddefine a commandadd a commandplace an order
Oryginalny opis (EN)

Define a Protean command, an immutable DTO representing an intent to change aggregate state. Commands encapsulate the data necessary to perform a specific action and are processed by command handlers. Commands are always associated with aggregates and are named with imperative verbs (PlaceOrder, RegisterUser, CancelReservation). Use when you need to define an action or operation that changes domain state, when the user asks to "create a command", "define a command", "add a command", when implementing CQRS patterns, or when they describe an action they want to perform (like "place an order", "r

Jak działa

  1. Basic structure
  2. Key rules
  3. Fields and options
  4. Quick example
  5. Submitting commands
  6. Common mistakes
  7. Detailed references
  8. Verify your work
Sekcje z nagłówków SKILL.md, w oryginale · 200 linii, 744 słów
Podgląd SKILL.md
---
name: command
description: Define a Protean command, an immutable DTO representing an intent to change aggregate state. Commands encapsulate the data necessary to perform a specific action and are processed by command handlers. Commands are always associated with aggregates and are named with imperative verbs (PlaceOrder, RegisterUser, CancelReservation). Use when you need to define an action or operation that changes domain state, when the user asks to "create a command", "define a command", "add a command", when implementing CQRS patterns, or when they describe an action they want to perform (like "place an order", "register a user", "cancel a reservation"). Commands can be processed synchronously or asynchronously.
license: Apache-2.0
compatibility: Requires Python 3.11+, protean framework
metadata:
  author: proteanhq
  version: "0.1"
  category: element
  diagnostic_codes:
    - COMMAND_NOT_IMPERATIVE
    - UNUSED_COMMAND
---

# Command

A command carries one request to change one aggregate, and exactly one command handler processes it. This skill defines commands: fields, naming, and how to submit them.

## Basic structure

A command is defined using the `@domain.command(part_of="...")` decorator:

```python
from protean import Domain
from protean.fields import String, Identifier

domain = Domain()

@domain.aggregate
class Order:
    customer_id: String(required=True)

@domain.command(part_of="Order")
class PlaceOrder:
    order_id: Identifier(required=True)
    customer_id: String(required=True)
    product_id: String(required=True)
```

## Key rules

1. **Commands must be associated with aggregates**: Always specify `part_of` parameter with the aggregate name
2. **Commands are named with imperative verbs**: Use imperative mood: `PlaceOrder`, not `OrderPlaced`
3. **Commands are immutable**: Once created, commands cannot be modified
4. **Commands are DTOs**: Can contain simple fields and value objects, but NOT entities or aggregates (no HasOne, HasMany)
5. **Commands are unique**: Each command is unique throughout the domain
6. **One handler per command**: A command can only be processed by one command handler
7. **Commands carry intent**: They describe what should happen, not what happened (that is events)
8. **Commands have metadata**: Protean automatically adds timestamps, unique IDs, and versioning
9. **Commands are submitted via `domain.process()`**: The domain dispatches to the appropriate handler
10. **Commands support sync and async processing**: Controlled per-instance or via domain configuration

## Fields and options

| Field/Option | Purpose | Required |
|--------------|---------|----------|
| `part_of` | Associate command with an aggregate | Yes (unless abstract) |
| `abstract` | Mark as abstract base command | No |
| `__version__` | Schema version as positive integer (defaults to `1`) | No |

### Supported field types

```python
from protean.fields import (
    String, Integer, Float, Boolean,
    DateTime, Date, Identifier,
    List, Dict, ValueObject,
)
```

Commands cannot use `HasOne`, `HasMany`, or `Reference` fields.

## Quick example

```python
from protean import Domain, handle
from protean.fields import DateTime, Decimal, Identifier, String

domain = Domain()

@domain.aggregate
class Order:
    order_id: Identifier(identifier=True)
    customer_id: String(required=True)
    total_amount: Decimal(precision=19, scale=4)

@domain.command(part_of="Order")
class PlaceOrder:
    order_id: Identifier(required=True)
    customer_id: String(required=True)
    total_amount: Decimal(precision=19, scale=4, required=True)

# Register the handler before init(); one registered after is not wired
@domain.command_handler(part_of="Order")
class OrderCommandHandler:
    @handle(PlaceOrder)
    def place_order(self, command: PlaceOrder):
        order = Order(
            order_id=command.order_id,
            customer_id=command.customer_id,
            total_amount=command.total_amount,
        )
        domain.repository_for(Order).add(order)

domain.init(traverse=False)

# Create and submit command
with domain.domain_context():
    command = PlaceOrder(
        order_id="ORD-001",
        customer_id="CUST-123",
        total_amount=99.99
    )
    domain.process(command)
```

## Submitting commands

Commands are submitted to the domain for processing:

```python
with domain.domain_context():
    # Default processing (based on domain config, default is async)
    domain.process(command)

    # Explicit synchronous processing
    domain.process(command, asynchronous=False)

    # Explicit asynchronous processing
    domain.process(command, asynchronous=True)
```

Domain-wide configuration:

```python
# In domain.toml
# command_processing = "sync"  # or "async"

# In code
domain.config["command_processing"] = "sync"
```

## Common mistakes

### Including entities in commands

```python
# fragment
@domain.command(part_of="Order")
class PlaceOrder:
    items = HasMany(OrderItem)  # Wrong! Commands can't contain entities
```

Instead: Only fields and value objects

```python
@domain.value_object
class Money:
    amount: Decimal(precision=19, scale=4, required=True)
    currency: String(max_length=3, default="USD")

@domain.command(part_of="Order")
class PlaceOrder:
    order_id: Identifier(required=True)
    customer_id: String(required=True)
    items: List()  # Serialize as list of dicts
    total = ValueObject(Money)  # Value objects are allowed
```

### Trying to modify a command after creation

```python
# fragment
command = PlaceOrder(order_id="ORD-001", customer_id="CUST-123")
command.customer_id = "CUST-456"  # Raises IncorrectUsageError!
```

Instead: Create a new command instance with the values you need.

### What `check` reports

`check` inspects your commands and reports these diagnostics:

- `COMMAND_NOT_IMPERATIVE`: the command is named in a mood that is not imperative (`OrderPlacement`), so it reads like data or an event. Rename it to a verb-first imperative phrase (`PlaceOrder`).
- `UNUSED_COMMAND`: the command has no registered handler, so nothing processes it. Add a command handler method for it, or remove the command if it is unused.

## Detailed references

### Core Concepts
- [Commands with Value Objects](references/with-value-objects.md): Using value objects in commands
- [Command Validation](references/command-validation.md): Field validation and error handling
- [Command Processing](references/command-processing.md): Synchronous and asynchronous processing
- [Command Inheritance](references/command-inheritance.md): Abstract commands and inheritance
- [Anti-patterns](references/anti-patterns.md): Common mistakes and how to avoid them

### Complete Examples
- [Simple Command](assets/command_simple.py): Basic commands with simple fields
- [Command with Value Objects](assets/command_with_value_object.py): Commands containing value objects
- [Command Validation](assets/command_validation.py): Field validation examples
- [Command Inheritance](assets/command_inheritance.py): Abstract base commands and inheritance
- [Submitting Commands](assets/submitting_commands.py): Command submission and processing

### Related Skills
- `aggregate`: Commands are always part of aggregates
- `command-handler`: How commands are processed
- `event`: Commands and events are complementary (commands = intent, events = result)
- `value-object`: Commands can contain value objects
- [CQRS](https://docs.proteanhq.com/concepts/architecture/cqrs/): Commands are the "C" in CQRS

## Verify your work

- [Verify with check](../../references/verify-with-check.md): run `check` and resolve what it reports
Pliki w paczce (11)
  • SKILL.md 7 KB
  • assets/command_inheritance.py 4 KB
  • assets/command_simple.py 4 KB
  • assets/command_validation.py 4 KB
  • assets/command_with_value_object.py 5 KB
  • assets/submitting_commands.py 4 KB
  • references/anti-patterns.md 6 KB
  • references/command-inheritance.md 3 KB
  • references/command-processing.md 4 KB
  • references/command-validation.md 4 KB
  • references/with-value-objects.md 2 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · proteanhq/protean100Apache-2.0
proteanhq/protean100Apache-2.0

Identyczna treść występuje jeszcze w 1 innych folderach na GitHubie. Tu pokazujemy jedną, najlepiej ocenioną kopię.

Migawka bazy z 13.11.2026 · wersja paczki c74b2717db31 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100query
    Definiuje zapytanie Protean jako niezmienny obiekt DTO do odczytu z projekcji w architekturze CQRS.
  • 100event
    Definiuje zdarzenie domenowe w Protean, czyli niezmienny fakt o zmianie stanu agregatu, nazwany w czasie przeszłym.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.