Beranda>Sumber daya pembuatan situs web>Data situs web
Unduh

Wissance.webapitoolkit

Lib ini membantu membangun REST API dengan C# dan AspNet dengan mudah daripada menulisnya dari awal dan berulang -ulang dalam proyek yang berbeda.

WebapitoolKit membantu membangun aplikasi dengan mudah

1. Fitur utama

  • REST API Controller dengan CRUD penuh hanya berisi 20 baris kode (~ 10 adalah impor)
    • GET metode memiliki dukungan paging bawaan ;
    • GET Method memiliki penyortiran dan filter dengan parameter kueri;
  • Mendukung Operasi Massal dengan Objek (Bulk Create , Update dan Delete ) pada level antarmuka controller &&
  • dukungan untuk bekerja dengan penyimpanan persisten (antarmuka IModelManager ); Dukungan EntityFramework yang baik (lihat Kelas EfModelManager ). Lihat aplikasi WeatherControl yang memiliki 2 proyek API Web:
    • Wissance.WeatherControl.WebApi menggunakan EntityFramework ;
    • Wissance.WeatherControl.WebApi.V2 menggunakan EdgeDb .

Konsep kunci:

  1. Controller adalah kelas yang menangani HTTP-requests untuk REST Resource .
  2. REST Resource sama dengan Entity class / Database Table
  3. Setiap operasi pada REST Resource menghasilkan JSON dengan DTO sebagai output. Kami berasumsi hanya menggunakan satu kelas DTO dengan semua metode REST .

2. Kontrak API

  • Kelas DTO :

    • OperationResultDto mewakili hasil operasi yang mengubah data dalam DB;
    • PagedDataDto mewakili bagian (halaman) dari objek yang sama (jenis apa pun);

  • Kelas Controllers - Kelas Abstrak

    • Basic Read Controller ( BasicReadController ) berisi 2 metode:
      • GET /api/[controller]/?[page={page}&size={size}&sort={sort}&order={order}] Untuk mendapatkan PagedDataDto<T> Sekarang kami juga memiliki kemungkinan untuk mengirim sejumlah param , Anda hanya perlu menyalakan EfModelManager . Kami juga meneruskan sortir (nama kolom) && order ( asc atau desc ) ke kelas manajer, EfModelManager memungkinkan untuk mengurutkan berdasarkan kolom apa pun . Sayangnya di sini kita memiliki satu kerugian - kita harus mengganti info Swagger untuk menampilkan penggunaan parameter kueri !!! Mulai dari 1.6.0 dimungkinkan untuk melihat semua parameter dalam Swagger dan menggunakannya.
      • GET /api/[controller]/{id} untuk mendapatkan satu objek dengan id
    • Pengontrol CRUD Lengkap ( BasicCrudController ) = Pengontrol Baca Dasar ( BasicReadController ) + Create , Update , dan Delete operasi:
      • POST /api/[controller] - Untuk pembuatan objek baru
      • PUT /api/[controller]/{id} - Untuk mengedit objek dengan id
      • DELETE /api/[controller]/{id} - Untuk Hapus Objek oleh ID
    • CRUD penuh dengan operasi curah (operasi atas beberapa objek sekaligus), kelas dasar - BasicBulkCrudController = Pengontrol Bacaan Dasar ( BasicReadController ) + BulkCreate , BulkUpdate dan Operasi BulkDelete :
      • POST /api/bulk/[controller] - Untuk pembuatan objek baru
      • PUT /api/bulk/[controller] - Untuk mengedit objek yang lewat di badan permintaan
      • DELETE /api/bulk/[controller]/{idList} - Untuk menghapus banyak objek dengan ID.

    Kelas pengontrol mengharapkan semua operasi akan dilakukan menggunakan kelas manajer (setiap pengontrol harus memiliki manajer sendiri)

  • Kelas Manajer - Kelas yang mengimplementasikan logika bisnis aplikasi

    • IModelManager - Antarmuka yang menjelaskan operasi dasar
    • EfModelManager - adalah kelas abstrak yang berisi implementasi operasi Get and Delete
    • EfSoftRemovableModelManager adalah kelas abstrak yang berisi implementasi operasi Get and Delete dengan model yang dapat dilepas lunak ( IsDeleted = true telah dihapus)

Contoh seberapa cepat curah vs non-bulk: Curah vs non curah

 Elapsed time in Non-Bulk REST API with EF is 0.9759984016418457 secs.
Elapsed time in Bulk API with EF is 0.004002094268798828 secs.

Akibatnya kami mendapat hampir ~ 250 x API lebih cepat.

3. Persyaratan

Hanya ada satu persyaratan : semua kelas entitas untuk penyimpanan kegigihan yang digunakan dengan pengontrol & manajer harus mengimplementasikan IModelIdentifiable<T> dari Wissance.WebApiToolkit.Data.Entity . Jika toolkit ini harus digunakan dengan EntityFramework , Anda harus memperoleh Anda Manajer Sumber Daya dari EfModelManager , itu memiliki metode bawaan untuk:

  • get many item
  • get one item by id
  • delete item by id

4. Algoritma Penggunaan Toolkit dengan EntityFramework

Contoh lengkap disebutkan dalam Bagian 6 (lihat di bawah). Tetapi jika Anda mulai membangun API REST Resource baru, Anda harus mengikuti:

  1. Buat kelas model ( entity ) yang mengimplementasikan IModelIdentifiable<T> dan kelas DTO untuk representasi TI ( untuk soft remeD juga menambahkan IModelSoftRemovable Implementasi), yaitu: 
 public class BookEntity : IModelIdentifiable < int >
{
    public int Id { get ; set ; }
    public string Title { get ; set ; }
    public string Authors { get ; set ; } // for simplicity
    public DateTimeOffset Created { get ; set ; }
    public DateTimeOffset Updated { get ; set ; }
}

public class BookDto
{
    public int Id { get ; set ; }
    public string Title { get ; set ; }
    public string Authors { get ; set ; } 
}
  1. Buat fungsi pabrik (yaitu fungsi statis dari kelas statis) yang mengubah Model menjadi DTO yaitu: 
 public static class BookFactory
{
    public static BookDto Create ( BookEntity entity )
    {
        return new BookDto
        {
            Id = entity . Id ,
            Title = entity . Title ,
            Authors = entity . Authors ;
        } ;
    }
}
  1. Buat Antarmuka IModelContext yang membuat Anda BookEntity sebagai kelas implementasi DbSet dan itu yang juga berasal dari DbContext ( EF Abstract Class ): 
 public interface IModelContext
{
    DbSet < BookEntity > Books { get ; set ; }
}

public MoidelContext : DbContext < ModelContext > , IModelContext
{
    // todo: not mrntioned here constructor, entity mapping and so on
    public DbSet < BookEntity > Books { get ; set ; }
}
  1. Konfigurasikan untuk menyuntikkan ModelContext sebagai DbContext via DI Lihat Kelas Startup
  2. Buat kelas Controller dan pasangan kelas manajer, yaitu pertimbangkan di sini penuh CRUD 
 [ ApiController ]
public class BookController : BasicCrudController < BookDto , BookEntity , int , EmptyAdditionalFilters >
{
    public BookController ( BookManager manager )
    {
        Manager = manager ;  // this is for basic operations
        _manager = manager ; // this for extended operations
    }
    
    private BookManager _manager ;
}

public class BookManager : EfModelManager < BookEntity , BookDto , int , EmptyAdditionalFilters >
{
    public BookManager ( ModelContext modelContext , ILoggerFactory loggerFactory ) : base ( modelContext , BookFactory . Create , loggerFactory )
    {
        _modelContext = modelContext ;
    }
    
    public override async Task < OperationResultDto < StationDto > > CreateAsync ( StationDto data )
    {
        // todo: implement
    }
    
    public override async Task < OperationResultDto < StationDto > > UpdateAsync ( int id , StationDto data )
    {
        // todo: implement
    }
    
    private readonly ModelContext _modelContext ;
}

Parameter generik terakhir dalam contoh di atas - EmptyAdditionalFilters adalah kelas yang memegang parameter tambahan untuk dicari untuk dilihat di Swagger, cukup tentukan kelas baru yang mengimplementasikan Ie IReadFilterable IE: 

 public class BooksFilterable : IReadFilterable
{
    public IDictionary < string , string > SelectFilters ( )
    {
            IDictionary < string , string > additionalFilters = new Dictionary < string , string > ( ) ;
            if ( ! string . IsNullOrEmpty ( Title ) )
            {
                additionalFilters . Add ( FilterParamsNames . TitleParameter , Title ) ;
            }

            if ( Authors != null && Authors . Length > 0 )
            {
                additionalFilters . Add ( FilterParamsNames . AuthorsParameter , string . Join ( "," , Authors ) ) ;
            }

            return additionalFilters ;
    }
        
    [ FromQuery ( Name = "title" ) ] public string Title { get ; set ; }
    [ FromQuery ( Name = "author" ) ] public string [ ] Authors { get ; set ; }
}

5. Paket Nuget

Anda dapat menemukan paket nuget di sini

6. Contoh

Di sini kami hanya mempertimbangkan pengontrol CRUD penuh karena crud full = baca saja + operasi tambahan (buat, perbarui, hapus) , contoh lengkap = aplikasi lengkap yang dibuat dengan wissance.webapitoolkit dapat ditemukan di sini: https://github.com/wissance/weathercontrol 

 [ ApiController ]
public class StationController : BasicCrudController < StationDto , StationEntity , int , EmptyAdditionalFilters >
{
    public StationController ( StationManager manager )
    {
        Manager = manager ;  // this is for basic operations
        _manager = manager ; // this for extended operations
    }
    
    private StationManager _manager ;
} 
 public class StationManager : EfModelManager < StationEntity , StationDto , int >
{
    public StationManager ( ModelContext modelContext , ILoggerFactory loggerFactory ) : base ( modelContext , StationFactory . Create , loggerFactory )
    {
        _modelContext = modelContext ;
    }

    public override async Task < OperationResultDto < StationDto > > CreateAsync ( StationDto data )
    {
        try
        {
            StationEntity entity = StationFactory . Create ( data ) ;
            await _modelContext . Stations . AddAsync ( entity ) ;
            int result = await _modelContext . SaveChangesAsync ( ) ;
            if ( result >= 0 )
            {
                return new OperationResultDto < StationDto > ( true , ( int ) HttpStatusCode . Created , null , StationFactory . Create ( entity ) ) ;
            }
            return new OperationResultDto < StationDto > ( false , ( int ) HttpStatusCode . InternalServerError , "An unknown error occurred during station creation" , null ) ;

            }
        catch ( Exception e )
        {
            return new OperationResultDto < StationDto > ( false , ( int ) HttpStatusCode . InternalServerError , $ "An error occurred during station creation: { e . Message } " , null ) ;
        }
    }

    public override async Task < OperationResultDto < StationDto > > UpdateAsync ( int id , StationDto data )
    {
        try
        {
            StationEntity entity = StationFactory . Create ( data ) ;
            StationEntity existingEntity = await _modelContext . Stations . FirstOrDefaultAsync ( s => s . Id == id ) ;
            if ( existingEntity == null )
            {
                return new OperationResultDto < StationDto > ( false , ( int ) HttpStatusCode . NotFound , $ "Station with id: { id } does not exists" , null ) ;
            }

            // Copy only name, description and positions, create measurements if necessary from MeasurementsManager
            existingEntity . Name = entity . Name ;
            existingEntity . Description = existingEntity . Description ;
            existingEntity . Latitude = existingEntity . Latitude ;
            existingEntity . Longitude = existingEntity . Longitude ;
            int result = await _modelContext . SaveChangesAsync ( ) ;
            if ( result >= 0 )
            {
                return new OperationResultDto < StationDto > ( true , ( int ) HttpStatusCode . OK , null , StationFactory . Create ( entity ) ) ;
            }
            return new OperationResultDto < StationDto > ( false , ( int ) HttpStatusCode . InternalServerError , "An unknown error occurred during station update" , null ) ;

        }
        catch ( Exception e )
        {
             return new OperationResultDto < StationDto > ( false , ( int ) HttpStatusCode . InternalServerError , $ "An error occurred during station update: { e . Message } " , null ) ;
        }
            
    }

    private readonly ModelContext _modelContext ;
}

Hanya 2 kelas yang sangat sederhana ^^ menggunakan webapitoolkit

7. Memperluas API

7.1 Tambahkan metode baru ke pengontrol yang ada

Pertimbangkan kami ingin menambahkan metode pencarian ke pengontrol kami: 

 [ HttpGet ]
[ Route ( "api/[controller]/search" ) ]
public async Task < PagedDataDto < BookDto > > > SearchAsync ( [ FromQuery ] string query , [ FromQuery ] int page , [ FromQuery ] int size )
{ 
    OperationResultDto < Tuple < IList < BookDto > , long > > result = await Manager . GetAsync ( page , size , query ) ;
    if ( result == null )
    {
        HttpContext . Response . StatusCode = ( int ) HttpStatusCode . InternalServerError ;
    }

    HttpContext . Response . StatusCode = result . Status ;
    return new PagedDataDto < TRes > ( pageNumber , result . Data . Item2 , GetTotalPages ( result . Data . Item2 , pageSize ) , result . Data . Item1 ) ;
}

7.2 Tambahkan Keamanan untuk Melindungi Anda API

Kami memiliki proyek tambahan untuk melindungi API dengan Keycloak OpenId-Connect . lulus IHttpContextAccessor ke kelas Manager dan periksa sesuatu seperti ini: ClaimsPrincipal principal = _httpContext.HttpContext.User;

8. Bahan tambahan

Anda dapat melihat artikel kami tentang penggunaan toolkit:

  • Artikel Menengah Tentang Penggunaan V1.0.x
  • Dev.to artikel tentang penggunaan v1.0.x

9. Kontributor

Memperluas
Informasi Tambahan
Aplikasi Terkait
Direkomendasikan untuk Anda
Informasi Terkait Semua