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

Total.js 5 · total5@0.0.19 aiconventionsguidelinescontextnativeactions Executada com o Total.js 5

Use este guia em conjunto com as diretrizes do Total.js e o Total.js AI Context. Os seus commits revistos estão registados em 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.

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

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 trata das decisões de arquitetura. O contexto curto é 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.