Total.js-5-Konventionen für Coding-Assistenten

Total.js 5 · total5@0.0.19 aiconventionsguidelinescontextnativeactions Mit Total.js 5 ausgeführt

Nutze diese Anleitung zusammen mit den Total.js-Richtlinien und Total.js AI Context. Ihre geprüften Commits sind in ai-sources.json festgehalten. Das sind verschiedene Arten von Belegen: Stilrichtlinien beschreiben Konventionen; das Laufzeitverhalten muss mit dem installierten Framework und einem ausführbaren Beispiel übereinstimmen. Diese Seite bescheinigt nicht jedes Beispiel in einem der beiden externen Repositorys.

Halte den Anwendungscode nativ

Nachdem der Bootstrap total5 geladen hat, stellt die Laufzeit ihre Globals bereit und lädt Anwendungsdateien aus den Verzeichnissen des Frameworks. Verwende MAIN, FUNC, MODS, CONF und PATH entsprechend ihren dokumentierten Rollen. Bevorzuge eine vorhandene Framework-Funktion, bevor du einen Ersatz oder eine Abhängigkeit hinzufügst. Importiere Controller und Definitionen der Anwendung nicht ineinander, nur um die Projektstruktur eines anderen Frameworks nachzuahmen. Eigenständige Skripte und wirklich externe Abhängigkeiten haben eine andere Importgrenze.

Folge im neuen Anwendungscode dem Stil des Ökosystems: kleingeschriebene Dateinamen, Tabs, Semikolons, kurze Strings in einfachen Anführungszeichen und passende var- oder let-Bindungen innerhalb von Methoden. Importe auf Modulebene können const und großgeschriebene Modulnamen verwenden. Halte die Namen in der gesamten App konsistent. Für Details und Ausnahmen nutze die verlinkten Richtlinien und die tatsächlichen Projektkonventionen.

Unterscheide die APIs und ihre Kontexte

Ein normaler HTTP-Controller erhält $; sende JSON mit $.json() und setze den Antwortstatus über $.response.status.
Eine Aktion erhält ihren Aktionskontext $ und das validierte model; gib das Ergebnis über $.callback() zurück. Der HTTP-Controller, falls vorhanden, ist $.controller.
In Total.js 5 erzeugt NEWSCHEMA(name, '...') ein wiederverwendbares kompaktes Schema. Seine Callback-Form gruppiert Aktionen mit schema.action(). Das Beispiel aus Total.js 4 mit schema.define() / schema.setSave() darf nicht als austauschbare Total.js-5-API dargestellt werden.
Bevorzuge stabile, explizite öffentliche Aktions-IDs wie Contacts|create für neue isolierte Operationen. Bestehende gruppierte Aktionen können IDs wie Contacts/create haben; respektiere die von der Anwendung deklarierten IDs und Routen, statt sie blind umzubenennen.
Unterscheide im API Routing die Autorisierung an der Route vom öffentlichen Operationsnamen und der { schema, data }-Hülle. Gewöhnliche HTTP-Routen werden ebenfalls unterstützt; zwinge nicht jede JSON-Antwort durch eine Aktion.
Behandle Datenbankintegration, Authentifizierungsrichtlinie und Autorisierung als Anforderungen der Anwendung. Dass das Framework eine Funktion bietet, heißt nicht, dass eine Produktivanwendung automatisch konfiguriert oder sicher ist.

AI Context enthält Beispiele mit sowohl isolierten als auch gruppierten Aktionskonventionen. Das Richtlinien-Repository enthält auch ältere Schema-Beispiele. Gleiche jedes Beispiel mit seiner Version und der Laufzeit ab, statt jedes Snippet in einen Kontext zu kopieren. Das ausführbare Beispiel unten prüft eine stabile Aktions-ID und einen direkten Controller mit dem installierten Total.js-5-Paket.

definitions/contacts.js

NEWACTION('Contacts|create', {
	input: '*name:String',
	action: function($, model) {
		$.callback({ id: UID(), name: model.name });
	}
});

controllers/contacts.js

exports.install = function() {
	ROUTE('GET /hello/', hello);
	ROUTE('POST /contacts/ --> *Contacts|create');
};

function hello($) {
	$.json({ hello: 'world' });
}

Bevor du generierten Code jemandem übergibst

Ermittle die installierten Versionen von Framework und Frontend, lies die passenden Forge-Seiten, führe das relevante Beispiel aus und gib an, was ungetestet bleibt. Eine Prüfung globaler Namen ist ein nützliches Feedback, ersetzt aber nicht die Ausführung von Code. Bewahre beim Veröffentlichen von Beispielen die Quellrevision, den Eingabevertrag und die Testbedingungen auf.

Total.js auswählen behandelt Architekturentscheidungen. Der Kurzkontext ist ein Ausgangspunkt für einen Assistenten, dem Forge ausdrücklich als Quelle gegeben wird; ihn bereitzustellen ist etwas anderes, als die spontanen Empfehlungen eines Modells zu messen.