WebAPI 参数绑定
一、参数绑定
TouchSocket.WebApi 支持从多个来源获取参数。
1.1 默认参数绑定规则
WebAPI 会根据 HTTP 方法和参数类型自动选择绑定源：
GET 请求：
- 所有参数默认从 Query String 获取
POST 请求：
- 简单类型（int、string、DateTime 等）从 Query String 获取
- 复杂类型（自定义类、集合等）从 Request Body 获取
1.2 FromQuery - 从查询字符串
显式指定从 Query String 获取参数：
🔄 正在加载代码...
说明：
- 可以通过
Name属性自定义参数名 [FromQuery(Name = "aa")]将参数a映射到查询字符串的aa
访问示例：/ApiServer/SumFromQuery?aa=10&b=20
1.3 FromHeader - 从请求头
从 HTTP Header 获取参数：
🔄 正在加载代码...
请求示例：
GET /ApiServer/SumFromHeader
a: 10
b: 20
1.4 FromForm - 从表单
从表单数据获取参数：
🔄 正在加载代码...
请求示例：
GET /ApiServer/SumFromForm
Content-Type: application/x-www-form-urlencoded
a=10&b=20
1.5 FromBody - 从请求体
显式指定从 Request Body 获取参数（JSON 格式）：
🔄 正在加载代码...
请求示例：
POST /ApiServer/TestPost
Content-Type: application/json
{
"a": 10,
"b": 20
}
二、参数类型支持
2.1 基础类型
支持所有 C# 基础类型：
- 整数：
int,long,short,byte - 浮点：
double,float,decimal - 其他：
bool,string,DateTime,DateTimeOffset,Guid - 可空类型：
int?,DateTime?等
2.2 集合类型
支持数组和集合，通过重复参数名传递：
示例：
/api/sumarray?numbers=1&numbers=2&numbers=3
2.3 复杂对象
支持嵌套对象和复杂类型：
🔄 正在加载代码...
三、参数特性说明
3.1 FromQuery
- 用途：从 URL 查询字符串获取参数
- 支持 GET/POST：是
- 自定义名称：支持
Name属性
3.2 FromHeader
- 用途：从 HTTP 请求头获取参数
- 支持 GET/POST：是
- 自定义名称：支持
Name属性
3.3 FromForm
- 用途：从表单数据获取参数
- Content-Type：
application/x-www-form-urlencoded或multipart/form-data - 支持文件上传：是（multipart/form-data）
3.4 FromBody
- 用途：从请求体获取参数
- Content-Type：通常为
application/json - 序列化：使用配置的序列化器（JSON/XML）
四、常见场景
4.1 GET 请求获取简单参数
简单参数无需特性标注，自动从 Query 获取：
🔄 正在加载代码...
4.2 POST 请求获取对象
复杂对象自动从 Body 获取：
🔄 正在加载代码...
4.3 混合参数来源
同时从多个来源获取参数：
[WebApi(Method = HttpMethodType.Post)]
public string MixedParams(
[FromQuery] int id,
[FromHeader] string authorization,
[FromBody] MyClass data)
{
return $"ID: {id}, Data: {data.A + data.B}";
}
请求示例：
POST /apiserver/mixedparams?id=100
Authorization: Bearer token123
Content-Type: application/json
{
"a": 10,
"b": 20
}
五、注意事项
5.1 参数名称匹配
- 参数名称不区分大小写
- Query 参数
?Name=Alice可以匹配参数string name
5.2 复杂类型序列化
- POST 的复杂对象默认使用 JSON 反序列化
- 可以通过配置更改序列化器（详见序列化文档）
5.3 必需参数与可选参数
- 使用可空类型或默认值定义可选参数：
public int Sum(int a, int b = 0) // b 是可选的
public string GetUser(int? id = null) // id 是可选的