Methodendefinitionen

CK Language 2 erlaubt es einem Typ oder einem Interface, Methoden zu deklarieren: benannte, versionierte Operationen mit typisierten Parametern, einem Ergebnis, deklarierten Fehlercodes sowie Autorisierungs- und Ausführungseinstellungen. Methoden sind der vorgesehene Weg, Attribute zu ändern, die nicht generisch geschrieben werden dürfen (access: MethodOnly), und ad-hoc-REST-Endpunkte zu ersetzen.

Nur Definitionen

In dieser Phase sind Methoden ausschließlich Definitionen. Sie werden vom Compiler validiert, persistiert, in der generierten Dokumentation angezeigt und in generierte C#-Verträge überführt – es gibt aber noch keinen Aufruf: keine GraphQL-Methoden-Mutationen, keine Handler-Zuordnung. Die Methoden-Laufzeit folgt in einer späteren Phase. Wenn Sie Methoden jetzt definieren, können sich die Verträge Ihrer Modelle frühzeitig stabilisieren.

Syntax

types:
  - typeId: Device
    # ...
    methods:
      - methodId: UpdateFirmware-1
        kind: Instance                 # Instance (default) | Static
        description: Installs a firmware version.
        parameters:
          - name: version
            valueType: String
          - name: signingKey
            valueType: String
            sensitive: true            # never logged, never in audit or traces
        errors:
          - code: FIRMWARE_REJECTED
            description: The device refused the image.
        authorization:
          roles: [ AssetManagement ]   # any of these roles
        execution:
          timeoutSeconds: 60           # 1..300, default 15
          idempotent: false            # default false

Schlüssel	Erforderlich	Beschreibung
methodId	ja	PascalCase-Name mit Elementversion, z. B. ChangePassword-1. Eine geänderte Signatur wird als neue Version veröffentlicht (ChangePassword-2).
kind	nein	Instance (Standard, wird auf einer einzelnen Entität aufgerufen) oder Static.
description	nein	Freitext.
parameters	nein	Liste mit name (camelCase), valueType, valueCkRecordId / valueCkEnumId (für Record / Enum), isOptional, sensitive, description.
result	nein	valueType plus valueCkRecordId / valueCkEnumId. Bei Methoden ohne Ergebnis weglassen.
errors	nein	Deklarierte fachliche Fehlercodes: code (UPPER_SNAKE_CASE, kein Präfix METHOD_ – dieses ist für Plattformfehler reserviert), description.
authorization	nein	roles (eine davon genügt; Namen werden ohne Beachtung der Groß-/Kleinschreibung verglichen), allowSelf (die Benutzer-ID des Aufrufers entspricht der ID der Zielentität; nur Instanzmethoden), scopes (zusätzliche Scopes, alle erforderlich; octo_api ist immer erforderlich). Default-Deny: Eine Methode ohne authorization oder mit leerem roles kann nur von Administratoren aufgerufen werden (nicht vom Eigentümer). Rollen- und Scope-Namen bestehen aus Buchstaben, Ziffern und _ - . : / und beginnen mit einem Buchstaben oder einer Ziffer (Meldung 104).
execution	nein	timeoutSeconds (1–300, Standard 15), idempotent (Standard false).
visibility	nein	Public (Standard) oder Internal.

Wertetypen für Parameter und Ergebnis: String, Boolean, DateTime, DateTimeOffset, TimeSpan, Int, Int64, Double, StringArray, IntArray, Enum, Record.

Methoden auf Interfaces verwenden dasselbe Schema. Methoden werden an abgeleitete Typen und an Typen vererbt, die das Interface implementieren.

Compiler-Regeln

Regel	Meldung
Eine Methoden-ID ist auf einem Typ eindeutig, und ein Typ deklariert keine geerbte Methoden-ID erneut (keine Überschreibungen)	100
Parameter verweisen auf bekannte Records/Enums, Namen sind eindeutig, Record/Enum haben genau die passende valueCkRecordId/valueCkEnumId	101
Die Namen Create, Update, Delete sind reserviert (ohne Beachtung der Groß-/Kleinschreibung)	102
Fehlercodes sind eindeutig und beginnen nicht mit METHOD_	103
allowSelf: true ist bei einer Static-Methode nicht erlaubt	104
Ein Typ deklariert eine Interface-Methode mit einem abweichenden Aufrufvertrag erneut (kind, Parameter, Ergebnis, Fehlercodes)	122
Zwei Methoden eines Modells erzeugen denselben generierten C#-Namen (User + ChangePassword vs. UserChange + Password)	125

Generierter Code

Für jede Typmethode erzeugt der Source Generator:

• eine Methoden-ID-Konstante in der *CkIds-Klasse des Modells, z. B. DeviceUpdateFirmwareMethodId = "Acme.Assets/Device.UpdateFirmware-1" (eine Version größer als 1 wird angehängt: DeviceUpdateFirmware2MethodId);
• einen Parameter-Record DeviceUpdateFirmwareParameters (erforderliche Parameter sind required, optionale nullable; sensitive-Parameter werden in ToString() als *** ausgegeben);
• einen Ergebnis-Record {Type}{Method}Result { Value }, wenn die Methode ein Ergebnis hat.

Interface-Methoden erhalten keine Records.

Versionierung

• Eine neue Methode ist eine Minor-Änderung.
• Das Entfernen einer Methode oder die Änderung ihrer Signatur (kind, Parameter, Ergebnis, Fehler, Autorisierung, Ausführung) ist Major – veröffentlichen Sie stattdessen eine neue Methodenversion (UpdateFirmware-2).
• description sowie Parameter-/Fehlerbeschreibungen sind Patch-Änderungen; sie gehören nicht zur Signatur.

Siehe auch

• Zugriffsmodifikatoren – access: MethodOnly
• Interfaces
• Compiler-Meldungen