Giới thiệu

Khi API của bạn phát triển, việc thay đổi không thể tránh khỏi. Việc giới thiệu phiên bản API đảm bảo rằng khách hàng của bạn tiếp tục hoạt động mà không bị gián đoạn trong khi bạn giới thiệu các tính năng và cải tiến mới.

Hướng dẫn này sẽ bao gồm cách triển khai phiên bản API trong .NET Web API với các ví dụ thực tiễn, bao gồm cách tiếp cận BaseApiController cho cấu hình tập trung.

Tại sao cần phiên bản API?

Tính tương thích ngược

• Khách hàng cũ vẫn có thể sử dụng các phiên bản trước.
• Giảm thiểu rủi ro cho các ứng dụng đang hoạt động.

Cập nhật mượt mà

• Bạn có thể giới thiệu các endpoint mới mà không làm hỏng chức năng hiện tại.
• Giúp duy trì sự ổn định cho API.

Giao tiếp rõ ràng

• Khách hàng biết họ đang sử dụng phiên bản nào.
• Giúp dễ dàng quản lý các thay đổi và thông báo.

Quản lý vòng đời tốt hơn

• Dễ dàng loại bỏ các phiên bản cũ dần dần.
• Tạo điều kiện cho việc bảo trì và nâng cấp.

Bước 1: Thêm gói NuGet cần thiết

dotnet add package Microsoft.AspNetCore.Mvc.Versioning

Gói này cung cấp các công cụ để phiên bản hóa API của bạn thông qua chuỗi truy vấn, tiêu đề hoặc đoạn URL.

Bước 2: Cấu hình phiên bản trong Program.cs

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();

// Thêm phiên bản API
builder.Services.AddApiVersioning(options =>
{
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new Microsoft.AspNetCore.Mvc.ApiVersion(1, 0);
    options.ReportApiVersions = true; // Trả về các phiên bản API trong tiêu đề phản hồi
});

var app = builder.Build();

app.MapControllers();
app.Run();

Bước 3: Tạo BaseApiController

Một BaseApiController có thể giữ các cấu hình, thuộc tính và phương thức trợ giúp chung cho tất cả các controller phiên bản.

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
public abstract class BaseApiController : ControllerBase
{
    protected IActionResult ApiResponse(object data, int statusCode = 200)
    {
        return StatusCode(statusCode, new
        {
            Status = statusCode,
            Data = data,
            Version = HttpContext.GetRequestedApiVersion()?.ToString()
        });
    }
}

Tất cả các controller phiên bản của bạn bây giờ có thể kế thừa từ controller cơ sở này để đảm bảo hành vi nhất quán.

Bước 4: Phiên bản hóa các controller sử dụng BaseApiController

[ApiVersion("1.0")]
public class ProductsController : BaseApiController
{
    [HttpGet]
    public IActionResult Get() => ApiResponse(new[] { "Sản phẩm 1", "Sản phẩm 2" });
}

[ApiVersion("2.0")]
public class ProductsV2Controller : BaseApiController
{
    [HttpGet]
    public IActionResult Get() => ApiResponse(new[] { "Sản phẩm A", "Sản phẩm B", "Sản phẩm C" });
}

Điều này giúp mã của bạn DRY (Don't Repeat Yourself) và tập trung hóa logic phiên bản.

Bước 5: Phiên bản hóa dựa trên chuỗi truy vấn và tiêu đề

Ví dụ chuỗi truy vấn:

GET /api/orders?api-version=1.0
GET /api/orders?api-version=2.0

Cấu hình dựa trên tiêu đề trong Program.cs:

builder.Services.AddApiVersioning(options =>
{
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.ApiVersionReader = new HeaderApiVersionReader("x-api-version");
    options.ReportApiVersions = true;
});

Khách hàng bây giờ có thể thiết lập tiêu đề:

x-api-version: 2.0

Bước 6: Ngừng hỗ trợ các phiên bản

[ApiVersion("1.0", Deprecated = true)]
public class OldController : BaseApiController
{
    [HttpGet]
    public IActionResult Get() => ApiResponse("Phiên bản này đã ngừng hỗ trợ");
}

Tiêu đề sẽ chỉ ra việc ngừng hỗ trợ.

Bước 7: Tích hợp Swagger cho các API phiên bản

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "API v1", Version = "v1" });
    options.SwaggerDoc("v2", new Microsoft.OpenApi.Models.OpenApiInfo { Title = "API v2", Version = "v2" });
});

var app = builder.Build();
app.UseSwagger();
app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "API v1");
    options.SwaggerEndpoint("/swagger/v2/swagger.json", "API v2");
});

Tổng kết

Việc sử dụng BaseApiController giúp tập trung hóa logic chung, giữ cho các controller DRY, và làm cho việc quản lý phiên bản API trở nên sạch sẽ hơn. Kết hợp với việc phiên bản hóa qua URL, chuỗi truy vấn hoặc tiêu đề và tích hợp Swagger, cách tiếp cận này cung cấp một cấu trúc API linh hoạt và dễ bảo trì trong .NET.

Các thực tiễn tốt nhất

• Luôn duy trì phiên bản API khi giới thiệu các thay đổi lớn.
• Thông báo rõ ràng cho khách hàng về các phiên bản cũ sắp ngừng hỗ trợ.

Lỗi thường gặp

• Không cấu hình đúng phiên bản API dẫn đến lỗi không tìm thấy endpoint.
• Quên kiểm tra phiên bản khi phát triển mới.

Mẹo hiệu suất

• Sử dụng bộ nhớ cache cho các phiên bản API cũ để giảm tải cho server.
• Hạn chế số lượng phiên bản API đang hoạt động cùng lúc để dễ dàng quản lý.

Câu hỏi thường gặp (FAQ)

1. Tại sao tôi cần phiên bản hóa API?
Phiên bản hóa cho phép bạn phát triển API mà không làm gián đoạn dịch vụ cho khách hàng hiện tại.

2. Tôi có thể sử dụng nhiều phương pháp phiên bản hóa cùng một lúc không?
Có, bạn có thể sử dụng chuỗi truy vấn, tiêu đề và đoạn URL cùng nhau để linh hoạt hơn trong việc quản lý phiên bản.

3. Làm thế nào để biết phiên bản API nào đang được sử dụng?
Bạn có thể kiểm tra tiêu đề phản hồi hoặc sử dụng Swagger để xem các phiên bản có sẵn.