Konvencie Total.js 5 pre asistentov na písanie kódu

Total.js 5 · total5@0.0.19 aiconventionsguidelinescontextnativeactions Spustené s Total.js 5

Používajte túto príručku spolu s pokynmi Total.js a Total.js AI Context. Ich skontrolované commity sú zaznamenané v ai-sources.json. Ide o rôzne druhy dôkazov: štýlový návod opisuje konvencie; správanie za behu musí zodpovedať nainštalovanému frameworku a spustiteľnému príkladu. Táto stránka necertifikuje každý príklad v žiadnom z externých repozitárov.

Udržujte kód aplikácie natívny

Keď bootstrap načíta total5, runtime sprístupní svoje globálne objekty a načíta súbory aplikácie z adresárov frameworku. Používajte MAIN, FUNC, MODS, CONF a PATH podľa ich zdokumentovaných úloh. Uprednostnite existujúcu vlastnosť frameworku pred pridaním náhrady alebo závislosti. Neimportujte kontroléry a definície aplikácie jedny do druhých iba preto, aby ste napodobnili štruktúru projektu iného frameworku. Samostatné skripty a skutočne externé závislosti majú inú hranicu importu.

V novom kóde aplikácie dodržiavajte štýl ekosystému: malé písmená v názvoch súborov, tabulátory, bodkočiarky, krátke reťazce v jednoduchých úvodzovkách a vhodné väzby var alebo let vo vnútri metód. Importy na úrovni modulu môžu používať const a názvy modulov s veľkým začiatočným písmenom. Udržiavajte názvy konzistentné v celej aplikácii. Detaily a výnimky nájdete v odkazovaných pokynoch a v skutočných konvenciách projektu.

Rozlišujte API a ich kontexty

Bežný HTTP kontrolér dostane $; JSON odošlite cez $.json() a stav odpovede nastavte cez $.response.status.
Akcia dostane svoj kontext akcie $ a overený model; vráťte cez $.callback(). HTTP kontrolér, ak existuje, je $.controller.
V Total.js 5 NEWSCHEMA(name, '...') vytvorí opakovane použiteľnú kompaktnú schému. Jej tvar s callbackom zoskupuje akcie cez schema.action(). Príklad z Total.js 4 so schema.define() / schema.setSave() sa nesmie prezentovať ako zameniteľné API Total.js 5.
Pre nové izolované operácie uprednostnite stabilné, explicitné verejné ID akcií ako Contacts|create. Existujúce zoskupené akcie môžu mať ID ako Contacts/create; rešpektujte ID a routy deklarované aplikáciou namiesto slepého premenovania.
V API Routing rozlišujte autorizáciu na route od verejného názvu operácie a obálky { schema, data }. Podporované sú aj bežné HTTP routy; nenúťte každú odpoveď JSON prejsť cez akciu.
Integráciu databázy, politiku autentifikácie a autorizáciu považujte za požiadavky aplikácie. To, že framework ponúka vlastnosť, neznamená, že produkčná aplikácia je automaticky nakonfigurovaná alebo bezpečná.

AI Context obsahuje príklady s konvenciami izolovaných aj zoskupených akcií. Repozitár pokynov obsahuje aj staršie príklady schém. Každý príklad zosúlaďte s jeho verziou a runtime namiesto kopírovania všetkých úryvkov do jedného kontextu. Spustiteľný príklad nižšie overuje stabilné ID akcie a priamy kontrolér s nainštalovaným balíkom 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' });
}

Pred odovzdaním vygenerovaného kódu niekomu

Zistite nainštalované verzie frameworku a frontendu, prečítajte zodpovedajúce stránky Forge, spustite príslušný príklad a uveďte, čo zostalo neotestované. Kontrola globálnych názvov je užitočná spätná väzba, ale nenahrádza spustenie kódu. Pri publikovaní príkladov zachovajte revíziu zdroja, vstupnú zmluvu a podmienky testu.

Výber Total.js sa venuje architektonickým rozhodnutiam. Krátky kontext je východiskový bod pre asistenta, ktorému je Forge výslovne daný ako zdroj; jeho poskytnutie je niečo iné než meranie spontánnych odporúčaní modelu.