ntex rest api example

ねえ、今日はRustでREST APIを書く方法に関する知識を共有したかったのです。あなたが思っているよりも簡単かもしれません！この記事では、データベースの接続を紹介しません。代わりに、 OpenAPI仕様を生成し、 Swagger UIを提供する方法を示すことに焦点を当てました。

GitHubで完全なコードソースを見つけることができます。

開始する前に、錆びたインストールがあることを確認してください。

cargo initを使用して新しいプロジェクトを初期化することから始めましょう。

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

次のディレクトリ構造が生成されるはずです。

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

rustfmtを使用してフォーマットできます。そうするために、次のコンテンツでrustfmt.tomlファイルを作成します。

 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 "

私は個人的にvscodeを使用しています。オプションで、 .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 "
}

あなたの新しいディレクトリ構造は次のようになるはずです：

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

NTEXをHTTPフレームワークとして使用します。
cargo addを実行して、錆の依存関係をインストールできます。
ntexを使用する場合、 runtimeを選択する機能があることに注意してください。
迅速に要約すると、 runtime async|awaitパターンを管理します。
nodejs runtimeに精通している場合、使用状況は似ています。

このチュートリアルでは、Tokioを使用して、より人気のある選択肢と思われます。依存関係としてntexを追加しましょう：

cargo add ntex --features tokio

次に、次のコンテンツでmain.rsファイルを更新します。

 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 ( ( ) )
}

次のコマンドを使用してプロジェクトを実行できます。

cargo run

このコマンドは、コードをコンパイルして実行します。
次の出力が表示されます。

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

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!%

おめでとう！これで、最初のhttpサーバーがRustいます！

それでは、最初のREST endpointsを作成しましょう。

ディレクトリアーキテクチャに関しては、個人的な好みに合っています。 ntexでは、 .service()メソッドを使用して新しいendpointsを追加します。したがって、私は自分のエンドポイントを収容するためにservicesと呼ばれるディレクトリを作成することを選択しました。

ディレクトリを作成しましょう。

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

デフォルトでは、 Rustディレクトリからmod.rsファイルをインポートしようとすることに注意してください。

services/mod.rs内のデフォルトのendpointsを作成しましょう：

 use ntex :: web ;

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

次に、main.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 ( ( ) )
}

さて、未登録のendpointsの場合、404エラーが発生します。

継続する前に、JSONシリアル化用のserdeとserde_json 、 utoipa-swagger-uiとのutoipa 4つの依存関係を追加して、 OpenAPI Swaggerを持っています。

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

次に、ヘルパーとして独自のHttpErrorタイプを作成します。次のコンテンツでsrc/error.rsの下にファイルを作成します。

 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 )
  }
}

main.rsにエラーモジュールをインポートする必要があります。

 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 ( ( ) )
}

いくつかの例のendpointsを書く準備ができていると思います。 TODOリストをシミュレートし、 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 ) ;
}

src/services/mod.rsを更新して、 todo.rsインポートする必要があります。

 pub mod todo ;

use ntex :: web ;

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

私たちの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 ( ( ) )
}

Todoのデータ構造を作成しましょう。彼のmod.rsとtodo.rsを使用して、新しいディレクトリsrc/modelsを作成します

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

src/models/mod.rsでは、 todo.rsをインポートします。

 pub mod todo ;

そして、 src/models/todo.rs内では、 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 ,
}

serdeとutoipaマクロを導出して、 JSONシリアル化とOpenAPI Schemaへの変換を可能にすることに気付くかもしれません。

main.rs更新して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 ( ( ) )
}

モデルを導入すると、ドキュメントを使用してタイプセーフエンドポイントを生成できるようになりました。 src/services/todo.rs内のendpointsを更新しましょう：

 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 ) ;
}

Utoipaを使用すると、Swaggerのドキュメントを提供することができます。

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 ) ,
  ) ;
}

src/services/openapi.rs src/services/mod.rsを更新することを忘れないでください。

 pub mod todo ;
pub mod openapi ;

use ntex :: web ;

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

次に、 main.rs更新して、エクスプローラーエンドポイントを登録できます。

 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 ( ( ) )
}

行ってもいいです。サーバーを実行しましょう：

cargo run

次に、http：// localhost：8080/explorer/でエクスプローラーにアクセスできるはずです

次のREST APIをRustで作成しようとすることを願っています！

依存関係のドキュメントを見ることを忘れないでください。

• ntex
• セルデ
• serde_json
• ユートイパ

ボーナス

プロダクションドッカーイメージを作成してください！次のコンテンツを使用して、プロジェクトディレクトリにDockerfileを追加します。

 # 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" ]

オプションで、このreleaseプロファイルをCargo.tomlに追加できます。toml：

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

これにより、リリースバイナリが可能な限り小さくなるように最適化されます。さらに、UPXを使用すると、本当に小さなDocker画像を作成できます！

あなたの画像を構築する：

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

より現実的な世界のユーザーを見たい場合は、私のOpenSourceプロジェクトNANOCLをご覧ください。これにより、コンテナまたは仮想マシンを使用して、マイクロサービスの開発と展開を簡素化しようとします！

ハッピーコーディング！