C# WebApi 接口传参详解

在 ASP.NET Core WebApi 的开发中，接口无疑是开发过程中非常重要的一部分。而对于接口传参，我们不仅需要对参数的类型、名称进行规范处理，还需要对传参方式、数据格式进行深入的了解。

本文将从接口传参的基础开始详细讲解，包括传参方式、数据格式、传递对象类型等内容。

传参方式

在 ASP.NET Core WebApi 中，接口的传参方式主要有两种：

1. QueryString参数传递：通过在接口地址中携带参数，将参数作为请求的一部分传递给服务端。这种方式参数是以键值对的形式出现在URL地址中的，例如：

/api/user?id=123&name=john

客户端的请求URL会包含查询字符串?id=123&name=john，服务端接口可以根据查询字符串中的参数进行相关的处理。

1. Body参数传递：通过发送HTTP请求体中的数据传递参数，一般用于传递复杂的对象。这种方式一般使用POST、PUT等请求方法发送，参数数据在请求体中以一定格式（如JSON、XML）进行发送。

数据格式

接口参数的数据格式，指的是传参时所使用的具体规范。常见的数据格式主要有：

1. x-www-form-urlencoded：键值对的形式出现在请求体中，变量之间以&符号分隔，如field1=value1&field2=value2。这种格式传递的数据通常比较简单，如表单等。

2. multipart/form-data：常见于文件上传，可以携带二进制文件数据。该格式请求头包含Content-Type: multipart/form-data， 请求体内容比较复杂，需要对表单用分隔符进行拆分。

3. application/json：JSON字符串作为请求体发送给服务端。该格式在处理复杂数据对象时使用较多。

4. application/xml：XML数据作为请求体发送给服务端。

传递对象类型

在 WebApi 中，我们一般通过DTO（Data Transfer Object）的形式进行数据传递，DTO可以理解为服务端与客户端之间传递的数据模型。我们可以使用简单的POCO(Plain Old CLR Object)类定义DTO，同时使用属性、字段等进行数据封装。

下面是一个示例：

public class UserInfoDto
{
    public string Name { get; set; }
    public int Age { get; set; }
}

客户端可以通过传递JSON字符串或URL参数的形式将UserInfoDto对象传递给服务端接口。

例如：

POST /api/user HTTP/1.1
Host: api.example.com
Content-Type: application/json
Content-Length: 53

{"Name":"john","Age":23}

服务端接口可以使用以下代码进行接收：

[HttpPost]
public IActionResult Post([FromBody] UserInfoDto userInfoDto)
{
    // do something with userInfoDto
}

示例说明

下面是一个URL参数传递的示例。

假设我们要通过 /api/user 接口查询用户信息，查询参数包括Name、Age、Gender三个字段。我们可以将查询参数组成QueryString的形式进行传递。

[HttpGet]
[Route("api/user")]
public IActionResult GetUserInfo([FromQuery] string name, int age, GenderEnum gender)
{
    // do something
}

示例2是一个JSON参数传递的示例。

假设我们要通过 /api/user 接口创建新用户，客户端需要向服务端传递一个UserInfoDto对象，包括Name、Age两个字段。

[HttpPost]
[Route("api/user")]
public IActionResult AddUser([FromBody] UserInfoDto userInfoDto)
{
    // do something
}

客户端可以使用以下代码进行请求。

var userInfoDto = new UserInfoDto
{
    Name = "john",
    Age = 23
};
var jsonStr = JsonSerializer.Serialize(userInfoDto);
var content = new StringContent(jsonStr, Encoding.UTF8, "application/json");

using var httpClient = new HttpClient();
var response = await httpClient.PostAsync("https://api.example.com/api/user", content);