Konwencje Total.js 5 dla asystentów kodowania

Total.js 5 · total5@0.0.19 aiconventionsguidelinescontextnativeactions Uruchomiono z Total.js 5

Używaj tego przewodnika razem z wytycznymi Total.js i Total.js AI Context. Ich przejrzane commity są zapisane w ai-sources.json. To różne rodzaje dowodów: wytyczne stylu opisują konwencje; zachowanie w czasie działania musi zgadzać się z zainstalowanym frameworkiem i wykonywalnym przykładem. Ta strona nie poświadcza każdego przykładu w żadnym z zewnętrznych repozytoriów.

Utrzymuj kod aplikacji natywny

Gdy bootstrap załaduje total5, runtime udostępnia swoje globalne obiekty i ładuje pliki aplikacji z katalogów frameworka. Używaj MAIN, FUNC, MODS, CONF i PATH zgodnie z ich udokumentowanymi rolami. Preferuj istniejące udogodnienie frameworka, zanim dodasz zamiennik lub zależność. Nie importuj kontrolerów i definicji aplikacji jedne do drugich tylko po to, by naśladować strukturę projektu innego frameworka. Samodzielne skrypty i naprawdę zewnętrzne zależności mają inną granicę importu.

W nowym kodzie aplikacji stosuj styl ekosystemu: nazwy plików małymi literami, tabulatory, średniki, krótkie ciągi w pojedynczych cudzysłowach oraz odpowiednie powiązania var lub let wewnątrz metod. Importy na poziomie modułu mogą używać const i nazw modułów pisanych wielką literą. Utrzymuj spójne nazwy w całej aplikacji. Szczegóły i wyjątki znajdziesz w linkowanych wytycznych i rzeczywistych konwencjach projektu.

Rozróżniaj API i ich konteksty

Zwykły kontroler HTTP otrzymuje $; wysyłaj JSON przez $.json() i ustawiaj status odpowiedzi przez $.response.status.
Akcja otrzymuje swój kontekst akcji $ i zwalidowany model; zwracaj przez $.callback(). Kontroler HTTP, jeśli jest, to $.controller.
W Total.js 5 NEWSCHEMA(name, '...') tworzy wielokrotnego użytku kompaktowy schemat. Jego forma z callbackiem grupuje akcje przez schema.action(). Przykładu z Total.js 4 ze schema.define() / schema.setSave() nie wolno przedstawiać jako wymiennego API Total.js 5.
Dla nowych izolowanych operacji preferuj stabilne, jawne publiczne ID akcji, takie jak Contacts|create. Istniejące pogrupowane akcje mogą mieć ID takie jak Contacts/create; szanuj ID i trasy zadeklarowane przez aplikację zamiast ślepo je zmieniać.
W API Routing rozróżniaj autoryzację na trasie od publicznej nazwy operacji i koperty { schema, data }. Zwykłe trasy HTTP też są obsługiwane; nie zmuszaj każdej odpowiedzi JSON do przechodzenia przez akcję.
Integrację z bazą danych, politykę uwierzytelniania i autoryzację traktuj jako wymagania aplikacji. To, że framework ma udogodnienie, nie znaczy, że aplikacja produkcyjna jest automatycznie skonfigurowana lub bezpieczna.

AI Context zawiera przykłady z konwencjami akcji zarówno izolowanych, jak i pogrupowanych. Repozytorium wytycznych zawiera też starsze przykłady schematów. Uzgodnij każdy przykład z jego wersją i runtime zamiast kopiować wszystkie fragmenty do jednego kontekstu. Wykonywalny przykład poniżej sprawdza stabilne ID akcji i bezpośredni kontroler z zainstalowanym pakietem Total.js 5.

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' });
}

Zanim przekażesz wygenerowany kod komuś

Ustal zainstalowane wersje frameworka i frontendu, przeczytaj odpowiednie strony Forge, uruchom właściwy przykład i napisz, co pozostaje nieprzetestowane. Sprawdzenie nazw globalnych jest użytecznym sygnałem, ale nie zastępuje uruchomienia kodu. Przy publikowaniu przykładów zachowaj rewizję źródła, kontrakt wejścia i warunki testu.

Wybór Total.js dotyczy decyzji architektonicznych. Krótki kontekst to punkt wyjścia dla asystenta, któremu Forge wyraźnie podano jako źródło; jego dostarczenie to co innego niż mierzenie spontanicznych rekomendacji modelu.