ntex rest api example Download - ntex rest api example de código fonte download

fundo

Ei, hoje eu queria compartilhar meus conhecimentos sobre como escrever uma API REST em ferrugem. Pode ser mais fácil do que você pensa! Não mostraremos a conectividade do banco de dados neste artigo. Em vez disso, focamos em demonstrar como gerar especificações OpenAPI e servir uma Swagger UI .

Você pode encontrar a fonte de código completa no GitHub.

Antes de começar, verifique se você está instalado.

Vamos começar inicializando um novo projeto usando cargo init .

cargo init my-rest-api
cd my-rest-api

Isso deve produzir a seguinte estrutura de diretório:

 ├── Cargo.toml
└── src
    └── main.rs

Você pode usar rustfmt para formatação. Para fazer isso, crie um arquivo rustfmt.toml com o seguinte conteúdo:

 indent_style = " Block "
max_width = 80
tab_spaces = 2
reorder_imports = false
reorder_modules = false
force_multiline_blocks = true
brace_style = " PreferSameLine "
control_brace_style = " AlwaysSameLine "

Eu pessoalmente uso o vscode. Opcionalmente, você pode adicionar essa configuração ao seu .vscode/settings.json :

{
  "editor.rulers" : [ 80 ],
  "editor.tabSize" : 2 ,
  "editor.detectIndentation" : false ,
  "editor.trimAutoWhitespace" : true ,
  "editor.formatOnSave" : true ,
  "files.insertFinalNewline" : true ,
  "files.trimTrailingWhitespace" : true ,
  "rust-analyzer.showUnlinkedFileNotification" : false ,
  "rust-analyzer.checkOnSave" : true ,
  "rust-analyzer.check.command" : " clippy "
}

Sua nova estrutura de diretório deve ficar assim:

 ├── .gitignore
├── .vscode
│   └── settings.json
├── Cargo.lock
├── Cargo.toml
├── rustfmt.toml
└── src
    └── main.rs

Vamos usar o NTEX como nossa estrutura HTTP.
Podemos instalar dependências de ferrugem executando cargo add .
Observe que, ao usar ntex , temos a capacidade de escolher nosso runtime .
Para resumir rapidamente, o runtime gerenciará seu padrão async|await
Se você está familiarizado com o nodejs runtime , é semelhante em uso.

Para este tutorial, vamos usar Tokio, pois parece ser a escolha mais popular. Vamos adicionar NTEX como uma dependência:

cargo add ntex --features tokio

Em seguida, vamos atualizar nosso arquivo main.rs com o seguinte conteúdo:

 use ntex :: web ;

# [ web :: get ( "/" ) ]
async fn index ( ) -> & ' static str {
  "Hello world!"
}

# [ ntex :: main ]
async fn main ( ) -> std :: io :: Result < ( ) > {
  web :: server ( || web :: App :: new ( ) . service ( index ) )
    . bind ( ( "0.0.0.0" , 8080 ) ) ?
    . run ( )
    . await ? ;
  Ok ( ( ) )
}

Podemos executar nosso projeto usando o seguinte comando:

cargo run

Este comando compilará nosso código e o executará.
Você deve ver a seguinte saída:

 Finished dev [unoptimized + debuginfo] target(s) in 17.38s
Running `target/debug/my-rest-api`

Podemos testar nosso servidor usando CURL:

 curl -v localhost:8080

 *   Trying 127.0.0.1:8080...
* TCP_NODELAY set
* Connected to localhost (127.0.0.1) port 8080 (#0)
> GET / HTTP/1.1
> Host: localhost:8080
> User-Agent: curl/7.68.0
> Accept: * / *
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< content-length: 12
< content-type: text/plain; charset=utf-8
< date: Fri, 26 May 2023 11:43:01 GMT
<
* Connection #0 to host localhost left intact
Hello world!%

Parabéns! Agora você tem seu primeiro servidor HTTP no Rust !

Agora vamos criar nossos primeiros REST endpoints .

Em relação à arquitetura do diretório, cabe à preferência pessoal. No ntex , usamos o método .service() para adicionar novos endpoints . Portanto, optei por criar um diretório chamado services para abrigar meus pontos de extremidade.

Vamos criar o diretório:

mkdir src/services
touch src/services/mod.rs

Observe que, por padrão, Rust tenta importar um arquivo mod.rs de nossos diretórios.

Vamos criar nossos endpoints padrão dentro de services/mod.rs :

 use ntex :: web ;

pub async fn default ( ) -> web :: HttpResponse {
  web :: HttpResponse :: NotFound ( ) . finish ( )
}

Agora precisamos indicar que queremos usar este módulo em nosso principal.RS:

 use ntex :: web ;

mod services ;

# [ ntex :: main ]
async fn main ( ) -> std :: io :: Result < ( ) > {
  web :: server ( || {
    web :: App :: new ( )
      // Default endpoint for unregisterd endpoints
      . default_service ( web :: route ( ) . to ( services :: default )
    )
  } )
  . bind ( ( "0.0.0.0" , 8080 ) ) ?
  . run ( )
  . await ? ;
  Ok ( ( ) )
}

Agora, para qualquer endpoints não registrado, teremos um erro 404.

Antes de continuar, vamos adicionar quatro dependências: serde e serde_json para a serialização do JSON, e utoipa com utoipa-swagger-ui para ter uma arrogância OpenAPI .

cargo add serde --features derive
cargo add serde_json utoipa utoipa-swagger-ui

Em seguida, criaremos nosso próprio tipo HttpError como ajudante. Crie um arquivo no src/error.rs com o seguinte conteúdo:

 use ntex :: web ;
use ntex :: http ;
use utoipa :: ToSchema ;
use serde :: { Serialize , Deserialize } ;

/// An http error response
# [ derive ( Clone , Debug , Serialize , Deserialize , ToSchema ) ]
pub struct HttpError {
  /// The error message
  pub msg : String ,
  /// The http status code, skipped in serialization
  # [ serde ( skip ) ]
  pub status : http :: StatusCode ,
}

/// Helper function to display an HttpError
impl std :: fmt :: Display for HttpError {
  fn fmt ( & self , f : & mut std :: fmt :: Formatter < ' _ > ) -> std :: fmt :: Result {
    write ! ( f , "[{}] {}" , self . status , self . msg )
  }
}

/// Implement standard error for HttpError
impl std :: error :: Error for HttpError { }

/// Helper function to convert an HttpError into a ntex::web::HttpResponse
impl web :: WebResponseError for HttpError {
  fn error_response ( & self , _ : & web :: HttpRequest ) -> web :: HttpResponse {
    web :: HttpResponse :: build ( self . status ) . json ( & self )
  }
}

Precisamos importar nosso módulo de erro em nosso main.rs Deixe atualizá -lo:

 use ntex :: web ;

mod error ;
mod services ;

# [ ntex :: main ]
async fn main ( ) -> std :: io :: Result < ( ) > {
  web :: server ( || {
    web :: App :: new ( )
      // Default endpoint for unregisterd endpoints
      . default_service ( web :: route ( ) . to ( services :: default )
    )
  } )
  . bind ( ( "0.0.0.0" , 8080 ) ) ?
  . run ( )
  . await ? ;
  Ok ( ( ) )
}

Acho que estamos prontos para escrever alguns endpoints . Vamos simular uma lista de TODO e criar um novo arquivo no src/services/todo.rs :

 use ntex :: web ;

# [ web :: get ( "/todos" ) ]
pub async fn get_todos ( ) -> web :: HttpResponse {
  web :: HttpResponse :: Ok ( ) . finish ( )
}

# [ web :: post ( "/todos" ) ]
pub async fn create_todo ( ) -> web :: HttpResponse {
  web :: HttpResponse :: Created ( ) . finish ( )
}

# [ web :: get ( "/todos/{id}" ) ]
pub async fn get_todo ( ) -> web :: HttpResponse {
  web :: HttpResponse :: Ok ( ) . finish ( )
}

# [ web :: put ( "/todos/{id}" ) ]
pub async fn update_todo ( ) -> web :: HttpResponse {
  web :: HttpResponse :: Ok ( ) . finish ( )
}

# [ web :: delete ( "/todos/{id}" ) ]
pub async fn delete_todo ( ) -> web :: HttpResponse {
  web :: HttpResponse :: Ok ( ) . finish ( )
}

pub fn ntex_config ( cfg : & mut web :: ServiceConfig ) {
  cfg . service ( get_todos ) ;
  cfg . service ( create_todo ) ;
  cfg . service ( get_todo ) ;
  cfg . service ( update_todo ) ;
  cfg . service ( delete_todo ) ;
}

Precisamos atualizar nosso src/services/mod.rs para importar nosso todo.rs :

 pub mod todo ;

use ntex :: web ;

pub async fn default ( ) -> web :: HttpResponse {
  web :: HttpResponse :: NotFound ( ) . finish ( )
}

Em nosso main.rs :

 use ntex :: web ;

mod error ;
mod services ;

# [ ntex :: main ]
async fn main ( ) -> std :: io :: Result < ( ) > {
  web :: server ( || {
    web :: App :: new ( )
      // Register todo endpoints
      . configure ( services :: todo :: ntex_config )
      // Default endpoint for unregisterd endpoints
      . default_service ( web :: route ( ) . to ( services :: default ) )
  } )
  . bind ( ( "0.0.0.0" , 8080 ) ) ?
  . run ( )
  . await ? ;
  Ok ( ( ) )
}

Vamos criar alguma estrutura de dados para o nosso Todo . Vamos criar um novo diretório src/models com seu mod.rs e um todo.rs

mkdir src/models
touch src/models/mod.rs
touch src/models/todo.rs

Em nosso src/models/mod.rs vamos importar todo.rs :

 pub mod todo ;

E dentro src/models/todo.rs , vamos adicionar alguma data structure :

 use utoipa :: ToSchema ;
use serde :: { Serialize , Deserialize } ;

/// Todo model
# [ derive ( Clone , Debug , Serialize , Deserialize , ToSchema ) ]
pub struct Todo {
  /// The todo id
  pub id : i32 ,
  /// The todo title
  pub title : String ,
  /// The todo completed status
  pub completed : bool ,
}

/// Partial Todo model
# [ derive ( Clone , Debug , Serialize , Deserialize , ToSchema ) ]
pub struct TodoPartial {
  /// The todo title
  pub title : String ,
}

Você pode notar que usamos o serde e utoipa derivam macros para permitir a serialização e a conversão JSON para OpenAPI Schema .

Não se esqueça de atualizar seu main.rs para importar nossos models :

 use ntex :: web ;

mod error ;
mod models ;
mod services ;

# [ ntex :: main ]
async fn main ( ) -> std :: io :: Result < ( ) > {
  web :: server ( || {
    web :: App :: new ( )
      // Register todo endpoints
      . configure ( services :: todo :: ntex_config )
      // Default endpoint for unregisterd endpoints
      . default_service ( web :: route ( ) . to ( services :: default ) )
  } )
  . bind ( ( "0.0.0.0" , 8080 ) ) ?
  . run ( )
  . await ? ;
  Ok ( ( ) )
}

Com os modelos em vigor, agora podemos gerar pontos de extremidade seguros com sua documentação. Vamos atualizar nossos endpoints dentro src/services/todo.rs :

 use ntex :: web ;

use crate :: models :: todo :: TodoPartial ;

/// List all todos
# [ utoipa :: path (
  get ,
  path = "/todos" ,
  responses (
    ( status = 200 , description = "List of Todo" , body = [ Todo ] ) ,
  ) ,
) ]
# [ web :: get ( "/todos" ) ]
pub async fn get_todos ( ) -> web :: HttpResponse {
  web :: HttpResponse :: Ok ( ) . finish ( )
}

/// Create a new todo
# [ utoipa :: path (
  post ,
  path = "/todos" ,
  request_body = TodoPartial ,
  responses (
    ( status = 201 , description = "Todo created" , body = Todo ) ,
  ) ,
) ]
# [ web :: post ( "/todos" ) ]
pub async fn create_todo (
  _todo : web :: types :: Json < TodoPartial > ,
) -> web :: HttpResponse {
  web :: HttpResponse :: Created ( ) . finish ( )
}

/// Get a todo by id
# [ utoipa :: path (
  get ,
  path = "/todos/{id}" ,
  responses (
    ( status = 200 , description = "Todo found" , body = Todo ) ,
    ( status = 404 , description = "Todo not found" , body = HttpError ) ,
  ) ,
) ]
# [ web :: get ( "/todos/{id}" ) ]
pub async fn get_todo ( ) -> web :: HttpResponse {
  web :: HttpResponse :: Ok ( ) . finish ( )
}

/// Update a todo by id
# [ utoipa :: path (
  put ,
  path = "/todos/{id}" ,
  request_body = TodoPartial ,
  responses (
    ( status = 200 , description = "Todo updated" , body = Todo ) ,
    ( status = 404 , description = "Todo not found" , body = HttpError ) ,
  ) ,
) ]
# [ web :: put ( "/todos/{id}" ) ]
pub async fn update_todo ( ) -> web :: HttpResponse {
  web :: HttpResponse :: Ok ( ) . finish ( )
}

/// Delete a todo by id
# [ utoipa :: path (
  delete ,
  path = "/todos/{id}" ,
  responses (
    ( status = 200 , description = "Todo deleted" , body = Todo ) ,
    ( status = 404 , description = "Todo not found" , body = HttpError ) ,
  ) ,
) ]
# [ web :: delete ( "/todos/{id}" ) ]
pub async fn delete_todo ( ) -> web :: HttpResponse {
  web :: HttpResponse :: Ok ( ) . finish ( )
}

pub fn ntex_config ( cfg : & mut web :: ServiceConfig ) {
  cfg . service ( get_todos ) ;
  cfg . service ( create_todo ) ;
  cfg . service ( get_todo ) ;
  cfg . service ( update_todo ) ;
  cfg . service ( delete_todo ) ;
}

Com o Utoipa, poderemos servir nossa documentação de arrogância.

Vamos criar um novo arquivo no src/services/openapi.rs :

 use std :: sync :: Arc ;

use ntex :: web ;
use ntex :: http ;
use ntex :: util :: Bytes ;
use utoipa :: OpenApi ;

use crate :: error :: HttpError ;
use crate :: models :: todo :: { Todo , TodoPartial } ;

use super :: todo ;

/// Main structure to generate OpenAPI documentation
# [ derive ( OpenApi ) ]
# [ openapi (
  paths (
    todo :: get_todos ,
    todo :: create_todo ,
    todo :: get_todo ,
    todo :: update_todo ,
    todo :: delete_todo ,
  ) ,
  components ( schemas ( Todo , TodoPartial , HttpError ) )
) ]
pub ( crate ) struct ApiDoc ;

# [ web :: get ( "/{tail}*" ) ]
async fn get_swagger (
  tail : web :: types :: Path < String > ,
  openapi_conf : web :: types :: State < Arc < utoipa_swagger_ui :: Config < ' static > > > ,
) -> Result < web :: HttpResponse , HttpError > {
  if tail . as_ref ( ) == "swagger.json" {
    let spec = ApiDoc :: openapi ( ) . to_json ( ) . map_err ( |err| HttpError {
      status : http :: StatusCode :: INTERNAL_SERVER_ERROR ,
      msg : format ! ( "Error generating OpenAPI spec: {}" , err ) ,
    } ) ? ;
    return Ok (
      web :: HttpResponse :: Ok ( )
        . content_type ( "application/json" )
        . body ( spec ) ,
    ) ;
  }
  let conf = openapi_conf . as_ref ( ) . clone ( ) ;
  match utoipa_swagger_ui :: serve ( & tail , conf . into ( ) ) . map_err ( |err| {
    HttpError {
      msg : format ! ( "Error serving Swagger UI: {}" , err ) ,
      status : http :: StatusCode :: INTERNAL_SERVER_ERROR ,
    }
  } ) ? {
    None => Err ( HttpError {
      status : http :: StatusCode :: NOT_FOUND ,
      msg : format ! ( "path not found: {}" , tail ) ,
    } ) ,
    Some ( file ) => Ok ( {
      let bytes = Bytes :: from ( file . bytes . to_vec ( ) ) ;
      web :: HttpResponse :: Ok ( )
        . content_type ( file . content_type )
        . body ( bytes )
    } ) ,
  }
}

pub fn ntex_config ( config : & mut web :: ServiceConfig ) {
  let swagger_config = Arc :: new (
    utoipa_swagger_ui :: Config :: new ( [ "/explorer/swagger.json" ] )
      . use_base_layout ( ) ,
  ) ;
  config . service (
    web :: scope ( "/explorer/" )
      . state ( swagger_config )
      . service ( get_swagger ) ,
  ) ;
}

Não se esqueça de atualizar src/services/mod.rs para importar src/services/openapi.rs :

 pub mod todo ;
pub mod openapi ;

use ntex :: web ;

pub async fn default ( ) -> web :: HttpResponse {
  web :: HttpResponse :: NotFound ( ) . finish ( )
}

Em seguida, podemos atualizar nossos main.rs para registrar nossos pontos de extremidade do Explorer:

 use ntex :: web ;

mod error ;
mod models ;
mod services ;

# [ ntex :: main ]
async fn main ( ) -> std :: io :: Result < ( ) > {
  web :: server ( || {
    web :: App :: new ( )
      // Register swagger endpoints
      . configure ( services :: openapi :: ntex_config )
      // Register todo endpoints
      . configure ( services :: todo :: ntex_config )
      // Default endpoint for unregisterd endpoints
      . default_service ( web :: route ( ) . to ( services :: default ) )
  } )
  . bind ( ( "0.0.0.0" , 8080 ) ) ?
  . run ( )
  . await ? ;
  Ok ( ( ) )
}

Estamos prontos para ir. Vamos executar nosso servidor:

cargo run

Então devemos poder acessar nosso Explorer em http: // localhost: 8080/explorer/

Swagger

Espero que você tente escrever sua próxima API Rest em Rust!

Não se esqueça de dar uma olhada na documentação de dependências:

NTEX
Serde
Serde_json
utoipa

Bônus

Crie uma imagem do Docker de produção! Adicione um Dockerfile no diretório do seu projeto com o seguinte conteúdo:

 # Builder
FROM rust:1.69.0-alpine3.17 as builder

WORKDIR /app

# # Install build dependencies
RUN apk add alpine-sdk musl-dev build-base upx

# # Copy source code
COPY Cargo.toml Cargo.lock ./
COPY src ./src

# # Build release binary
RUN cargo build --release --target x86_64-unknown-linux-musl
# # Pack release binary with UPX (optional)
RUN upx --best --lzma /app/target/x86_64-unknown-linux-musl/release/my-rest-api

# Runtime
FROM scratch

# # Copy release binary from builder
COPY --from=builder /app/target/x86_64-unknown-linux-musl/release/my-rest-api /app

ENTRYPOINT [ "/app" ]

Opcionalmente, você pode adicionar este perfil release em sua Cargo.toml :

[ profile . release ]
opt-level = " z "
codegen-units = 1
strip = true
lto = true

Isso otimizará o binário de liberação para ser o menor possível. Além disso, com a UPX, podemos criar uma imagem muito pequena do Docker!

Construa sua imagem:

docker build -t my-rest-api:0.0.1 -f Dockerfile .

Docker_image_ls

Se você quiser ver uma USECASE mais real, convido você a dar uma olhada no meu projeto OpenSource Nanocl. Isso tenta simplificar o desenvolvimento e a implantação de micro serviços, com contêineres ou máquinas virtuais!

Codificação feliz!

Expandir