WebAPI 数据序列化

一、数据序列化

数据序列化用于将对象转换为传输格式（如 JSON、XML）。TouchSocket.WebApi 支持多种序列化格式。

1.1 默认序列化器

框架默认支持以下格式化器，根据 Accept 请求头自动选择：

• application/json 或 text/json：使用 JSON 格式化（默认：System.Text.Json）
• application/xml 或 text/xml：使用 XML 格式
• text/plain：使用文本格式化

1.2 配置序列化器

在添加 WebApi 插件时，可以配置序列化器：

🔄 正在加载代码...

1.3 使用 Newtonsoft.Json

TouchSocket.WebApi 默认不支持 Newtonsoft.Json 序列化。如果需要，可以自定义 Newtonsoft.Json 的配置，可以实现自定义的序列化器：

1.3.1 定义 Newtonsoft.Json 序列化器

首先需要实现一个基于 Newtonsoft.Json 的序列化器：

🔄 正在加载代码...

1.3.2 配置使用 Newtonsoft.Json

然后在配置中添加该序列化器：

🔄 正在加载代码...

提示

Newtonsoft.Json 是一个功能强大的 JSON 序列化库，支持丰富的配置选项，如日期格式化、null 值处理、循环引用处理等。但需要注意的是，Newtonsoft.Json 不支持 AOT 编译。

WebApiServer

GiteeGitHub

1.4 使用 System.Text.Json

对于需要 AOT 支持的场景，推荐使用 System.Text.Json：

🔄 正在加载代码...

提示

System.Text.Json 是 .NET 内置的 JSON 序列化库，性能优异且完整支持 AOT 编译。如果项目需要 AOT 支持，建议使用 System.Text.Json 而不是 Newtonsoft.Json。

1.5 自定义序列化器

可以实现自定义的序列化器：

🔄 正在加载代码...

二、AOT 支持

TouchSocket.WebApi 完整支持 Native AOT 编译。

2.1 基础配置

在项目文件中启用AOT：

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    ...
    <PublishAot>true</PublishAot>
    <RuntimeIdentifier>win-x64</RuntimeIdentifier> <!-- 根据目标平台选择 -->
    <PublishTrimmed>true</PublishTrimmed>
  </PropertyGroup>
  ...
</Project>

2.2 JSON 序列化上下文

AOT 需要定义 JSON 序列化上下文：

🔄 正在加载代码...

提示

一般情况下，建议为所有需要序列化的类型创建上下文以确保兼容性。包括Rpc方法的返回类型、参数类型以及类中类等，一切可能被序列化的类型都应包含在上下文中。

2.3 配置序列化器

使用 System.Text.Json 并指定序列化上下文：

🔄 正在加载代码...

注意

AOT 场景下必须使用 System.Text.Json，不能使用 Newtonsoft.Json，因为 Newtonsoft.Json 不支持 AOT 编译。

2.4 服务注册

使用源生成器注册服务：

🔄 正在加载代码...

2.5 发布

使用以下命令发布 AOT 应用：

dotnet publish -c Release

生成的可执行文件体积小、启动快、无需运行时。

三、注意事项

3.1 序列化注意事项

1. 格式化器顺序：可以通过设置 Order 属性来控制格式化器的优先级
2. 内容协商：框架会根据请求的 Accept 头自动选择合适的格式化器
3. 自定义格式化器：实现 ISerializerFormatter<string, HttpContext> 接口即可添加自定义格式化器

3.2 AOT 注意事项

1. 避免反射：使用源生成器而不是反射
2. 序列化类型：所有序列化类型必须添加到 JsonSerializable 特性
3. 第三方库：确保所有依赖库支持 AOT