Engenharia de Software

No artigo anterior, comparei endpoints equivalentes em TL++ e WSRESTFUL . Os dois responderam corretamente por HTTP, mas apenas a operação TL++ apareceu no YAML produzido pelo REST-DOC no ambiente do laboratório. Essa não foi a única diferença entre uma exportação concluída e um documento pronto para uso. O arquivo gerado declarava OpenAPI 3.0.3 e incluía as rotas TL++ esperadas. Ao mesmo tempo, continha chaves de path duplicadas e havia sido gravado em Windows-1252. Aberto diretamente como UTF-8, exibia acentos corrompidos; interpretado como YAML, apresentava conflitos estruturais. ...

No primeiro artigo sobre o Media Transcriber , apresentei a ideia de transformar um projeto abandonado em um laboratório prático de Engenharia de Software com Python. A evolução e os conteúdos relacionados também estão reunidos na página do projeto Media Transcriber . Mas a primeira versão não transcreve áudio, não processa vídeo nem oferece uma interface de linha de comando. A v0.1.0 faz algo menos visível e, ao mesmo tempo, essencial: estabelece a fundação sobre a qual as funcionalidades seguintes serão construídas. ...

No Hello World REST em TL++ , publicamos uma operação pequena e verificamos seus metadados no YAML produzido pelo REST-DOC. A etapa seguinte foi implementar uma resposta equivalente em AdvPL, usando WSRESTFUL, e repetir a exportação. Os dois endpoints responderam corretamente às requisições autenticadas. Na documentação gerada, porém, o resultado foi diferente: a operação TL++ apareceu; a operação AdvPL não foi encontrada. Essa comparação ajuda a delimitar o problema que o Protheus OpenAPI pretende investigar. Publicar um serviço e descobrir seus metadados são capacidades que precisam ser verificadas separadamente. ...

Uma validação começa com poucas condições. Depois recebe uma mensagem na tela, uma consulta de parâmetro, uma atualização de registro e uma exceção para determinado processo. Quando alguém precisa mudar a regra, já é difícil saber quais outros comportamentos serão afetados. No artigo AdvPL não precisa ser código legado , discuti como decisões de organização influenciam o custo de manutenção. Aqui, vamos trabalhar uma dessas decisões: separar responsabilidades dentro de uma rotina sem transformar uma alteração pequena em uma reescrita. ...

O primeiro experimento do Protheus OpenAPI começou com uma rota pequena: receber uma requisição GET e devolver um JSON com três campos. Esse recorte permitiu investigar duas perguntas: consigo publicar um endpoint REST em TL++ no ambiente do laboratório? E quais informações desse endpoint aparecem na documentação produzida pelo gerador nativo? No artigo de apresentação , mostrei como essa investigação contribuiu para a proposta do projeto. Agora, vou detalhar o caminho entre o fonte TL++, a resposta HTTP e o artefato gerado pelo REST-DOC. ...

Documentar uma API parece simples enquanto código e documentação nascem juntos. O problema aparece depois. Uma rota muda, um parâmetro é acrescentado, uma resposta ganha outro formato e a especificação continua descrevendo a versão anterior. Aos poucos, o contrato que deveria ajudar consumidores, testes e integrações deixa de representar o serviço publicado. No Protheus, existe ainda uma dificuldade adicional: APIs REST desenvolvidas em momentos diferentes podem usar modelos diferentes. De um lado estão endpoints TL++ baseados em annotations. De outro, serviços AdvPL construídos com WSRESTFUL, WSMETHOD e estruturas relacionadas. ...

Ao iniciar um projeto com determinadas tecnologias, é comum encontrarmos uma ferramenta capaz de criar automaticamente uma estrutura básica de aplicação. No ecossistema Node.js, por exemplo, o NestJS permite iniciar um novo projeto com um único comando: npx @nestjs/cli@latest new minha-api Esse comando cria a estrutura inicial, instala as dependências e entrega uma aplicação pronta para execução. Durante um curso de Docker e Docker Compose, percebi que os exemplos práticos utilizavam justamente essa abordagem. A aplicação em si não era o foco principal da aula. Ela servia apenas como base para estudar imagens, containers, volumes, redes e orquestração com Docker Compose. ...

AdvPL é frequentemente associado a código legado. A associação não surgiu por acaso. Existem customizações Protheus desenvolvidas há muitos anos, funções extensas, dependência de estado compartilhado, regras de negócio misturadas com interface, acesso direto a tabelas e poucos testes automatizados. Também existem projetos sem documentação, sem estratégia clara de versionamento e com alterações realizadas diretamente em código antigo, porque ninguém conhece completamente os efeitos de uma mudança. Mas existe uma distinção importante: ...

Alguns projetos começam com um planejamento detalhado. Outros surgem de uma necessidade simples, recebem algumas linhas de código e acabam esquecidos em algum repositório. O Media Transcriber se encaixa melhor no segundo caso. Há algum tempo, criei um pequeno projeto chamado mp4-audio-transcriber. A ideia era relativamente simples: receber um arquivo MP4, extrair seu áudio e gerar uma transcrição utilizando Python e Whisper. O projeto chegou a ganhar um repositório no GitHub e uma estrutura inicial, mas nunca evoluiu de fato. Ficou basicamente como uma prova de conceito de uma ideia que poderia ser desenvolvida algum dia. ...

Trabalhar com mais de uma conta no GitHub é algo bastante comum. Por exemplo: uma conta pessoal uma conta corporativa contas usadas em organizações específicas Sem uma configuração adequada, o Git pode acabar utilizando a chave SSH ou o usuário errado, gerando erros de autenticação ou registrando commits com o e-mail incorreto. Este guia mostra como configurar múltiplas identidades SSH para acessar diferentes contas no GitHub utilizando: chaves SSH separadas aliases no arquivo ~/.ssh/config configurações específicas em cada repositório O problema Quando utilizamos SSH para acessar o GitHub, o cliente SSH normalmente usa uma única chave padrão localizada em: ...