📚 Pré-requisitos Teóricos: este projeto aplica conceitos ensinados no Capítulo 18 — Programação Assíncrona com Runtime Tokio e Async/Await da Especialização em Sistemas com Rust. Recomendado revisar antes de iniciar.

🦀 API RESTful Assíncrona de Alta Vazão com Tokio & Axum

v1.0 — Rust Assíncrono, Tokio Runtime, Axum, Tower, Conexões Não-Bloqueantes, Serde JSON

Série Prática Sistemas em Rust — Projeto Especializado

➡️ Projeto: 🦀 API RESTful Assíncrona de Alta Vazão com Tokio & Axum

Subpasta Canônica: api-axum/

🏛️ Visão Geral & Arquitetura Visual

O projeto API RESTful Assíncrona de Alta Vazão com Tokio & Axum desenvolve um serviço backend de microsserviço em Rust capaz de processar centenas de milhares de requisições concorrentes com latência sub-milissegundo. A solução combina o runtime assíncrono Tokio baseado em event loops de threads verdes (green tasks), o framework web de alta velocidade Axum com roteamento tipado e o ecossistema de middlewares Tower, alcançando máxima eficiência no consumo de memória e I/O de rede não-bloqueante.

Arquitetura do Projeto 🦀 API RESTful Assíncrona de Alta Vazão com Tokio & Axum

📁 Estrutura de Pastas Anti-Colisão

Os artefatos em Rust, manifestos Cargo e documentação técnica estão organizados na subpasta canônica api-axum/:

catalogo_projetos/sistemas_rust_02_axum_async_api/
├── assets/
│   └── arquitetura_rust_02.svg
├── api-axum/
│   ├── Cargo.toml
│   ├── README.md
│   └── src/
│       └── main.rs
└── index.md

🧑‍💼 Engenharia de Software & Especificação Formal

1. Histórias de Usuário (User Stories)

ID	Persona	Narrativa da Funcionalidade	Critério de Aceitação Principal	Prioridade
US-01	Arquiteto de Backend	Quero uma API REST com latência no percentil p99 inferior a 2 milissegundos	Uso do runtime Tokio com I/O multiplexado epoll/kqueue.	Alta
US-02	Desenvolvedor Backend	Quero rotas fortemente tipadas e validação automática de payloads JSON	Extratores do Axum (`Json<T>`, `Path<T>`, `State<T>`) validados em tempo de compilação.	Alta
US-03	Engenheiro de Segurança	Quero proteção contra esgotamento de conexões e slowloris	Middlewares Tower controlando timeouts, concurrency limits e CORS.	Alta
US-04	Engenheiro de Confiabilidade	Quero compartilhar estado global em memória sem deadlock	Uso de `Arc<RwLock<T>>` ou state patterns seguros do Axum.	Alta
US-05	Desenvolvedor Frontend	Quero respostas padronizadas em formato JSON serializadas com zero cópias desnecessárias	Adoção do Serde com zero-copy deserialization.	Média

2. Requisitos do Sistema

Requisitos Funcionais (RF)

RF-01: Inicializar o runtime assíncrono Tokio com suporte a multi-threading.
RF-02: Configurar router Axum com endpoints de health check, consulta e inserção de recursos.
RF-03: Implementar extratores tipados para deserialização automática de requisições JSON.
RF-04: Gerenciar estado compartilhado da aplicação através de axum::extract::State.
RF-05: Retornar códigos de status HTTP corretos (200 OK, 201 Created, 404 Not Found, 422 Unprocessable).

Requisitos Não-Funcionais (RNF)

RNF-01 (Throughput Massivo): Capacidade de atender dezenas de milhares de requisições simultâneas sem bloqueio de thread.
RNF-02 (Conformidade com Tipos): Garantia de segurança de tipos em rotas e parâmetros em tempo de compilação.
RNF-03 (Consumo Mínimo de RAM): Footprint de memória inferior a 20 MB em repouso.
RNF-04 (Concorrência Não-Bloqueante): Ausência de operações bloqueantes dentro do event loop assíncrono.
RNF-05 (Resiliência a Falhas): Tratamento elegante de erros via padrão Result<T, AppError>.

3. Diagrama de Casos de Uso

flowchart TD
    Client[(fa:fa-globe Clientes HTTP/2)]
    Tokio[(fa:fa-bolt Tokio Async Event Loop)]
    DB[(fa:fa-database Storage Assíncrono)]

    subgraph AppAxumAPI ["🦀 API Assíncrona Axum (api-axum)"]
        UC01["Receber Requisição HTTP Concorrente"]
        UC02["Despachar Task Leve (tokio::spawn)"]
        UC03["Rotear e Extrair JSON Tipado (Axum)"]
        UC04["Consultar Storage Não-Bloqueante"]
        UC05["Emitir Resposta JSON Zero-Copy"]
    end

    Client --> UC01
    UC01 --> Tokio
    Tokio --> UC02
    UC02 --> UC03
    UC03 --> UC04
    UC04 --> DB
    UC04 --> UC05
    UC05 --> Client

4. Matriz de Rastreabilidade (RTM)

ID Requisito	História de Usuário	Artefato de Código	Teste de Aceitação
RF-01	US-01	`api-axum/src/main.rs`	Inicialização da macro `#[tokio::main]`
RF-02	US-02	`api-axum/src/main.rs`	Configuração do router com `Router::new()`
RF-03	US-05	`api-axum/src/main.rs`	Uso de `axum::Json` e structs Serde
RF-04	US-04	`api-axum/src/main.rs`	Injeção de dependência com `State`
RF-05	US-03	`api-axum/src/main.rs`	Respostas HTTP padronizadas e testes de integração

🛠️ Implementação Guiada

ℹ️ O trecho de código que ficava aqui não correspondia ao código do projeto e foi retirado. Consulte os arquivos em api-axum.

🚀 Como Executar no Laboratório

1. Navegue até a subpasta do projeto

cd catalogo_projetos/sistemas_rust_02_axum_async_api/api-axum

2. Execute via Cargo

cargo run

🏁 Matriz de Checkpoints de Conclusão

Checkpoint	Meta Técnica	Critério de Aceite	Status
CP-01	Tokio Runtime Ativo	Loop assíncrono executando em pool de workers	`PASS ✅`
CP-02	Roteamento Tipado Axum	Endpoints `/health` e `/mensagens` mapeados	`PASS ✅`
CP-03	Serialização Serde JSON	Parsing e resposta JSON com validação de tipos	`PASS ✅`
CP-04	Estado Concorrente Seguro	Compartilhamento com `Arc<RwLock<T>>` sem data races	`PASS ✅`
CP-05	Testes de Integração HTTP	Suíte de requisições de teste aprovada	`PASS ✅`