ntex rest api example Download - ntex rest api example رمز المصدر

خلفية

مرحبًا ، أردت اليوم أن أشارك معرفتي حول كيفية كتابة واجهة برمجة تطبيقات REST في الصدأ. قد يكون أسهل مما تعتقد! لن نعرض اتصال قاعدة البيانات في هذه المقالة. بدلاً من ذلك ، ركزنا على توضيح كيفية إنشاء مواصفات OpenAPI وخدمة Swagger UI .

يمكنك العثور على مصدر الكود الكامل على جيثب.

قبل البدء ، تأكد من تثبيت الصدأ.

لنبدأ بتهيئة مشروع جديد باستخدام 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 -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 من أدلةنا.

دعنا ننشئ endpoints الافتراضية الخاصة بنا داخل services/mod.rs :

 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.

قبل المتابعة ، دعنا نضيف أربعة تبعيات: serde و serde_json للتسلسل JSON ، و utoipa مع utoipa-swagger-ui للحصول على تبخير OpenAPI .

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 . سنقوم بإنشاء دليل جديد src/models مع mod.rs و todo.rs

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

مع وجود النماذج المعمول بها ، يمكننا الآن إنشاء نقاط نهاية آمنة من النوع مع وثائقها. دعنا نقوم بتحديث endpoints الخاصة بنا داخل 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 ) ;
}

مع 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/mod.rs لاستيراد src/services/openapi.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/

اختيال

أتمنى أن تحاول كتابة واجهة برمجة تطبيقات الراحة التالية في الصدأ!

لا تنس إلقاء نظرة على وثائق التبعيات:

NTEX
سيردي
serde_json
Utoipa

علاوة

إنشاء صورة عامل الإنتاج! أضف 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 :

[ 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 .

docker_image_ls

إذا كنت ترغب في رؤية عالم أكثر واقعية ، فأنا أدعوك لإلقاء نظرة على مشروع OpenSource Nanocl الخاص بي. التي تحاول تبسيط تطوير ونشر الخدمات الصغيرة ، مع الحاويات أو الأجهزة الافتراضية!

ترميز سعيد!

يوسع