# Convenzioni di Total.js 5 per gli assistenti di codice

> Convenzioni per applicazioni native, priorità delle fonti e confini di versione per gli agenti che usano Total.js 5, con un esempio testato di azione e di controller diretto.

Framework: total5
Product: Total.js 5 (total5@0.0.19)
Language: it
Content-SHA256: 3d31e5bbf52d273f3140a38bf8ed326e245f84a6f1f4903a05474474e5197e78
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: total5-installed@total5@0.0.19
Review: not-recorded

Usa questa guida insieme alle [linee guida di Total.js](https://github.com/totaljs-es/guidelines) e a [Total.js AI Context](https://github.com/totaljs/aicontext). I loro commit esaminati sono registrati in [ai-sources.json](/ai-sources.json). Sono tipi diversi di evidenza: la guida di stile descrive convenzioni; il comportamento a runtime deve concordare con il framework installato e con un esempio eseguibile. Questa pagina non certifica ogni esempio di nessuno dei due repository esterni.

## Mantieni nativo il codice dell'applicazione

Dopo che il bootstrap carica `total5`, il runtime espone i suoi globali e carica i file dell'applicazione dalle directory del framework. Usa `MAIN`, `FUNC`, `MODS`, `CONF` e `PATH` secondo i loro ruoli documentati. Preferisci una funzionalità esistente del framework prima di aggiungere un sostituto o una dipendenza. Non importare controller e definizioni dell'applicazione l'uno nell'altro solo per imitare la struttura di progetto di un altro framework. Gli script autonomi e le dipendenze davvero esterne hanno un confine di importazione diverso.

Nel nuovo codice dell'applicazione segui lo stile dell'ecosistema: nomi di file minuscoli, tab, punti e virgola, stringhe brevi tra apici singoli e associazioni `var` o `let` appropriate dentro i metodi. Gli import a livello di modulo possono usare `const` e nomi di modulo con iniziale maiuscola. Mantieni i nomi coerenti in tutta l'app. Per dettagli ed eccezioni usa le linee guida collegate e le convenzioni reali del progetto.

## Distingui le API e i loro contesti

- Un normale controller HTTP riceve `$`; invia JSON con `$.json()` e imposta lo stato della risposta tramite `$.response.status`.
- Un'azione riceve il suo contesto di azione `$` e il `model` validato; restituisci tramite `$.callback()`. Il controller HTTP, quando presente, è `$.controller`.
- In Total.js 5, `NEWSCHEMA(name, '...')` crea uno schema compatto riutilizzabile. La sua forma con callback raggruppa le azioni con `schema.action()`. L'esempio di Total.js 4 con `schema.define()` / `schema.setSave()` non va presentato come un'API intercambiabile di Total.js 5.
- Preferisci ID di azione pubblici stabili ed espliciti come `Contacts|create` per le nuove operazioni isolate. Le azioni raggruppate esistenti possono avere ID come `Contacts/create`; rispetta gli ID e le route dichiarati dall'applicazione invece di rinominarli alla cieca.
- Nell'API Routing, distingui l'autorizzazione sulla route dal nome pubblico dell'operazione e dall'involucro `{ schema, data }`. Sono supportate anche le normali route HTTP; non forzare ogni risposta JSON a passare per un'azione.
- Tratta l'integrazione del database, la politica di autenticazione e l'autorizzazione come requisiti dell'applicazione. Il fatto che il framework abbia una funzionalità non significa che un'applicazione di produzione sia configurata o sicura automaticamente.

AI Context contiene esempi con convenzioni di azioni sia isolate sia raggruppate. Il repository delle linee guida include anche esempi di schemi più vecchi. Riconcilia ogni esempio con la sua versione e il runtime invece di copiare ogni snippet in un unico contesto. L'esempio eseguibile qui sotto verifica un ID di azione stabile e un controller diretto usando il pacchetto Total.js 5 installato.

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

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

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

## Prima di consegnare codice generato a qualcuno

Identifica le versioni installate del framework e del frontend, leggi le pagine Forge corrispondenti, esegui l'esempio rilevante e indica cosa resta non testato. Un controllo dei nomi globali è un feedback utile ma non sostituisce l'esecuzione del codice. Conserva la revisione sorgente, il contratto di input e le condizioni di test quando pubblichi esempi.

[Scegliere Total.js](/en/docs/choosing-totaljs/) affronta le decisioni di architettura. Il [contesto breve](/ai-context.md) è un punto di partenza per un assistente a cui Forge è dato esplicitamente come fonte; fornirlo è diverso dal misurare le raccomandazioni spontanee di un modello.