Κατά την ανάπτυξη API, πρέπει να έχετε κατά νου ένα πράγμα: Η αλλαγή είναι αναπόφευκτη. Όταν το API σας έχει φτάσει σε ένα σημείο όπου πρέπει να προσθέσετε περισσότερες ευθύνες, θα πρέπει να εξετάσετε το ενδεχόμενο να εκδώσετε το API σας. Ως εκ τούτου, θα χρειαστείτε μια στρατηγική εκδόσεων.
Υπάρχουν πολλές προσεγγίσεις για την έκδοση API, και καθεμία από αυτές έχει τα πλεονεκτήματα και τα μειονεκτήματά της. Αυτό το άρθρο θα συζητήσει τις προκλήσεις της έκδοσης API και πώς μπορείτε να εργαστείτε με το πακέτο ASP.NET Core MVC Versioning της Microsoft σε έκδοση RESTful API που είναι ενσωματωμένα στον πυρήνα ASP.NET. Μπορείτε να διαβάσετε περισσότερα για την έκδοση API Ιστού στο προηγούμενο άρθρο μου εδώ.
Δημιουργήστε ένα έργο ASP.NET Core 3.1 API
Πρώτα απ 'όλα, ας δημιουργήσουμε ένα έργο ASP.NET Core στο Visual Studio. Ας υποθέσουμε ότι το Visual Studio 2019 είναι εγκατεστημένο στο σύστημά σας, ακολουθήστε τα βήματα που περιγράφονται παρακάτω για να δημιουργήσετε ένα νέο έργο ASP.NET Core στο Visual Studio.
- Εκκινήστε το Visual Studio IDE.
- Κάντε κλικ στο "Δημιουργία νέου έργου".
- Στο παράθυρο "Δημιουργία νέου έργου", επιλέξτε "ASP.NET Core Web Application" από τη λίστα των προτύπων που εμφανίζονται.
- Κάντε κλικ στο Επόμενο.
- Στο παράθυρο "Διαμόρφωση του νέου έργου" που εμφανίζεται στη συνέχεια, καθορίστε το όνομα και την τοποθεσία για το νέο έργο.
- Κάντε κλικ στο Δημιουργία.
- Στο παράθυρο "Δημιουργία νέας εφαρμογής ASP.NET Core Web", επιλέξτε .NET Core ως χρόνο εκτέλεσης και ASP.NET Core 3.1 (ή μεταγενέστερη έκδοση) από την αναπτυσσόμενη λίστα στην κορυφή. Θα χρησιμοποιήσω το ASP.NET Core 3.1 εδώ.
- Επιλέξτε "API" ως πρότυπο έργου για να δημιουργήσετε μια νέα εφαρμογή ASP.NET Core API.
- Βεβαιωθείτε ότι τα πλαίσια ελέγχου "Ενεργοποίηση υποστήριξης Docker" και "Διαμόρφωση για HTTPS" δεν είναι επιλεγμένα, καθώς δεν θα χρησιμοποιούμε αυτές τις δυνατότητες εδώ.
- Βεβαιωθείτε ότι ο Έλεγχος ταυτότητας έχει οριστεί ως "Χωρίς έλεγχο ταυτότητας", καθώς ούτε θα χρησιμοποιούμε έλεγχο ταυτότητας.
- Κάντε κλικ στο Δημιουργία.
Αυτό θα δημιουργήσει ένα νέο έργο ASP.NET Core API στο Visual Studio. Επιλέξτε το φάκελο Controllers solution στο παράθυρο Solution Explorer και κάντε κλικ στο "Add -> Controller ..." για να δημιουργήσετε ένα νέο χειριστήριο με το όνομα DefaultController.
Αντικαταστήστε τον πηγαίο κώδικα της κλάσης DefaultController με τον ακόλουθο κώδικα.
[Διαδρομή ("api / [ελεγκτής]")] [ApiController]
δημόσια τάξη DefaultController: ControllerBase
{
συμβολοσειρά [] συγγραφείς = νέα συμβολοσειρά []
{"Joydip Kanjilal", "Steve Smith", "Stephen Jones"}.
[HttpGet]
δημόσια IEnumerable Get ()
{
συγγραφείς επιστροφής;
}
}
Θα χρησιμοποιήσουμε αυτόν τον ελεγκτή στις επόμενες ενότητες αυτού του άρθρου.
Για να εφαρμόσετε την έκδοση API στο ASP.NET Core πρέπει να κάνετε τα εξής:
- Εγκαταστήστε το πακέτο ASP.NET Core MVC Versioning.
- Ρύθμιση παραμέτρων API στην κλάση εκκίνησης.
- Σχολιάστε τους ελεγκτές και τις ενέργειες με τα κατάλληλα χαρακτηριστικά.
Εγκαταστήστε το πακέτο ASP.NET Core MVC Versioning
Το ASP.NET Core παρέχει υποστήριξη για εκδόσεις API εκτός συσκευασίας. Για να αξιοποιήσετε την έκδοση API, το μόνο που χρειάζεται να κάνετε είναι να εγκαταστήσετε το πακέτο Microsoft.AspNetCore.Mvc.Versioning από το NuGet. Μπορείτε να το κάνετε είτε μέσω του διαχειριστή πακέτων NuGet στο Visual Studio 2019 IDE είτε εκτελώντας την ακόλουθη εντολή στην κονσόλα διαχειριστή πακέτων NuGet:
Εγκατάσταση πακέτου Microsoft.AspNetCore.Mvc.Versioning
Σημειώστε ότι εάν χρησιμοποιείτε ASP.NET Web API, θα πρέπει να προσθέσετε το πακέτο Microsoft.AspNet.WebApi.Versioning.
Ρύθμιση παραμέτρων API στο ASP.NET Core
Τώρα που το απαραίτητο πακέτο για την έκδοση του API σας έχει εγκατασταθεί στο έργο σας, μπορείτε να διαμορφώσετε την έκδοση API στη μέθοδο ConfigureServices της κλάσης εκκίνησης. Το παρακάτω απόσπασμα κώδικα δείχνει πώς μπορεί να επιτευχθεί αυτό.
public void ConfigureServices (υπηρεσίες IServiceCollection){
υπηρεσίες.AddControllers ();
υπηρεσίες.AddApiVersioning ();
}
Όταν υποβάλλετε ένα αίτημα Λήψης στο API σας, θα εμφανιστεί το σφάλμα που φαίνεται στο Σχήμα 1.
Για να επιλύσετε αυτό το σφάλμα, μπορείτε να καθορίσετε την προεπιλεγμένη έκδοση κατά την προσθήκη των υπηρεσιών εκδόσεων API στο κοντέινερ. Ίσως θέλετε επίσης να χρησιμοποιήσετε μια προεπιλεγμένη έκδοση εάν μια έκδοση δεν καθορίζεται στο αίτημα. Το παρακάτω απόσπασμα κώδικα δείχνει πώς μπορείτε να ορίσετε μια προεπιλεγμένη έκδοση ως 1.0 χρησιμοποιώντας την ιδιότητα AssumeDefaultVersionWhenUnspecified εάν οι πληροφορίες έκδοσης δεν είναι διαθέσιμες στο αίτημα.
services.AddApiVersioning (config =>{
config.DefaultApiVersion = νέο ApiVersion (1, 0);
config.AssumeDefaultVersionWhenUnspecified = true;
});
Σημειώστε πώς μεταδίδονται η κύρια έκδοση και η δευτερεύουσα έκδοση στον κατασκευαστή της κλάσης ApiVersion κατά τη στιγμή της εκχώρησης της προεπιλεγμένης έκδοσης. Η ιδιότητα AssumeDefaultVersionWhenUnspecified μπορεί να περιέχει είτε αληθείς είτε ψευδείς τιμές. Εάν είναι αλήθεια, η προεπιλεγμένη έκδοση που καθορίζεται κατά τη ρύθμιση παραμέτρων του API θα χρησιμοποιηθεί εάν δεν υπάρχουν διαθέσιμες πληροφορίες έκδοσης.
Ο πλήρης πηγαίος κώδικας της μεθόδου ConfigureServices δίνεται παρακάτω για την αναφορά σας.
public void ConfigureServices (υπηρεσίες IServiceCollection){
υπηρεσίες.AddControllers ();
services.AddApiVersioning (config =>
{
config.DefaultApiVersion = νέο ApiVersion (1, 0);
config.AssumeDefaultVersionWhenUnspecified = true;
});
}
Εφόσον δεν έχετε καθορίσει πληροφορίες έκδοσης, όλα τα τελικά σημεία θα έχουν την προεπιλεγμένη έκδοση 1.0.
Αναφέρετε όλες τις υποστηριζόμενες εκδόσεις του API σας
Ίσως θέλετε να ενημερώσετε τους πελάτες του API για όλες τις υποστηριζόμενες εκδόσεις. Για να το κάνετε αυτό, θα πρέπει να επωφεληθείτε από την ιδιότητα ReportApiVersions όπως φαίνεται στο απόσπασμα κώδικα που δίνεται παρακάτω.
services.AddApiVersioning (config =>{
config.DefaultApiVersion = νέο ApiVersion (1, 0);
config.AssumeDefaultVersionWhenUnspecified = true;
config.ReportApiVersions = true;
});
Χρησιμοποιήστε εκδόσεις στον ελεγκτή και στις μεθόδους δράσης
Τώρα ας προσθέσουμε μερικές υποστηριζόμενες εκδόσεις στον ελεγκτή μας χρησιμοποιώντας χαρακτηριστικά όπως φαίνεται στο απόσπασμα κώδικα που δίνεται παρακάτω.
[Διαδρομή ("api / [ελεγκτής]")] [ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1")]
[ApiVersion ("2.0")]
δημόσια τάξη DefaultController: ControllerBase
{
συμβολοσειρά [] συγγραφείς = νέα συμβολοσειρά []
{"Joydip Kanjilal", "Steve Smith", "Anand John"}.
[HttpGet]
δημόσια IEnumerable Get ()
{
συγγραφείς επιστροφής;
}
}
Όταν υποβάλλετε ένα αίτημα Λήψης από έναν πελάτη HTTP όπως ο Ταχυδρόμος, μπορείτε να αναφέρετε τις εκδόσεις.
Μπορείτε επίσης να αναφέρετε τις καταργημένες εκδόσεις. Για να το κάνετε αυτό, θα πρέπει να μεταβιβάσετε μια επιπλέον παράμετρο στη μέθοδο ApiVersion όπως φαίνεται στο απόσπασμα κώδικα που δίνεται παρακάτω.
[ApiVersion ("1.0", Καταργήθηκε = αληθινό)]Αντιστοίχιση σε μια συγκεκριμένη έκδοση μιας μεθόδου δράσης
Υπάρχει ένα άλλο σημαντικό χαρακτηριστικό που ονομάζεται MapToApiVersion. Μπορείτε να το χρησιμοποιήσετε για να αντιστοιχίσετε μια συγκεκριμένη έκδοση μιας μεθόδου δράσης. Το παρακάτω απόσπασμα κώδικα δείχνει πώς μπορεί να επιτευχθεί αυτό.
[HttpGet ("{id}")][MapToApiVersion ("2.0")]
δημόσια συμβολοσειρά Get (int id)
{
συγγραφείς επιστροφής [id];
}
Πλήρες παράδειγμα εκδόσεων API στο ASP.NET Core
Εδώ είναι ο πλήρης πηγαίος κώδικας του DefaultController για αναφορά σας.
[Διαδρομή ("api / [ελεγκτής]")][ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1")]
[ApiVersion ("2.0")]
δημόσια τάξη DefaultController: ControllerBase
{
συμβολοσειρά [] συγγραφείς = νέα συμβολοσειρά []
{"Joydip Kanjilal", "Steve Smith", "Stephen Jones"}.
[HttpGet]
δημόσια IEnumerable Get ()
{
συγγραφείς επιστροφής;
}
[HttpGet ("{id}")]
[MapToApiVersion ("2.0")]
δημόσια συμβολοσειρά Get (int id)
{
συγγραφείς επιστροφής [id];
}
}
Στρατηγικές εκδόσεων API στο ASP.NET Core
Υπάρχουν διάφοροι τρόποι με τους οποίους μπορείτε να εκδώσετε το API σας στο ASP.NET Core. Σε αυτήν την ενότητα θα διερευνήσουμε καθένα από αυτά.
Περάστε τις πληροφορίες έκδοσης ως παραμέτρους QueryString
Σε αυτήν την περίπτωση, συνήθως διαβιβάζετε τις πληροφορίες έκδοσης ως μέρος της συμβολοσειράς ερωτήματος όπως φαίνεται στη διεύθυνση URL που δίνεται παρακάτω.
//localhost:25718/api/default?api-version=1.0
Διαβιβάστε πληροφορίες έκδοσης στις κεφαλίδες HTTP
Εάν πρόκειται να μεταβιβάσετε πληροφορίες έκδοσης στις κεφαλίδες HTTP, θα πρέπει να τις ρυθμίσετε στη μέθοδο ConfigureServices όπως φαίνεται στο απόσπασμα κώδικα που δίνεται παρακάτω.
services.AddApiVersioning (config =>{
config.DefaultApiVersion = νέο ApiVersion (1, 0);
config.AssumeDefaultVersionWhenUnspecified = true;
config.ReportApiVersions = true;
config.ApiVersionReader = νέο HeaderApiVersionReader ("api-version");
});
Μόλις ρυθμιστεί, μπορείτε να καλέσετε μια μέθοδο δράσης που σχετίζεται με μια συγκεκριμένη έκδοση του API, όπως φαίνεται στο σχήμα 3.
Διαβιβάστε τις πληροφορίες έκδοσης στη διεύθυνση URL
Μια άλλη μέθοδος μετάδοσης πληροφοριών έκδοσης είναι η μετάδοση πληροφοριών έκδοσης ως μέρος της διαδρομής. Αυτός είναι ο απλούστερος τρόπος έκδοσης του API σας, αλλά υπάρχουν ορισμένες προειδοποιήσεις. Πρώτα απ 'όλα, εάν χρησιμοποιείτε αυτήν τη στρατηγική, οι πελάτες σας θα πρέπει να ενημερώνουν τη διεύθυνση URL κάθε φορά που κυκλοφορεί μια νέα έκδοση του API. Κατά συνέπεια, αυτή η προσέγγιση παραβιάζει μια θεμελιώδη αρχή του REST που δηλώνει ότι η διεύθυνση URL ενός συγκεκριμένου πόρου δεν πρέπει ποτέ να αλλάζει.
Για να εφαρμόσετε αυτήν τη στρατηγική έκδοσης, θα πρέπει να καθορίσετε τις πληροφορίες διαδρομής στον ελεγκτή σας όπως φαίνεται παρακάτω.
[Διαδρομή ("api / v {version: apiVersion} / [controller]")]Η ακόλουθη λίστα κωδικών δείχνει πώς μπορείτε να το ρυθμίσετε στην τάξη του ελεγκτή σας.
[Διαδρομή ("api / v {version: apiVersion} / [controller]")][ApiController]
[ApiVersion ("1.0")]
[ApiVersion ("1.1")]
δημόσια τάξη DefaultController: ControllerBase
{
συμβολοσειρά [] συγγραφείς = νέα συμβολοσειρά []
{"Joydip Kanjilal", "Steve Smith", "Stephen Jones"}.
[HttpGet]
δημόσια IEnumerable Get ()
{
συγγραφείς επιστροφής;
}
[HttpGet ("{id}")]
[MapToApiVersion ("2.0")]
δημόσια συμβολοσειρά Get (int id)
{
συγγραφείς επιστροφής [id];
}
}
Δείτε πώς μπορείτε να καλέσετε το προεπιλεγμένο HTTP για να λάβετε τη μέθοδο της κλάσης DefaultController.
//localhost:25718/api/v1.0/προεπιλογή
Για να καλέσετε την άλλη μέθοδο HTTP GET, δηλαδή αυτή που αποδέχεται μια παράμετρο, καθορίστε τα ακόλουθα είτε στο πρόγραμμα περιήγησης ιστού είτε σε ένα πρόγραμμα-πελάτη HTTP όπως το Postman
//localhost:25718/api/v2.0/default/1
Καταργήστε μία ή περισσότερες εκδόσεις του API σας
Ας υποθέσουμε ότι έχετε πολλές εκδόσεις του API σας, αλλά θέλετε να καταργήσετε μία ή περισσότερες από αυτές. Μπορείτε να το κάνετε εύκολα - απλώς πρέπει να καθορίσετε την ιδιότητα Καταργήθηκε της κλάσης ApiVersionAttribute σε true, όπως φαίνεται στο απόσπασμα κώδικα που δίνεται παρακάτω.
[ApiController][ApiVersion ("1.0")]
[ApiVersion ("1.1", Καταργήθηκε = true)]
[ApiVersion ("2.0")]
δημόσια τάξη DefaultController: ControllerBase
{
// Συνήθης κωδικός
}
Η έκδοση API στο ASP.NET Core είναι πλέον απρόσκοπτη χάρη στην εισαγωγή του πακέτου Microsoft.AspNetCore.Mvc.Versioning. Υπάρχουν διάφοροι τρόποι για να εκδώσετε το API σας - απλώς πρέπει να αποφασίσετε την καλύτερη στρατηγική με βάση τις απαιτήσεις σας. Μπορείτε επίσης να χρησιμοποιήσετε πολλά σχήματα εκδόσεων για το API σας. Αυτό προσθέτει μεγάλη ευελιξία καθώς οι πελάτες μπορούν να επιλέξουν οποιοδήποτε από τα υποστηριζόμενα σχήματα εκδόσεων.
Πώς να κάνετε περισσότερα στο ASP.NET Core:
- Τρόπος χρήσης αντικειμένων μεταφοράς δεδομένων στο ASP.NET Core 3.1
- Πώς να χειριστείτε 404 σφάλματα στο ASP.NET Core MVC
- Πώς να χρησιμοποιήσετε την ένεση εξάρτησης σε φίλτρα δράσης στο ASP.NET Core 3.1
- Πώς να χρησιμοποιήσετε το μοτίβο επιλογών στο ASP.NET Core
- Τρόπος χρήσης δρομολόγησης τελικού σημείου στο ASP.NET Core 3.0 MVC
- Τρόπος εξαγωγής δεδομένων στο Excel στο ASP.NET Core 3.0
- Πώς να χρησιμοποιήσετε το LoggerMessage στο ASP.NET Core 3.0
- Πώς να στείλετε email στο ASP.NET Core
- Τρόπος καταγραφής δεδομένων σε SQL Server στον πυρήνα ASP.NET
- Πώς να προγραμματίσετε εργασίες χρησιμοποιώντας το Quartz.NET στο ASP.NET Core
- Πώς να επιστρέψετε δεδομένα από το ASP.NET Core Web API
- Πώς να μορφοποιήσετε δεδομένα απόκρισης στο ASP.NET Core
- Πώς να καταναλώσετε ένα ASP.NET Core Web API χρησιμοποιώντας το RestSharp
- Πώς να εκτελέσετε λειτουργίες ασύγχυσης χρησιμοποιώντας το Dapper
- Πώς να χρησιμοποιήσετε σημαίες χαρακτηριστικών στο ASP.NET Core
- Τρόπος χρήσης του χαρακτηριστικού FromServices στο ASP.NET Core
- Πώς να εργαστείτε με cookie στο ASP.NET Core
- Πώς να εργαστείτε με στατικά αρχεία στο ASP.NET Core
- Πώς να χρησιμοποιήσετε το Middle Rewriting URL στο ASP.NET Core
- Πώς να εφαρμόσετε περιορισμό ρυθμού στο ASP.NET Core
- Πώς να χρησιμοποιήσετε το Azure Application Insights στο ASP.NET Core
- Χρήση προηγμένων δυνατοτήτων NLog στο ASP.NET Core
- Πώς να χειριστείτε σφάλματα στο ASP.NET Web API
- Πώς να εφαρμόσετε τον παγκόσμιο χειρισμό εξαιρέσεων στο ASP.NET Core MVC
- Τρόπος χειρισμού μηδενικών τιμών στο ASP.NET Core MVC
- Προηγμένη έκδοση στο ASP.NET Core Web API
- Πώς να εργαστείτε με υπηρεσίες εργαζομένων στο ASP.NET Core
- Τρόπος χρήσης του API προστασίας δεδομένων στο ASP.NET Core
- Τρόπος χρήσης μεσαίου λογισμικού υπό όρους στο ASP.NET Core
- Τρόπος εργασίας με την κατάσταση συνεδρίας στον ASP.NET Core
- Πώς να γράψετε αποτελεσματικούς ελεγκτές στο ASP.NET Core
