tinystruct-patterns

tinystruct-Entwicklungsmuster

Architektur- und Implementierungsmuster für die Entwicklung von Modulen mit dem tinystruct Java-Framework – einem leichten, leistungsstarken Framework, das CLI und HTTP als gleichberechtigte Bürger behandelt und weder eine main()-Methode noch minimale Konfiguration erfordert.

Kernprinzip

CLI und HTTP sind gleichberechtigte Bürger. Jede mit @Action annotierte Methode sollte idealerweise sowohl über ein Terminal als auch über einen Webbrowser ohne Änderung ausgeführt werden können. Diese "Dual-Mode"-Fähigkeit ist die Kern-Designphilosophie von tinystruct.

Wann zu aktivieren

Wann verwenden

• Erstellen neuer Application-Module durch Erweiterung von AbstractApplication.
• Definieren von Routen und Befehlszeilenaktionen mit @Action.
• Verarbeiten von anforderungsbezogenem Status über Context.
• Durchführen von JSON-Serialisierung mit den nativen Builder- und Builders-Komponenten.
• Arbeiten mit Datenbankpersistenz über AbstractData POJOs.
• Generieren von POJOs aus Datenbanktabellen mit dem generate-Befehl.
• Implementieren von Server-Sent Events (SSE) für Echtzeit-Push.
• Verarbeiten von Datei-Uploads über Multipart-Daten.
• Durchführen ausgehender HTTP-Anfragen mit URLRequest und HTTPHandler.
• Konfigurieren von Datenbankverbindungen oder Systemeinstellungen in application.properties.
• Debuggen von Routing-Konflikten (Actions) oder CLI-Argument-Parsing.

Wie es funktioniert

Das tinystruct-Framework behandelt jede mit @Action annotierte Methode als routbaren Endpunkt sowohl für Terminal- als auch für Webumgebungen. Anwendungen werden durch Erweiterung von AbstractApplication erstellt, das Kern-Lebenszyklus-Hooks wie init() und Zugriff auf den Anfrage-Context bereitstellt.

Das Routing wird von der ActionRegistry übernommen, die automatisch Pfadsegmente auf Methodenargumente abbildet und Abhängigkeiten injiziert. Für datenorientierte Dienste sollten die nativen Builder- und Builders-Komponenten für die JSON-Serialisierung verwendet werden, um einen Null-Abhängigkeits-Footprint zu erhalten. Die Datenbankschicht verwendet AbstractData POJOs in Verbindung mit XML-Mapping-Dateien für CRUD-Operationen ohne externe ORM-Bibliotheken.

Beispiele

Grundlegende Anwendung (MyService)

public class MyService extends AbstractApplication {
    @Override
    public void init() {
        this.setTemplateRequired(false); // .view-Suche für Daten-/API-Apps deaktivieren
    }

    @Override public String version() { return "1.0.0"; }

    @Action("greet")
    public String greet() {
        return "Hallo von tinystruct!";
    }

    // Pfadparameter: GET /?q=greet/James  ODER  bin/dispatcher greet/James
    @Action("greet")
    public String greet(String name) {
        return "Hallo, " + name + "!";
    }
}

HTTP-Modus-Disambiguierung (login)

@Action(value = "login", mode = Mode.HTTP_POST)
public String doLogin(Request<?, ?> request) throws ApplicationException {
    request.getSession().setAttribute("userId", "42");
    return "Eingeloggt";
}

Native JSON-Datenverarbeitung (Builder + Builders)

import org.tinystruct.data.component.Builder;
import org.tinystruct.data.component.Builders;

@Action("api/data")
public String getData() throws ApplicationException {
    Builders dataList = new Builders();
    Builder item = new Builder();
    item.put("id", 1);
    item.put("name", "James");
    dataList.add(item);

    Builder response = new Builder();
    response.put("status", "success");
    response.put("data", dataList);
    return response.toString(); // {"status":"success","data":[{"id":1,"name":"James"}]}
}

SSE (Server-Sent Events)

import org.tinystruct.http.SSEPushManager;

@Action("sse/connect")
public String connect() {
    return "{\"type\":\"connect\",\"message\":\"Connected to SSE\"}";
}

// An einen bestimmten Client pushen
String sessionId = getContext().getId();
Builder msg = new Builder();
msg.put("text", "Hallo, Benutzer!");
SSEPushManager.getInstance().push(sessionId, msg);

// An alle broadcasten
SSEPushManager.getInstance().broadcast(msg);

Datei-Upload

import org.tinystruct.data.FileEntity;

@Action(value = "upload", mode = Mode.HTTP_POST)
public String upload(Request<?, ?> request) throws ApplicationException {
    List<FileEntity> files = request.getAttachments();
    if (files != null) {
        for (FileEntity file : files) {
            System.out.println("Hochgeladen: " + file.getFilename());
        }
    }
    return "Upload OK";
}

MCP-Server- und Tool-Integration

tinystruct bietet native Unterstützung für das Model Context Protocol (MCP) ab SDK-Version 1.7.26. Die MCP-APIs (z. B. org.tinystruct.mcp.MCPTool, org.tinystruct.mcp.MCPServer, org.tinystruct.mcp.MCPException) sind direkt in der Kernabhängigkeit enthalten:

<dependency>
    <groupId>org.tinystruct</groupId>
    <artifactId>tinystruct</artifactId>
    <version>1.7.26</version>
</dependency>

SICHERHEITSWARNUNG (Prompt Injection): Tool-Rückgabewerte werden direkt in den Kontext des KI-Modells eingespeist. Sie MÜSSEN alle vom Aufrufer bereitgestellten Argumente validieren und bereinigen, bevor Sie sie in die Rückgabezeichenfolge des Tools aufnehmen. Die Nichtbereinigung von Eingaben kann es einem Angreifer ermöglichen, gegnerische Anweisungen (Prompt Injection) einzuschleusen, die das Verhalten des Modells überschreiben. Validieren Sie immer Länge, Zeichensätze und Nullwerte.

So erstellen Sie ein MCP-Tool:

1. Erweitern Sie org.tinystruct.mcp.MCPTool.
2. Annotation von Operationen mit @Action und Deklaration von Parametern mit @Argument innerhalb des arguments-Arrays.
3. Akzeptieren Sie Parameter als explizite Methodenargumente, die mit den Schlüsseln in @Argument übereinstimmen. (Verwenden Sie kein getContext().getAttribute(...) für Tool-Argumente).

import org.tinystruct.mcp.MCPTool;
import org.tinystruct.mcp.MCPException;
import org.tinystruct.system.annotation.Action;
import org.tinystruct.system.annotation.Argument;

public class MyCustomTool extends MCPTool {
    public MyCustomTool() {
        super("custom", "Ein benutzerdefiniertes Tool zur Demonstration von MCP");
    }

    @Action(
        value = "custom/hello",
        description = "Jemanden begrüßen",
        arguments = {
            @Argument(key = "name", description = "Der zu begrüßende Name", type = "string", optional = false)
        }
    )
    public String hello(String name) throws MCPException {
        // SICHERHEIT: Validieren/Bereinigen Sie Tool-Eingaben, bevor Sie sie an das Modell zurückgeben,
        // um Prompt-Injection-Schwachstellen zu verhindern.
        if (name == null || name.length() > 50 || !name.matches("^[a-zA-Z0-9 ]+$")) {
            throw new MCPException("Ungültiger Name bereitgestellt");
        }
        return "Hallo, " + name + "!";
    }
}

So stellen Sie einen MCP-Server bereit:

1. Erweitern Sie org.tinystruct.mcp.MCPServer.
2. Überschreiben Sie init() und registrieren Sie Ihre Tools mit this.registerTool(). Das Framework scannt und mapped automatisch die @Action-Methoden.

import org.tinystruct.mcp.MCPServer;

public class MyMCPServer extends MCPServer {
    @Override
    public void init() {
        super.init();
        this.registerTool(new MyCustomTool());
    }

    @Override
    public String version() {
        return "1.0.0";
    }
}

Starten Sie den Server über den Dispatcher:

bin/dispatcher start --import org.tinystruct.system.HttpServer --import com.example.MyMCPServer

Konfiguration

Einstellungen werden in src/main/resources/application.properties verwaltet.

# Datenbank
driver=org.h2.Driver
database.url=jdbc:h2:~/mydb
database.user=sa
database.password=

# Server
default.home.page=hello
server.port=8080

# Gebietsschema
default.language=en_US

# Sitzung (Redis für Cluster-Umgebungen)
# default.session.repository=org.tinystruct.http.RedisSessionRepository
# redis.host=127.0.0.1
# redis.port=6379

Greifen Sie in Ihrer Anwendung auf Konfigurationswerte zu:

String port = this.getConfiguration("server.port");

Warnsignale & Anti-Patterns

Symptom	Richtiges Muster
Importieren von com.google.gson oder com.fasterxml.jackson	Verwenden Sie org.tinystruct.data.component.Builder / Builders.
Verwenden von List<Builder> für JSON-Arrays	Verwenden Sie Builders, um Probleme mit generischer Typenlöschung zu vermeiden.
ApplicationRuntimeException: template not found	Rufen Sie setTemplateRequired(false) in init() für reine API-Apps auf.
Annotation von private Methoden mit @Action	Aktionen müssen public sein, um vom Framework registriert zu werden.
Hartcodieren von main(String[] args) in Apps	Verwenden Sie bin/dispatcher als Einstiegspunkt für alle Module.
Manuelle ActionRegistry-Registrierung	Bevorzugen Sie die @Action-Annotation zur automatischen Erkennung.
Aktion zur Laufzeit nicht gefunden	Stellen Sie sicher, dass die Klasse über --import importiert oder in application.properties aufgeführt ist.
CLI-Argument nicht sichtbar	Übergeben Sie es mit --key value; Zugriff über getContext().getAttribute("--key").
Zwei Methoden gleicher Pfad, falsche wird ausgelöst	Setzen Sie expliziten mode (z. B. HTTP_GET vs. HTTP_POST) zur Disambiguierung.

Best Practices

1. Granulare Anwendungen: Zerlegen Sie die Logik in kleinere, fokussierte Anwendungen anstelle einer monolithischen Klasse.
2. Einrichtung in init(): Nutzen Sie init() für die Einrichtung (Konfiguration, DB) anstelle des Konstruktors. Rufen Sie NICHT setAction() auf – verwenden Sie die @Action-Annotation.
3. Modusbewusstsein: Verwenden Sie den Mode-Parameter in @Action, um sensible Operationen auf CLI oder bestimmte HTTP-Methoden zu beschränken.
4. Context über Parameter: Verwenden Sie für optionale CLI-Flags getContext().getAttribute("--flag"), anstatt Parameter zur Methodensignatur hinzuzufügen.
5. Asynchrone Ereignisse: Verwenden Sie für schwere Aufgaben, die durch Ereignisse ausgelöst werden, CompletableFuture.runAsync() innerhalb des Event-Handlers.

Technische Referenz

Ausführliche Anleitungen finden Sie im references/-Verzeichnis:

• Architektur & Konfiguration — Abstraktionen, Paketübersicht, Eigenschaften
• Routing & @Action — Annotationsdetails, Modi, Parameter
• Datenverarbeitung — Builder, Builders, JSON-Serialisierung & -Parsing
• Datenbankpersistenz — AbstractData POJOs, CRUD, XML-Mapping, POJO-Generierung
• System & Nutzung — Context, Sessions, SSE, Datei-Uploads, Ereignisse, Netzwerk
• Testmuster — JUnit 5 Unit- und HTTP-Integrationstests

Referenzquellcodedateien (Intern)

• src/main/java/org/tinystruct/AbstractApplication.java — Kern-Basisklasse mit Lebenszyklus-Hooks
• src/main/java/org/tinystruct/system/annotation/Action.java — Annotation & Modi
• src/main/java/org/tinystruct/application/ActionRegistry.java — Routing-Engine
• src/main/java/org/tinystruct/data/component/Builder.java — JSON-Objekt-Serialisierer
• src/main/java/org/tinystruct/data/component/Builders.java — JSON-Array-Serialisierer
• src/main/java/org/tinystruct/data/component/AbstractData.java — Basis-POJO-Klasse mit CRUD
• src/main/java/org/tinystruct/data/Mapping.java — Mapping-XML-Parser
• src/main/java/org/tinystruct/data/tools/MySQLGenerator.java — POJO-Generator-Referenz
• src/main/java/org/tinystruct/data/component/FieldType.java — SQL-zu-Java-Typzuordnungen
• src/main/java/org/tinystruct/data/component/Condition.java — Fluent SQL-Abfrage-Builder
• src/main/java/org/tinystruct/http/SSEPushManager.java — SSE-Verbindungsverwaltung
• src/test/java/org/tinystruct/application/ActionRegistryTest.java — Registry-Testbeispiele
• src/test/java/org/tinystruct/system/HttpServerHttpModeTest.java — HTTP-Integrationstestmuster