Forem: Danilo Itagyba

Codex CLI no dia a dia: como usar IA no terminal com boas práticas

Danilo Itagyba — Mon, 13 Apr 2026 17:30:40 +0000

O Codex CLI mudou a forma como escrevemos código: ao invés de digitar linha por linha, passamos a orquestrar tarefas usando IA diretamente no terminal.

Mas tem um detalhe importante:

👉 Usar IA sem boas práticas pode gerar mais problemas do que soluções.

Neste artigo você vai ver:

Como usar o Codex CLI no dia a dia
Boas práticas reais (baseadas no guia oficial)
E principalmente: por que testes são ainda mais importantes com IA

🚀 O que é o Codex CLI?

O Codex CLI é um agente de desenvolvimento que roda no terminal e permite:

Gerar código com contexto do projeto
Refatorar código existente
Criar testes automaticamente
Automatizar tarefas (CI/CD, scripts, etc.)

Ele funciona como um pair programmer que executa código por você.

⚙️ Setup básico

npm install -g @openai/codex

export OPENAI_API_KEY="your-api-key"

Uso:

codex "Create a REST API with validation and pagination"

🧠 Como pensar ao usar Codex

Mude sua mentalidade:

❌ Antes: eu escrevo código
✅ Agora: eu descrevo o problema e reviso a solução

Fluxo ideal:

Você define o problema
Codex gera a solução
Você revisa
Você valida (testes!)

🧩 Boas práticas essenciais

1. Dê contexto (isso muda tudo)

❌ Ruim:

codex "fix bug"

✅ Bom:

codex "Fix null reference in UserService when email is missing. Add validation and unit tests."

2. Quebre tarefas grandes

❌ Evite:

codex "Build entire system"

✅ Prefira:

codex "Create authentication service"
codex "Add JWT support"
codex "Write unit tests"

3. Planeje antes de executar

codex "Plan how to migrate this monolith to microservices"

Depois:

codex "Implement step 1 of the plan"

4. Use AGENTS.md

# AGENTS.md
- Use clean architecture
- Prefer repository pattern
- Use xUnit for tests

👉 Isso padroniza o comportamento do Codex no projeto

5. Use intenção, não sintaxe

❌

codex "write a for loop in C#"

✅

codex "Iterate over active users and filter inactive ones"

6. Trabalhe em ciclos curtos

Pequenas mudanças = menos bugs + mais controle

🧪 A parte mais importante: TESTES

Se você só lembrar de uma coisa desse artigo, que seja isso:

❗ Código gerado por IA sem testes é um risco real

A IA gera código que:

Parece correto
Compila
Mas pode estar errado

🧠 Regra de ouro

👉 Se não tem teste, não existe

🧩 Tipos de testes que você DEVE usar

✔️ Unit Test

[Fact]
public void Should_Return_Error_When_Email_Is_Invalid()
{
    var service = new UserService();

    var result = service.CreateUser("invalid-email");

    Assert.False(result.Success);
}

✔️ Integration Test

[Fact]
public async Task Should_Create_User_In_Database()
{
    var client = _factory.CreateClient();

    var response = await client.PostAsync("/users", content);

    Assert.Equal(HttpStatusCode.Created, response.StatusCode);
}

✔️ Regression Test

Sempre rode após usar IA:

dotnet test

⚠️ O que acontece se você NÃO testar

Bugs silenciosos em produção
Regressões inesperadas
Falhas de segurança
Performance ruim

👉 Quanto mais IA você usa, mais testes você precisa

⚙️ Boas práticas com testes + Codex

✔️ Gere testes junto com código

codex "Create order service with unit tests"

✔️ Crie testes antes de refatorar

codex "Write unit tests for this class before refactoring"

👉 Técnica: test safety net

✔️ Aumente cobertura automaticamente

codex "Increase test coverage and include edge cases"

✔️ Automatize no CI/CD

name: Test

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run tests
        run: dotnet test

🧱 Exemplos reais de uso

Criar endpoint

codex "Create a .NET API endpoint with validation and error handling"

Otimizar SQL

codex "Optimize this SQL query and suggest indexes"

Refatorar código

codex "Refactor this service to use dependency injection"

⚠️ Erros comuns

Erro	Problema
Prompt genérico	Resultado ruim
Tarefa grande demais	Código inconsistente
Sem revisão	Bugs
Sem contexto	IA “chuta”
Sem testes	💥 produção

🏁 Conclusão

O Codex CLI muda completamente o jogo:

Você deixa de escrever código
E passa a orquestrar código

Mas o sucesso depende disso:

👉 Contexto + Iteração + Testes + Revisão

📌 TL;DR

Dê contexto claro
Trabalhe em etapas
Planeje tarefas grandes
Use AGENTS.md
Teste tudo que a IA gerar
Revise sempre

Blindando Aplicações no .NET 10: Um Guia Completo sobre Polly e Resiliência

Danilo Itagyba — Mon, 09 Feb 2026 14:29:15 +0000

Resiliência à Prova de Falhas no .NET 10 com Polly

No desenvolvimento de software moderno, especialmente em arquiteturas de microsserviços e nuvem, a estabilidade não é definida pela ausência de falhas, mas pela capacidade do sistema de resistir e se recuperar delas.

Com a chegada do .NET 10 (e seguindo a evolução desde o .NET 8), a forma de implementar resiliência mudou drasticamente. As antigas Policies síncronas e pesadas deram lugar aos Resilience Pipelines: leves, performáticos e nativos para código assíncrono.

Este artigo explora como utilizar o poder do Polly em conjunto com o Microsoft.Extensions.Http.Resilience para criar aplicações robustas.

1. O Novo Paradigma: Resilience Pipelines

Diferente das versões anteriores do Polly (v7 e inferiores), a nova arquitetura (v8+) foca em:

Zero-Allocation (ou quase): Redução drástica no consumo de memória.
Pipeline Pattern: Estratégias são encadeadas de forma lógica e fluente.
Integração Nativa: Telemetria, Logging e Injeção de Dependência já "saem da caixa".

Instalação

Para projetos .NET modernos, você deve instalar os seguintes pacotes via NuGet:

dotnet add package Polly.Core
dotnet add package Microsoft.Extensions.Http.Resilience

Nota: O pacote Microsoft.Extensions.Http.Resilience é a recomendação oficial da Microsoft para aplicações web e APIs.

2. Estratégias Fundamentais de Resiliência

Abaixo, detalhamos as principais estratégias (strategies) utilizando a sintaxe moderna do ResiliencePipelineBuilder.

A. Retry (Tentativa) com Jitter

A estratégia mais básica. Se falhar, tente novamente. No entanto, o Retry simples é perigoso (pode causar efeito "Thundering Herd"). A solução é o Backoff Exponencial com Jitter (ruído aleatório), que agora é o padrão no Polly moderno.

using Polly;
using Polly.Retry;

ResiliencePipeline pipeline = new ResiliencePipelineBuilder()
    .AddRetry(new RetryStrategyOptions
    {
        // Trata exceções de rede e códigos 5xx
        ShouldHandle = new PredicateBuilder().Handle<HttpRequestException>(),
        MaxRetryAttempts = 3,
        Delay = TimeSpan.FromSeconds(2),
        BackoffType = DelayBackoffType.Exponential, // Inclui Jitter automaticamente
        OnRetry = static args =>
        {
            Console.WriteLine($"Tentativa {args.AttemptNumber} falhou. Retentando...");
            return ValueTask.CompletedTask;
        }
    })
    .Build();

B. Circuit Breaker (Disjuntor)

Protege o sistema de destino. Se um serviço está fora do ar, continuar tentando só piora a situação. O Circuit Breaker "abre o circuito" após um número de falhas, falhando imediatamente novas requisições para dar tempo ao serviço de se recuperar.

var circuitOptions = new CircuitBreakerStrategyOptions
{
    FailureRatio = 0.5,       // Se 50% das requisições falharem...
    SamplingDuration = TimeSpan.FromSeconds(30), // ...nos últimos 30s...
    MinimumThroughput = 7,    // ...com no mínimo 7 requisições...
    BreakDuration = TimeSpan.FromSeconds(60)     // ...abra o circuito por 1 min.
};

var pipeline = new ResiliencePipelineBuilder()
    .AddCircuitBreaker(circuitOptions)
    .Build();

C. Fallback (Plano de Contingência)

Quando tudo falha (Retry esgotado, Circuito aberto), o Fallback define o que fazer para não estourar erro na cara do usuário. Pode ser retornar um dado do cache ou um valor padrão.

var pipeline = new ResiliencePipelineBuilder()
    .AddFallback(new FallbackStrategyOptions<UserDto>
    {
        FallbackAction = _ => Outcome.FromResult(new UserDto { Name = "Usuário Padrão" }),
        OnFallback = static _ => 
        {
            Console.WriteLine("Fallback acionado! Retornando dados provisórios.");
            return ValueTask.CompletedTask;
        }
    })
    .Build();

D. Hedging (Especulação)

Útil para baixa latência. O Hedging dispara requisições paralelas (ou com pequeno atraso). A primeira que retornar com sucesso é usada; as outras são canceladas.

Exemplo: Você chama uma API que às vezes demora 5s, mas normalmente leva 100ms. O Hedging dispara uma segunda chamada se a primeira demorar mais que 200ms.

var pipeline = new ResiliencePipelineBuilder()
    .AddHedging(new HedgingStrategyOptions
    {
        MaxHedgedAttempts = 2,
        Delay = TimeSpan.FromMilliseconds(500), // Dispara 2ª tentativa se 1ª demorar 500ms
    })
    .Build();

3. A Implementação "Gold Standard" no .NET 10

Em aplicações reais (.NET Core API, Worker Services, Blazor), você raramente constrói pipelines manualmente. Você utiliza a Injeção de Dependência para decorar o HttpClient.

A Microsoft introduziu o AddStandardResilienceHandler, que aplica uma combinação pré-configurada e otimizada de:

Rate Limiter
Total Timeout
Retry
Circuit Breaker
Attempt Timeout

Configuração no `Program.cs`

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var builder = Host.CreateApplicationBuilder(args);

// 1. Registro do HttpClient nomeado
builder.Services.AddHttpClient("CatalogoApi", client =>
{
    client.BaseAddress = new Uri("https://api.catalogo.com");
    client.Timeout = TimeSpan.FromSeconds(30); // Timeout do socket
})
// 2. Adicionando a Resiliência Padrão
.AddStandardResilienceHandler(options => 
{
    // Podemos customizar os padrões se necessário
    options.Retry.MaxRetryAttempts = 5;
    options.CircuitBreaker.BreakDuration = TimeSpan.FromSeconds(15);
    options.TotalRequestTimeout.Timeout = TimeSpan.FromSeconds(60);
});

var app = builder.Build();

Consumindo o Serviço Resiliente

Sua classe de serviço não precisa saber que o Polly existe. A resiliência é transparente.

public class CatalogoService(IHttpClientFactory factory, ILogger<CatalogoService> logger)
{
    private readonly HttpClient _client = factory.CreateClient("CatalogoApi");

    public async Task<Produto?> GetProdutoAsync(int id, CancellationToken ct)
    {
        // Se a rede falhar, o Polly intercepta, tenta de novo, 
        // ou abre o circuito automaticamente aqui.
        try 
        {
            return await _client.GetFromJsonAsync<Produto>($"/produtos/{id}", ct);
        }
        catch (Exception ex)
        {
            // Logar apenas se todas as estratégias de resiliência falharem
            logger.LogError(ex, "Não foi possível obter o produto após múltiplas tentativas.");
            throw;
        }
    }
}

4. Cenários Avançados: Pipeline Registry

Às vezes, você precisa reutilizar a mesma estratégia de resiliência em vários lugares que não são necessariamente chamadas HTTP (ex: acesso a arquivos, conexões Redis). Para isso, usamos o ResiliencePipelineProvider.

Registro

builder.Services.AddResiliencePipeline("meu-pipeline-banco", builder =>
{
    builder
        .AddRetry(new RetryStrategyOptions { MaxRetryAttempts = 3 })
        .AddTimeout(TimeSpan.FromSeconds(5));
});

Uso Injetado

public class BancoService(ResiliencePipelineProvider<string> pipelineProvider)
{
    public async Task SalvarDadosAsync(string dados, CancellationToken ct)
    {
        // Recupera o pipeline pelo nome
        var pipeline = pipelineProvider.GetPipeline("meu-pipeline-banco");

        // Executa qualquer código arbitrário com resiliência
        await pipeline.ExecuteAsync(async token => 
        {
            await _database.ExecuteCommandAsync(dados, token);
        }, ct);
    }
}

5. Checklist de Melhores Práticas

Idempotência é Chave: Nunca use Retry em métodos que não sejam idempotentes (ex: POST para criar pedido) a menos que sua API suporte verificação de duplicidade. Se a primeira requisição criou o pedido mas a resposta falhou na rede, o Retry pode criar um pedido duplicado.
Timeouts em Camadas:
Attempt Timeout: Tempo para cada tentativa individual (curto).
Total Timeout: Tempo máximo para todo o processo (longo).
Socket Timeout: Configuração do HttpClient.
Circuit Breaker Distribuído: Lembre-se que o Circuit Breaker é local (na memória da instância). Se você tem 10 réplicas da sua API no Kubernetes, cada uma terá seu próprio estado de circuito.
Não trate tudo: Não use Retry para erros de negócio (400 Bad Request, 403 Forbidden). Resiliência é para falhas transitórias (503 Service Unavailable, 408 Request Timeout, falhas de rede).

Conclusão

No .NET 10, a biblioteca Polly deixou de ser apenas um utilitário de terceiros para se tornar parte integrante da stack de rede da Microsoft. Ao utilizar Microsoft.Extensions.Http.Resilience e os novos Pipelines, você garante que sua aplicação seja capaz de suportar as instabilidades inerentes à nuvem com performance máxima e código limpo.

🚀 Node.js Best Practices

Danilo Itagyba — Fri, 05 Dec 2025 14:27:43 +0000

Node.js Best Practices

Comprehensive Node.js development guidelines
Based on goldbergyoni/nodebestpractices

🎯 102 Best Practices | 📦 Node.js 22+ |

Project Structure
Framework Selection
TypeScript Usage
Error Handling
Code Style and Patterns
Testing and Quality
Production Best Practices
Security Best Practices
Docker Best Practices
Code Examples
Summary Checklist

Project Structure

📂 Component-Based Architecture

Structure your application by business components (bounded contexts) for better modularity and maintainability.

my-system/
├── apps/                    # Business components
│   ├── orders/
│   ├── users/
│   ├── payments/
└── libraries/               # Shared utilities
    ├── logger/
    └── authenticator/

Benefits:

✅ Reduced mental overload
✅ Smaller, granular changes
✅ Faster development cycles
✅ Clear modularity borders

Anti-pattern:

❌ Mixing artifacts from different modules
❌ Tightly-coupled 'spaghetti' architecture
❌ Global dependencies everywhere

Best Practices:

✅ Each module has its own package.json
✅ Use package.json.main or package.json.exports for public API
✅ Hide internal implementation details
✅ Support Monorepo or multi-repo approaches

⚙️ Configuration Management

Implement secure, flexible configuration from day one.

Requirements:

✅ Read from files AND environment variables
✅ Keep secrets outside committed code
✅ Hierarchical structure for easy navigation
✅ Type support and validation
✅ Default values for all keys

Recommended Libraries:

// Example with convict
const convict = require('convict');

const config = convict({
  env: {
    format: ['production', 'development', 'test'],
    default: 'development',
    env: 'NODE_ENV'
  },
  port: {
    format: 'port',
    default: 3000,
    env: 'PORT'
  }
});

config.validate({ allowed: 'strict' });

Framework Selection

Recommended Frameworks (2024)

Nest.js - For OOP teams and large-scale apps
Fastify - For microservices with simple Node.js mechanics
Express - For simplicity and wide ecosystem
Koa - For minimalist, modern middleware approach

Framework Considerations

Evaluate based on team size, project scale, and architecture
Consider TypeScript support and plugin ecosystem
Assess performance requirements vs development speed

TypeScript Usage

Use TypeScript Sparingly and Thoughtfully

Define variables and function return types
Avoid over-engineering with advanced features
Use ~50 keywords thoughtfully, not excessively
Utilize advanced features only when truly needed
Remember: Types catch ~20% of bugs; tests catch the rest
Balance type safety with code simplicity

Error Handling

Async Error Handling

Use async-await or promises exclusively
Avoid callback-style error handling (callback hell)
Enable better error handling with try-catch blocks

Error Object Standards

Always extend the built-in Error object
Add useful properties: name, code, isCatastrophic
Use ESLint rule: no-throw-literal
For TypeScript: @typescript-eslint/no-throw-literal

Error Classification

Operational Errors: Known, expected errors (invalid input)
- Handle gracefully, log, and continue
Catastrophic Errors: Unknown programmer errors
- Log, alert, and restart process gracefully

Centralized Error Handling

Create dedicated error handler object
Don't handle errors within middleware
Encapsulate: logging, crash decisions, monitoring
All entry points should use the same handler

Error Documentation

Document API errors using OpenAPI or GraphQL
Help API callers handle errors properly
Prevent unexpected crashes in client applications

Process Exit Strategy

Exit gracefully on unknown errors
Let runtime (Docker, Kubernetes) restart the process
Log observable errors before shutdown
Close connections properly

Logging Best Practices

Use mature logger: Pino or Winston (avoid console.log)
Support log levels, pretty printing, and coloring
Write logs to stdout (let infrastructure handle routing)
Attach custom properties with minimal serialization penalty

Testing Error Flows

Test both positive and error scenarios
Simulate uncaught exceptions
Verify error handler behavior
Test error recovery mechanisms

Monitoring

Use APM products to discover errors automatically
Monitor performance and downtime proactively
Gauge application health in real-time

Promise Management

Catch unhandled promise rejections
Register to process.unhandledRejection event
Always await promises before returning for full stacktrace
Use return await pattern in async functions

Input Validation

Fail fast: validate arguments immediately
Use validation libraries: ajv, zod, typebox
Validate at API boundaries
Assert API input to prevent nasty bugs

Event Emitter Error Handling

Subscribe to 'error' events on event emitters
Handle stream errors explicitly
For EventTargets, use global process error handling
Initialize emitters with {captureRejections: true} for async handlers

Code Style and Patterns

ESLint Configuration

Use ESLint as the standard linter
Combine with Prettier for code formatting
Catch errors and anti-patterns early

Node.js-Specific Linting

Use plugins:
- eslint-plugin-node
- eslint-plugin-security
- eslint-plugin-mocha / eslint-plugin-jest
- eslint-plugin-require
Detect Node.js-specific anti-patterns

Code Formatting Rules

Opening braces on same line as statement
Proper statement separation (use semicolons or understand ASI)
Use ESLint semi rule
Use no-unexpected-multiline rule

Naming Conventions

lowerCamelCase: variables, constants, functions
UpperCamelCase: classes
UPPER_SNAKE_CASE: global/static variables
Name all functions (avoid anonymous functions)
Use descriptive but concise names

Variable Declaration

Prefer const over let
Avoid var completely (ES6+)
const prevents accidental reassignment
let for block-scoped variables that need reassignment

Module Management

Require modules at file beginning
Import before any function definitions
Avoid requires inside functions (except lazy loading)

Module Entry Points

Set explicit entry point (index.js or package.json.main)
Use package.json.exports for ESM
Hide internal structure from clients

Comparison Operators

Use strict equality === over ==
Avoid type coercion surprises

Async Patterns

Use async-await as primary pattern
Avoid callbacks (callback hell)
Promises for library compatibility
Arrow functions for compact code

Side Effects

Avoid effects outside of functions
No DB/network calls at module load time
Use factory or revealing module patterns for initialization
Keep code testable and mockable

Testing and Quality

Test Coverage Requirements

Write API (component) tests at minimum
Component tests provide more coverage than unit tests
Use tools like Postman for API testing

Test Naming Convention (3 Parts)

What is being tested (unit under test)
Under what circumstances
What is the expected result
Example: "ProductService - when no price provided - should return validation error"

Test Structure (AAA Pattern)

Arrange: Setup test data and conditions
Act: Execute the unit under test
Assert: Verify expected outcome

Environment Consistency

Use Node version management: nvm or Volta
Specify Node version in project files
Replicate to CI and production runtime
Prevent version drift across environments

Test Data Management

Avoid global test fixtures and seeds
Add data per-test (test isolation)
Each test manages its own database state
Prevent test coupling and interference

Test Organization

Tag tests by category: #cold, #api, #sanity, #integration
Run subsets based on context (commit, PR, deploy)
Example: mocha --grep 'sanity'

Code Coverage

Use Istanbul/NYC for coverage reports
Identify untested code paths
Set coverage thresholds in CI
Fail builds on coverage decrease

E2E Testing

Use production-like environment
Leverage docker-compose for services
Keep DBs synchronized across environments

Static Analysis

Use SonarQube or Code Climate
Detect code smells and complexity
Track code quality over time
Integrate into CI pipeline

External Service Mocking

Mock external HTTP services: nock or Mock-Server
Simulate errors, delays, timeouts
Test non-happy path flows
Avoid hitting real external services in tests

Middleware Testing

Test middlewares in isolation
Stub {req, res, next} objects
Verify middleware behavior independently

Port Management

Specify port in production
Randomize port in testing (port 0)
Prevent port collisions in parallel tests

Test Five Outcomes

Response validation
State changes (DB, memory)
Outgoing API calls
Message queue events
Observability (logs, metrics)

Production Best Practices

Monitoring Strategy

Monitor uptime, metrics, and user-facing symptoms
Track Node.js-specific metrics (event loop lag)
Use distributed tracing with Open Telemetry
Implement comprehensive logging
4 layers: uptime, metrics, distributed flows, logs

Smart Logging

Plan logging platform from day 1
Log to stdout, let environment handle routing
Include transaction IDs (correlation IDs)
Use AsyncLocalStorage for context propagation
Enable log aggregation and analysis

Reverse Proxy Delegation

Delegate CPU-intensive tasks (gzip, SSL)
Use nginx, HAproxy, or cloud services
Keep Node thread focused on application logic

Dependency Management

Lock dependencies with package-lock.json
Commit lockfiles to version control
Use npm ci for consistent installs
Ensure identical code across environments

Process Management

Use platform-native solutions (Kubernetes, systemd)
Avoid custom process managers in modern platforms
Let infrastructure handle restarts and health checks
Ensure process uptime with proper tools

CPU Utilization

Replicate Node process for all CPU cores
Use container orchestration for scaling
Don't rely on Node cluster module alone
Verify all cores are utilized

Maintenance Endpoints

Expose system information securely
Provide memory usage, health checks
Enable diagnostic operations
Keep separate from public API

APM Integration

Add Application Performance Monitoring
Auto-discover slow transactions
Identify performance bottlenecks
Provide developer context for errors

Production-Ready Code

Plan for production from day 1
Consider maintainability early
Design for operations and debugging
Build with monitoring in mind

Memory Management

Watch Node process memory usage
V8 has soft limits (1.4GB default)
Monitor for memory leaks
Alert on unusual memory growth

Frontend Asset Management

Serve frontend via nginx, S3, or CDN
Don't serve static files through Node
Exception: server-side rendering
Keep Node focused on dynamic content

Stateless Architecture

Store data in external data stores
Avoid in-process state (sessions, cache, files)
Enable easy horizontal scaling
Support instance reapp-ing

Vulnerability Detection

Use automated security scanning tools
Monitor dependencies continuously
Patch vulnerabilities immediately
Scan locally and in CI/CD

Transaction ID Logging

Assign UUID to each request
Use AsyncLocalStorage for context
Include in all log statements
Enable request flow tracing

Environment Configuration

Set NODE_ENV=production
Enable production optimizations
Libraries use environment for behavior
Affects performance significantly

Deployment Strategy

Automate deployments completely
Use Docker with CI/CD tools
Implement zero-downtime deployments
Make deployments atomic and reversible

Node.js Version

Use LTS (Long Term Support) releases
Receive critical bug fixes and security updates
Ensure module compatibility
Plan upgrade paths

Log Routing

Log to stdout exclusively
Let execution environment handle destinations
Don't hard-code log destinations
Support flexible log aggregation

Security Best Practices

Linter Security Rules

Use eslint-plugin-security
Catch vulnerabilities during development
Prevent eval usage and code injection
Detect insecure patterns early

Rate Limiting

Implement request limiting
Prevent DOS attacks
Use cloud load balancers, nginx, or rate-limiter-flexible
Protect against abuse

Secret Management

Never store plain-text secrets in code
Use Vault, Kubernetes Secrets, or environment variables
Encrypt secrets in source control
Implement pre-commit hooks
Rotate keys regularly

Query Injection Prevention

Use ORM/ODM libraries (Sequelize, Knex, Mongoose)
Leverage parameterized queries
Validate user input for expected types
Never concatenate user input into queries

Security Checklist

Enable HTTPS everywhere
Use helmet.js for HTTP headers
Implement CSRF protection
Sanitize user input
Use secure session cookies
Implement proper authentication
Apply principle of least privilege

Dependency Security

Scan for vulnerable dependencies
Use npm audit or Snyk
Update dependencies regularly
Monitor security advisories

Input Validation

Validate all user input
Use validation libraries (joi, yup, zod)
Implement allow-lists over deny-lists
Validate data types and formats

Authentication Best Practices

Use bcrypt or scrypt for passwords
Implement 2FA where possible
Use secure JWT practices
Rotate secrets regularly

Data Protection

Escape HTML, JS, and CSS output
Validate JSON schemas
Implement proper access controls
Encrypt sensitive data at rest

Secure Headers

Use helmet.js middleware
Set Content-Security-Policy
Enable HSTS
Disable X-Powered-By

Error Information Leakage

Hide error details from clients
Log detailed errors server-side
Return generic error messages
Don't expose stack traces in production

Child Process Safety

Avoid child_exec with user input
Sanitize all arguments
Use execFile over exec
Implement timeouts

RegEx DOS Prevention

Validate regex patterns
Set timeouts for regex operations
Test regex with long inputs
Use safe-regex library

Session Security

Use secure session configuration
Set httpOnly and secure flags
Implement session timeouts
Rotate session IDs

NPM Security

Enable 2FA for npm account
Audit packages before publishing
Use .npmignore to prevent secret leaks
Review dependencies regularly

Module Loading Security

Avoid dynamic requires with user input
Use static imports when possible
Validate module paths
Implement sandbox for untrusted code

Redirect Safety

Validate redirect URLs
Use allow-list for redirects
Prevent open redirect vulnerabilities

Built-in Module Usage

Import built-in modules with 'node:' protocol
Example: import fs from 'node:fs'
Makes built-in modules explicit
Prevents shadowing attacks

Docker Best Practices

Multi-Stage Builds

Use multi-stage builds for smaller images
Separate build and runtime dependencies
Reduce attack surface
Improve security and performance

Process Bootstrap

Use node command directly, avoid npm start
Faster startup, proper signal handling
No unnecessary npm process overhead

Container Runtime

Let orchestrator handle replication
Use Kubernetes/Docker Swarm for uptime
Don't run process manager inside container

Secret Protection

Use .dockerignore effectively
Never commit secrets to images
Use Docker secrets or environment variables
Clean secrets after build

Dependency Cleanup

Run npm ci --production in final stage
Remove devDependencies
Clean npm cache
Minimize image size

Graceful Shutdown

Handle SIGTERM properly
Implement health checks
Clean up connections on shutdown
Drain requests before exit

Memory Limits

Set Docker memory limits
Configure V8 max-old-space-size
Prevent OOM kills
Match container and V8 limits

Image Caching

Order Dockerfile for optimal caching
Copy package.json before source code
Leverage layer caching
Minimize cache invalidation

Image Tagging

Use explicit image references
Avoid 'latest' tag in production
Pin dependencies to versions
Ensure reproducible builds

Base Image Selection

Prefer Alpine or slim variants
Minimize base image size
Reduce vulnerabilities
Use official Node.js images

Build Secrets

Use BuildKit secret mounts
Never use ARG for secrets
Secrets don't persist in layers
Clean build-time secrets

Image Scanning

Scan for vulnerabilities (Snyk, Trivy)
Check multiple layers
Integrate into CI/CD
Fix critical vulnerabilities

Cache Management

Clean node_modules cache
Remove unnecessary files
Use .dockerignore
Minimize layer size

Dockerfile Linting

Use hadolint for linting
Follow best practices
Catch common mistakes
Integrate into CI

Code Examples

Proper Error Handling

// Do: Use AppError extending Error
class AppError extends Error {
  constructor(name, message, httpCode, isOperational = true) {
    super(message);
    this.name = name;
    this.httpCode = httpCode;
    this.isOperational = isOperational;
    Error.captureStackTrace(this);
  }
}

// Usage
throw new AppError('ValidationError', 'Invalid email', 400);

Async-Await Pattern

// Do: Use async-await
async function getUser(id) {
  try {
    const user = await userRepository.findById(id);
    return user;
  } catch (error) {
    logger.error('Failed to get user', { id, error });
    throw new AppError('UserNotFound', 'User not found', 404);
  }
}

// Avoid: Callbacks
function getUser(id, callback) {
  userRepository.findById(id, (err, user) => {
    if (err) return callback(err);
    callback(null, user);
  });
}

Configuration Management

// Do: Use convict or similar
const convict = require('convict');

const config = convict({
  env: {
    format: ['production', 'development', 'test'],
    default: 'development',
    env: 'NODE_ENV'
  },
  port: {
    format: 'port',
    default: 3000,
    env: 'PORT'
  },
  db: {
    host: {
      format: String,
      default: 'localhost',
      env: 'DB_HOST'
    }
  }
});

config.validate({ allowed: 'strict' });
module.exports = config.get();

Logging with Context

// Do: Use AsyncLocalStorage for transaction ID
const { AsyncLocalStorage } = require('async_hooks');
const asyncLocalStorage = new AsyncLocalStorage();

function logWithContext(message, data) {
  const context = asyncLocalStorage.getStore();
  logger.info(message, { 
    ...data, 
    transactionId: context?.transactionId 
  });
}

// Middleware to set context
app.use((req, res, next) => {
  const transactionId = uuid.v4();
  asyncLocalStorage.run({ transactionId }, () => {
    next();
  });
});

Input Validation

// Do: Use validation library
const Joi = require('joi');

const userSchema = Joi.object({
  email: Joi.string().email().required(),
  password: Joi.string().min(8).required(),
  age: Joi.number().integer().min(18).max(120)
});

function validateUser(userData) {
  const { error, value } = userSchema.validate(userData);
  if (error) {
    throw new AppError('ValidationError', error.message, 400);
  }
  return value;
}

Security Headers

// Do: Use helmet
const helmet = require('helmet');

app.use(helmet());
app.use(helmet.contentSecurityPolicy({
  directives: {
    defaultSrc: ["'self'"],
    styleSrc: ["'self'", "'unsafe-inline'"],
    scriptSrc: ["'self'"],
    imgSrc: ["'self'", 'data:', 'https:']
  }
}));

Summary Checklist

[ ] Structure by business components
[ ] Use 3-tier layering (entry-points, domain, data-access)
[ ] Implement centralized error handling
[ ] Use async-await exclusively
[ ] Configure ESLint with security plugins
[ ] Write API tests minimum
[ ] Use mature logger (Pino/Winston)
[ ] Implement rate limiting
[ ] Validate all user input
[ ] Lock dependencies
[ ] Use environment variables for config
[ ] Monitor with APM tools
[ ] Set NODE_ENV=production
[ ] Log to stdout only
[ ] Use Docker multi-stage builds
[ ] Implement graceful shutdown
[ ] Scan for vulnerabilities
[ ] Use LTS Node.js version
[ ] Enable TypeScript thoughtfully
[ ] Test error flows

References

Main Repository: https://github.com/goldbergyoni/nodebestpractices
JavaScript Testing: https://github.com/goldbergyoni/javascript-testing-best-practices
Node.js Integration Tests: https://github.com/testjavascript/nodejs-integration-tests-best-practices

Dapper no .NET: simplicidade e performance no acesso a dados

Danilo Itagyba — Wed, 03 Sep 2025 13:03:46 +0000

Quando pensamos em acesso a banco de dados no .NET, o Entity Framework costuma ser a escolha padrão. Ele oferece recursos avançados de ORM, mas nem sempre precisamos de toda essa complexidade. Em cenários onde performance e simplicidade são prioridade, o Dapper se destaca como alternativa leve e eficiente.

O que é o Dapper?

O Dapper é uma biblioteca open source criada pela equipe do Stack Overflow. Ele é conhecido como um micro-ORM, pois não tenta abstrair completamente o banco de dados. Em vez disso, fornece um jeito simples e rápido de mapear resultados de queries SQL para objetos C#.

📦 Pacote: Dapper (disponível no NuGet)
⚡ Performance: próximo do ADO.NET puro, mas com muito menos código
🎯 Ideal quando você já tem queries SQL prontas e quer apenas mapear resultados para objetos

Instalação

No seu projeto .NET, basta rodar:

dotnet add package Dapper

Primeiro Exemplo com Dapper

Suponha que temos uma tabela Products no banco:

CREATE TABLE Products ( Id INT PRIMARY KEY, Name NVARCHAR(100), Price DECIMAL(10,2) )

E uma classe em C#:
public class Product { public int Id { get; set; } public string Name { get; set; } public decimal Price { get; set; } }

Com Dapper, podemos buscar todos os produtos assim:

using System.Data.SqlClient;
using Dapper;

string connectionString = "Server=.;Database=MyDb;Trusted_Connection=True;";

using (var connection = new SqlConnection(connectionString))
{
    var products = connection.Query<Product>("SELECT * FROM Products").ToList();

    foreach (var p in products)
    {
        Console.WriteLine($"{p.Id} - {p.Name} - {p.Price:C}");
    }
}

👉 Em apenas duas linhas de código (Query + ToList()), já temos os dados do banco mapeados para objetos.

Inserindo Dados com Dapper:

var sql = "INSERT INTO Products (Name, Price) VALUES (@Name, @Price)";

var newProduct = new Product { Name = "Notebook", Price = 3500.00m };

using (var connection = new SqlConnection(connectionString))
{
    connection.Execute(sql, newProduct);
}

Aqui o Dapper faz o binding automático das propriedades Name e Price do objeto para os parâmetros @name e @price da query.

Vantagens do Dapper
✔️ Simplicidade – menos código para mapear dados
✔️ Performance – quase tão rápido quanto ADO.NET puro
✔️ Flexibilidade – você escreve o SQL, o Dapper só faz o mapeamento
✔️ Integração fácil – funciona bem junto com Entity Framework, se quiser misturar

Quando usar o Dapper?

Projetos que exigem alta performance.

Sistemas que já usam queries SQL prontas.

Aplicações pequenas ou médias onde um ORM completo seria “overkill”.

Microserviços, APIs e jobs que só precisam de consultas rápidas.

Se você precisa de lazy loading, migrations ou LINQ avançado, provavelmente o Entity Framework continua sendo a melhor opção.

Conclusão

O Dapper é a escolha perfeita quando você quer controle total sobre suas queries SQL, mas não quer lidar com toda a verbosidade do ADO.NET. Ele equilibra performance, simplicidade e produtividade de uma forma difícil de ignorar.

Se o seu projeto .NET precisa de acesso a dados rápido e direto ao ponto, vale a pena experimentar o Dapper.

Forem: Danilo Itagyba

Codex CLI no dia a dia: como usar IA no terminal com boas práticas

🚀 O que é o Codex CLI?

⚙️ Setup básico

🧠 Como pensar ao usar Codex

🧩 Boas práticas essenciais

1. Dê contexto (isso muda tudo)

2. Quebre tarefas grandes

3. Planeje antes de executar

4. Use AGENTS.md

5. Use intenção, não sintaxe

6. Trabalhe em ciclos curtos

🧪 A parte mais importante: TESTES

🧠 Regra de ouro

🧩 Tipos de testes que você DEVE usar

✔️ Unit Test

✔️ Integration Test

✔️ Regression Test

⚠️ O que acontece se você NÃO testar

⚙️ Boas práticas com testes + Codex

✔️ Gere testes junto com código

✔️ Crie testes antes de refatorar

✔️ Aumente cobertura automaticamente

✔️ Automatize no CI/CD

🧱 Exemplos reais de uso

Criar endpoint

Otimizar SQL

Refatorar código

⚠️ Erros comuns

🏁 Conclusão

📌 TL;DR

Blindando Aplicações no .NET 10: Um Guia Completo sobre Polly e Resiliência

Resiliência à Prova de Falhas no .NET 10 com Polly

1. O Novo Paradigma: Resilience Pipelines

Instalação

2. Estratégias Fundamentais de Resiliência

A. Retry (Tentativa) com Jitter

B. Circuit Breaker (Disjuntor)

C. Fallback (Plano de Contingência)

D. Hedging (Especulação)

3. A Implementação "Gold Standard" no .NET 10

Configuração no Program.cs

Consumindo o Serviço Resiliente

4. Cenários Avançados: Pipeline Registry

Registro

Uso Injetado

5. Checklist de Melhores Práticas

Conclusão

🚀 Node.js Best Practices

Node.js Best Practices

Table of Contents

Project Structure

📂 Component-Based Architecture

⚙️ Configuration Management

Framework Selection

Recommended Frameworks (2024)

Framework Considerations

TypeScript Usage

Use TypeScript Sparingly and Thoughtfully

Error Handling

Async Error Handling

Error Object Standards

Error Classification

Centralized Error Handling

Error Documentation

Process Exit Strategy

Logging Best Practices

Testing Error Flows

Monitoring

Promise Management

Input Validation

Event Emitter Error Handling

Code Style and Patterns

ESLint Configuration

Node.js-Specific Linting

Code Formatting Rules

Naming Conventions

Variable Declaration

Module Management

Module Entry Points

Configuração no `Program.cs`