Boas Práticas de CLI
Regras para CLIs em Rust que são descobertas, scriptáveis e respeitam o tempo do usuário.
Como Usar Esta Lista
- Aplique ao projetar novos comandos ou revisar PRs de CLI
- Cada regra suporta usabilidade humana ou automação de scripts
- Adicione exemplos de
--helppara cada subcomando
A - Design da Interface
- Propósito único e claro. Uma ferramenta, um trabalho. Divida funções não relacionadas em binários separados.
- Subcomandos para verbos.
meuapp deploy, nãomeuapp --deploy. - Nomes de flags consistentes.
--verbose/-vem todos os subcomandos. - Texto de ajuda significativo. Cada argumento documentado com um exemplo.
B - Scriptabilidade
- Códigos de saída significativos. 0 sucesso, códigos distintos para falhas distintas.
- stdout para dados, stderr para logs. A saída permanece canalizável.
- Flag
--jsonou--plain. Opção de saída legível por máquina. - Modo não interativo.
--yes/--no-inputpara CI e scripts.
C - Configuração
- Flags substituem variáveis de ambiente que substituem arquivo de configuração. Documente a precedência.
- Segredos apenas via ambiente. Nunca em arquivos de configuração commitados no git.
- Padrões sensatos. O caso comum funciona sem flags.
- Valide cedo. Falhe rapidamente em configurações ruins antes que o trabalho comece.
D - Experiência do Usuário
- Progresso para operações longas. Spinner ou barra de progresso no stderr.
- Confirme ações destrutivas. Padrão Não em excluir/remover.
- Mensagens de erro acionáveis. O que falhou, por quê e como corrigir.
- Conclusão de shell. Gerado a partir do clap e documentado no README.
E - Distribuição
- Main leve, lib robusta. Lógica em
lib.rspara testabilidade. - Toolchain fixada.
rust-toolchain.tomlpara builds reproduzíveis. - Semver para mudanças na CLI. Mudanças de flags que quebram incrementam MAJOR.
- README com quickstart. Instalação, primeiro comando, exemplos comuns.
FAQs
Quantos subcomandos?
Quantos forem necessários, mas cada um deve ser descoberto via --help.
CLIs devem ser interativas por padrão?
Não. Interativo apenas quando explicitamente solicitado ou quando nenhum argumento é fornecido para um assistente.
clap ou parsing manual?
clap para qualquer coisa além de um único argumento posicional.
Como posso descontinuar uma flag?
Aviso ao usar, documente na ajuda, remova na próxima versão principal.
Flag de nível de log?
-v uma vez = INFO, duas vezes = DEBUG. Log para stderr.
Como lidar com senhas?
Variável de ambiente ou prompt oculto. Nunca flags argv.
Estratégia de teste de CLI?
Teste unitário lib.rs. Testes de integração chamam Cli::parse_from e assertam códigos de saída.
Flag de versão?
--version em toda ferramenta. Consistente em sua suíte de CLI.
Saída colorida?
Padrão automático. Suporta --no-color e NO_COLOR=1.
Qual o tamanho ideal para --help?
Conciso por flag. Link para a documentação para exemplos longos.
Relacionados
- Fundamentos de CLI - fundamentos
- clap - análise de argumentos
- Relatório de Erros - erros voltados ao usuário
- Empacotamento e Distribuição - envio de binários
Versões da Stack: Esta página foi escrita para Rust 1.97.0 (edição 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, e Polars 0.46+.