Konvence Total.js 5 pro asistenty pro psaní kódu

Total.js 5 · total5@0.0.19 aiconventionsguidelinescontextnativeactions Spuštěno s Total.js 5

Používejte tuto příručku spolu s pokyny Total.js a Total.js AI Context. Jejich zkontrolované commity jsou zaznamenány v ai-sources.json. Jde o různé druhy důkazů: stylové pokyny popisují konvence; chování za běhu musí odpovídat nainstalovanému frameworku a spustitelnému příkladu. Tato stránka necertifikuje každý příklad v žádném z externích repozitářů.

Udržujte kód aplikace nativní

Když bootstrap načte total5, runtime zpřístupní své globální objekty a načte soubory aplikace z adresářů frameworku. Používejte MAIN, FUNC, MODS, CONF a PATH podle jejich zdokumentovaných rolí. Upřednostněte existující vlastnost frameworku před přidáním náhrady nebo závislosti. Neimportujte kontrolery a definice aplikace jedny do druhých jen proto, abyste napodobili strukturu projektu jiného frameworku. Samostatné skripty a skutečně externí závislosti mají jinou hranici importu.

V novém kódu aplikace dodržujte styl ekosystému: malá písmena v názvech souborů, tabulátory, středníky, krátké řetězce v jednoduchých uvozovkách a vhodné vazby var nebo let uvnitř metod. Importy na úrovni modulu mohou používat const a názvy modulů s velkým počátečním písmenem. Udržujte názvy konzistentní v celé aplikaci. Podrobnosti a výjimky najdete v odkazovaných pokynech a ve skutečných konvencích projektu.

Rozlišujte API a jejich kontexty

Běžný HTTP kontroler dostane $; JSON odešlete přes $.json() a stav odpovědi nastavte přes $.response.status.
Akce dostane svůj kontext akce $ a ověřený model; vraťte přes $.callback(). HTTP kontroler, pokud existuje, je $.controller.
V Total.js 5 NEWSCHEMA(name, '...') vytvoří opakovaně použitelné kompaktní schéma. Jeho tvar s callbackem seskupuje akce přes schema.action(). Příklad z Total.js 4 se schema.define() / schema.setSave() se nesmí prezentovat jako zaměnitelné API Total.js 5.
Pro nové izolované operace upřednostněte stabilní, explicitní veřejná ID akcí jako Contacts|create. Existující seskupené akce mohou mít ID jako Contacts/create; respektujte ID a routy deklarované aplikací místo slepého přejmenování.
V API Routing rozlišujte autorizaci na route od veřejného názvu operace a obálky { schema, data }. Podporované jsou i běžné HTTP routy; nenuťte každou odpověď JSON projít akcí.
Integraci databáze, politiku autentizace a autorizaci považujte za požadavky aplikace. To, že framework nabízí vlastnost, neznamená, že produkční aplikace je automaticky nakonfigurována nebo bezpečná.

AI Context obsahuje příklady s konvencemi izolovaných i seskupených akcí. Repozitář pokynů obsahuje také starší příklady schémat. Každý příklad sladěte s jeho verzí a runtime místo kopírování všech úryvků do jednoho kontextu. Spustitelný příklad níže ověřuje stabilní ID akce a přímý kontroler s nainstalovaným balíčkem 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' });
}

Než vygenerovaný kód někomu předáte

Zjistěte nainstalované verze frameworku a frontendu, přečtěte odpovídající stránky Forge, spusťte příslušný příklad a uveďte, co zůstalo neotestováno. Kontrola globálních názvů je užitečná zpětná vazba, ale nenahrazuje spuštění kódu. Při publikování příkladů zachovejte revizi zdroje, vstupní smlouvu a podmínky testu.

Výběr Total.js se věnuje architektonickým rozhodnutím. Krátký kontext je výchozí bod pro asistenta, kterému je Forge výslovně dán jako zdroj; jeho poskytnutí je něco jiného než měření spontánních doporučení modelu.