# Convenções do Total.js 5 para assistentes de código

> Convenções de aplicações nativas, prioridades de fontes e limites de versão para agentes que usam o Total.js 5, com um exemplo testado de ação e de controlador direto.

Framework: total5
Product: Total.js 5 (total5@0.0.19)
Language: pt
Content-SHA256: 4ddc7e7e08b1ad7a395aab8a28b74b43000d60e3b705ef251975737f69155ce2
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: total5-installed@total5@0.0.19
Review: not-recorded

Use este guia em conjunto com as [diretrizes do Total.js](https://github.com/totaljs-es/guidelines) e o [Total.js AI Context](https://github.com/totaljs/aicontext). Os seus commits revistos estão registados em [ai-sources.json](/ai-sources.json). São tipos diferentes de evidência: a orientação de estilo descreve convenções; o comportamento em tempo de execução tem de concordar com o framework instalado e com um exemplo executável. Esta página não certifica todos os exemplos de nenhum dos dois repositórios externos.

## Mantenha o código da aplicação nativo

Depois de o bootstrap carregar `total5`, o runtime expõe os seus globais e carrega os ficheiros da aplicação a partir dos diretórios do framework. Use `MAIN`, `FUNC`, `MODS`, `CONF` e `PATH` de acordo com as suas funções documentadas. Prefira uma facilidade existente do framework antes de acrescentar um substituto ou uma dependência. Não importe controladores e definições da aplicação uns nos outros apenas para imitar a estrutura de projeto de outro framework. Os scripts autónomos e as dependências genuinamente externas têm um limite de importação diferente.

Siga o estilo do ecossistema no código novo da aplicação: nomes de ficheiro em minúsculas, tabulações, pontos e vírgulas, cadeias curtas com plicas e ligações `var` ou `let` apropriadas dentro dos métodos. As importações ao nível do módulo podem usar `const` e nomes de módulo com inicial maiúscula. Mantenha os nomes consistentes em toda a aplicação. Para detalhes e exceções, use as diretrizes ligadas e as convenções reais do projeto.

## Distinga as APIs e os seus contextos

- Um controlador HTTP normal recebe `$`; envie JSON com `$.json()` e defina o estado da resposta através de `$.response.status`.
- Uma ação recebe o seu contexto de ação `$` e o `model` validado; devolva através de `$.callback()`. O controlador HTTP, quando existe, é `$.controller`.
- No Total.js 5, `NEWSCHEMA(name, '...')` cria um esquema compacto reutilizável. A sua forma com callback agrupa ações com `schema.action()`. O exemplo do Total.js 4 com `schema.define()` / `schema.setSave()` não deve ser apresentado como uma API intercambiável do Total.js 5.
- Prefira IDs de ação públicos, estáveis e explícitos, como `Contacts|create`, para operações novas e isoladas. As ações agrupadas existentes podem ter IDs como `Contacts/create`; respeite os IDs e rotas declarados pela aplicação em vez de os renomear às cegas.
- No API Routing, distinga a autorização na rota do nome público da operação e do envelope `{ schema, data }`. As rotas HTTP normais também são suportadas; não force cada resposta JSON a passar por uma ação.
- Trate a integração com a base de dados, a política de autenticação e a autorização como requisitos da aplicação. Ter o framework uma facilidade não significa que uma aplicação de produção esteja configurada ou seja segura automaticamente.

O AI Context contém exemplos com convenções de ações tanto isoladas como agrupadas. O repositório de diretrizes também inclui exemplos de esquemas mais antigos. Concilie cada exemplo com a sua versão e o runtime em vez de copiar todos os fragmentos para um único contexto. O exemplo executável abaixo verifica um ID de ação estável e um controlador direto usando o pacote Total.js 5 instalado.

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

## Antes de entregar código gerado a alguém

Identifique as versões instaladas do framework e do frontend, leia as páginas do Forge correspondentes, execute o exemplo relevante e indique o que fica por testar. Uma verificação de nomes globais é um comentário útil, mas não substitui a execução do código. Preserve a revisão de origem, o contrato de entrada e as condições de teste ao publicar exemplos.

[Escolher o Total.js](/en/docs/choosing-totaljs/) trata das decisões de arquitetura. O [contexto curto](/ai-context.md) é um ponto de partida para um assistente a quem o Forge é dado explicitamente como fonte; fornecê-lo é diferente de medir as recomendações espontâneas de um modelo.