.NET REST API 中的序列化和反序列化

设计强大的 API 的一个关键方面是能够以各种格式返回响应，以满足不同的客户端需求。在 API 的上下文中，序列化和反序列化对于客户端和服务器之间的数据交换至关重要。当客户端向 API 发出请求时，它通常需要向服务器发送数据（例如 JSON）。服务器将此数据反序列化为它可以处理的对象。当服务器响应时，它会将对象序列化回客户端可以理解的格式（例如，JSON、XML）。

序列化是将对象转换为易于存储或传输的格式的过程。这可能涉及将对象转换为字节流、JSON 字符串、XML 文档或其他格式。序列化可以将对象的状态保存到文件中，通过网络发送对象，或将其存储在数据库中。

反序列化是相反的过程。它涉及将数据从存储或传输的格式转换回对象。这允许使用其原始状态和数据重建对象。

API 可以根据需求和客户端的偏好返回各种类型的数据格式。以下是 API 可以返回的一些常见数据类型：

HTTP本身并不规定数据如何在格式上在客户端和服务器之间传递;它与所使用的内容类型和编码无关。JSON 是一种被广泛接受的现代 Web API 数据交换格式，因为它具有简单性、可读性以及与 JavaScript 和许多其他编程语言的易用性。

以下是 HTTP 请求和响应中通常如何处理 JSON 数据：

HTTP 请求：

• Content-Type Header：当客户端向服务器发送 JSON 数据时（例如，在 POST 或 PUT 请求中），它包含一个指定 .此标头告诉服务器请求正文包含 JSON 数据。Content-Typeapplication/json
• 请求正文：JSON 数据本身作为 HTTP 请求的正文发送。它是一个符合 JSON 格式的纯文本字符串，除非有特定的应用程序级要求或约束，否则不需要以 base64 编码。

HTTP 响应：

• Content-Type Header：当服务器使用 JSON 数据进行响应时，它会在响应中包含一个指定 .此标头向客户端指示响应正文包含 JSON 数据。Content-Typeapplication/json
• 响应正文：JSON 数据作为 HTTP 响应的正文返回。同样，它是一个符合 JSON 格式的纯文本字符串。

编码问题：

• Base64 编码：当您需要通过基于文本的协议（如 HTTP ）传输二进制数据（如图像或文件）时，通常使用 Base64 编码。JSON 基于文本，由 UTF-8 编码字符组成，其核心功能不需要 base64 编码。它以原始文本格式按原样传输。
• 特定于应用程序的需求：有时，应用程序可能出于特定原因需要以 base64 格式编码 JSON 数据，例如在某些安全上下文中或与需要二进制安全传输的系统集成时。但是，这不是 Web API 中典型 JSON 数据交换的标准做法。

在 .NET 中，在中间件中配置序列化涉及设置适当的序列化程序和格式化程序来处理各种数据格式。以下是在 .NET 6 中执行此操作的方法。

在 .NET 中间件中配置序列化的分步指南

使用 System.Text.Json 进行1. JSON序列化

System.Text.Json是 .NET Core 和 .NET 6 中的默认 JSON 序列化程序。它以其性能和低内存使用率而闻名。

2. JSON 使用 Newtonsoft.Json 进行序列化

Newtonsoft.Json（也称为 Json.NET）是用于 .NET 的常用 JSON 框架。它具有高度的通用性，并因其广泛的功能而被广泛使用。我们需要添加 nuget 包 Microsoft.AspNetCore.Mvc.NewtonsoftJson，并在 .net 中间件中配置它，如下所示

var builder = WebApplication.CreateBuilder(args);  

  

builder.Services.AddControllers()  

    .AddNewtonsoftJson();  

  

var app = builder.Build();  

  

if (app.Environment.IsDevelopment())  

{  

    app.UseDeveloperExceptionPage();  

}  

  

app.UseHttpsRedirection();  

app.UseAuthorization();  

app.MapControllers();  

app.Run();

3. XML序列化

对于 XML 序列化，您需要将 XML 格式化程序添加到 API 配置中。我们需要 dotnet 添加 nuget 包和配置 Microsoft.AspNetCore.Mvc.Formatters.Xml

var builder = WebApplication.CreateBuilder(args);  

  

// Add services to the container.  

builder.Services.AddControllers()  

    .AddXmlSerializerFormatters(); // Add XML support  

  

var app = builder.Build();  

  

if (app.Environment.IsDevelopment())  

{  

    app.UseDeveloperExceptionPage();  

}  

  

app.UseHttpsRedirection();  

app.UseAuthorization();  

app.MapControllers();  

app.Run();

4. 协议缓冲区 （Protobuf）

协议缓冲区用于高效的数据序列化，适用于性能关键型应用程序。我们需要添加包 Google.Protobuf 和 Grpc.AspNetCore 以及处理请求和响应的控制器，并将其配置为支持 JSON 和 XML 序列化。

var builder = WebApplication.CreateBuilder(args);  

builder.Services.AddGrpc();  

builder.Services.AddControllers();  

  

var app = builder.Build();  

if (app.Environment.IsDevelopment())  

{  

    app.UseDeveloperExceptionPage();  

}  

  

app.UseHttpsRedirection();  

app.UseRouting();  

app.UseAuthorization();

在 .NET 6 中，可以将中间件配置为支持多种序列化格式，例如 XML 和 JSON。让我们看看下面的代码，以同时使用 XML 序列化和 Newtonsoft.Json 序列化。

var builder = WebApplication.CreateBuilder(args);  

  

builder.Services.AddControllers()  

    .AddNewtonsoftJson() // Add Newtonsoft.Json support  

    .AddXmlSerializerFormatters(); // Add XML support  

  

var app = builder.Build();  

if (app.Environment.IsDevelopment())  

{  

    app.UseDeveloperExceptionPage();  

}  

app.UseHttpsRedirection();  

app.UseAuthorization();  

app.MapControllers();  

app.Run();

[ApiController]

[Route("api/[controller]")]

public class OrderController : ControllerBase

{

     [HttpPost]

    [Produces("application/json", "application/xml")]

    public IActionResult CreateOrder()

    {

        var contentType = Request.ContentType;



        if (contentType.Contains("application/json"))

        {

            using var reader = new StreamReader(Request.Body);

            var jsonString = reader.ReadToEnd();

            var order = JsonConvert.DeserializeObject<Order>(jsonString);



            if (order == null)

            {

                return BadRequest();

            }



            return Ok(order); // Return the created order in JSON

        }

        else if (contentType.Contains("application/xml"))

        {

            var serializer = new XmlSerializer(typeof(Order));

            using var reader = new StreamReader(Request.Body);

            var order = (Order)serializer.Deserialize(reader);

            if (order == null)

            {

                return BadRequest();

            }

            return Ok(order); // Return the created order in XML

        }

        else

        {

            return UnsupportedMediaType();

        }

    }

}

结论

在 .NET 中间件中配置序列化涉及选择适当的序列化程序并设置必要的格式化程序。通过理解和利用 System.Text.Json、Newtonsoft.Json、XML 格式化程序和协议缓冲区等库，您可以确保您的 API 有效地处理各种数据格式，满足不同的客户端需求并优化性能。这些配置和库使开发人员能够创建多功能且强大的 API，这些 API 可以有效地序列化和反序列化数据，从而增强互操作性和性能。

本文章转载微信公众号@dotNET跨平台