Postman参数类型、功能、用途及 后端接口接收详解【接口调试工具】

三天不学习2025-08-25 12:07

文章目录

  • 前言🎀
  • [一、Query Params（查询参数）](#一、Query Params（查询参数）)
  • [二、Path Variables（路径参数）](#二、Path Variables（路径参数）)
    • [2.1 功能与用途](#2.1 功能与用途)
    • [2.2 示例URL：](#2.2 示例URL：)
    • [2.3 .NET 8接口接收方式](#2.3 .NET 8接口接收方式)
  • 三、Body（请求体）
    • [1. form-data](#1. form-data)
    • [2. x-www-form-urlencoded](#2. x-www-form-urlencoded)
    • [3. raw (最常用的是JSON)](#3. raw (最常用的是JSON))
    • [4. binary](#4. binary)
  • 四、Headers（请求头）
    • [4.1 功能与用途](#4.1 功能与用途)
    • [4.2 .NET 8接口接收方式](#4.2 .NET 8接口接收方式)
  • 五、Authorization（授权参数）
    • [5.1 功能与用途](#5.1 功能与用途)
    • [5.2 .NET 8接口接收方式](#5.2 .NET 8接口接收方式)
  • ✅总结对比表
  • 结语🎯

前言🎀

作为一名API开发者和测试人员，Postman 无疑是你最亲密的伙伴之一。但你是否曾困惑于Query Params、Body、Headers 等各种参数类型该如何选择？后端又该如何正确接收这些参数？本文将彻底解决这些疑问，以.NET 8 Web API为例，为你详细解析 Postman 的各种参数类型。

一、Query Params（查询参数）

1.1功能与用途

查询参数附加在 URL 的末尾，以 ? 开始，多个参数用 & 分隔，格式为key=value 。它通常用于 GET 请求，向服务器传递非敏感的可选或过滤条件，如分页、排序、搜索关键字等。

1.2示例URL：

text 复制代码 
https://api.example.com/users?page=2&limit=10&sort=name&keyword=john

1.3 .NET 8接口接收方式

在 Controller 的 Action 方法中，直接使用方法的参数来接收。参数名需与 Query 中的 key 一致，.NET框架会自动完成绑定。

csharp 复制代码 
// GET: /api/users
[HttpGet]
public IActionResult GetUsers(
    [FromQuery] int page = 1,      // [FromQuery]属性显式声明，可省略
    [FromQuery] int limit = 20,    // 参数提供默认值
    string sort = "id",            // 参数名与Query key 'sort'匹配
    string keyword = null)         // 参数名与Query key 'keyword'匹配
{
    // 业务逻辑使用page, limit, sort, keyword进行查询
    return Ok($"Page: {page}, Limit: {limit}, SortBy: {sort}, Keyword: {keyword}");
}

二、Path Variables（路径参数）

2.1 功能与用途

路径参数是URL路径的一部分，用于唯一标识或定位一个资源。在 RESTful API 设计中非常常见。

2.2 示例URL：

text 复制代码 
https://api.example.com/users/123

（其中123就是路径参数，代表用户ID）

2.3 .NET 8接口接收方式

在路由模板中使用 {参数名} 占位符，并在 Action 方法参数中使用相同的名称来接收。

csharp 复制代码 
// GET: /api/users/{id}
[HttpGet("{id}")] // 路由模板中定义路径参数'id'
public IActionResult GetUserById(int id) // 参数名'id'必须与路由模板中的'{id}'一致
{
    var user = _userService.GetUser(id);
    if (user == null)
    {
        return NotFound();
    }
    return Ok(user);
}

三、Body（请求体）

Body 用于在请求中发送大量数据，通常在 POST、PUT、PATCH 请求中使用。Postman提供了多种Body格式。

1. form-data

功能与用途： 类似于HTML表单，允许发送键值对数据。它的特点是可以同时上传文本和文件。

.NET 8接口接收方式：

csharp 复制代码 
// POST: /api/upload
[HttpPost]
public async Task<IActionResult> UploadUserProfile(
    [FromForm] string userName,       // 接收文本字段
    [FromForm] IFormFile avatarFile)  // 接收文件字段
{
    if (avatarFile?.Length > 0)
    {
        var filePath = Path.Combine(_hostEnvironment.WebRootPath, avatarFile.FileName);
        using (var stream = System.IO.File.Create(filePath))
        {
            await avatarFile.CopyToAsync(stream);
        }
        return Ok(new { userName, Avatar = avatarFile.FileName });
    }
    return BadRequest("File is required.");
}

2. x-www-form-urlencoded

功能与用途： 发送键值对，但数据被编码成URL格式，只能发送文本，不能发送文件。

.NET 8接口接收方式：

csharp 复制代码 
// POST: /api/login
[HttpPost("login")]
public IActionResult Login([FromForm] string username, [FromForm] string password)
{
    // 验证用户名和密码
    return Ok();
}

3. raw (最常用的是JSON)

功能与用途： 用于发送原始数据，可以自定义任何格式。这是现代Web API交换数据最常用的方式。

.NET 8接口接收方式：

csharp 复制代码 
// POST: /api/users
[HttpPost]
public IActionResult CreateUser([FromBody] UserCreateDto userCreateDto)
{
    if (!ModelState.IsValid)
    {
        return BadRequest(ModelState);
    }
    var newUser = _userService.CreateUser(userCreateDto);
    return CreatedAtAction(nameof(GetUserById), new { id = newUser.Id }, newUser);
}

// 对应的DTO类
public class UserCreateDto
{
    [Required]
    public string Name { get; set; }

    [Required]
    [EmailAddress]
    public string Email { get; set; }

    public int Age { get; set; }
}

4. binary

功能与用途： 用于发送单个文件的原始二进制数据。

.NET 8接口接收方式：

csharp 复制代码 
// POST: /api/upload/binary
[HttpPost("binary")]
public async Task<IActionResult> UploadBinary()
{
    var filePath = Path.Combine(_hostEnvironment.WebRootPath, "uploadedfile.bin");
    using (var stream = System.IO.File.Create(filePath))
    {
        await Request.Body.CopyToAsync(stream);
    }
    return Ok();
}

四、Headers（请求头）

4.1 功能与用途

请求头用于传递关于请求的元信息，如内容类型(Content-Type)、认证令牌(Authorization)、客户端信息(User-Agent)等。

4.2 .NET 8接口接收方式

csharp 复制代码 
// 通过[FromHeader]属性获取单个请求头
[HttpGet("with-header")]
public IActionResult GetWithCustomHeader([FromHeader(Name = "X-Custom-Header")] string customHeaderValue)
{
    return Ok($"Received header value: {customHeaderValue}");
}

五、Authorization（授权参数）

5.1 功能与用途

Postman提供了专门的选项卡来管理授权信息（如API Key, Bearer Token, OAuth等）。它本质上是在请求头中自动添加授权凭证。

5.2 .NET 8接口接收方式

后端通过身份认证中间件自动处理授权头。

csharp 复制代码 
// Program.cs中的配置
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            // 其他配置...
        };
    });

// Controller中使用
[ApiController]
[Route("api/[controller]")]
[Authorize] // 需要认证
public class SecureController : ControllerBase
{
    [HttpGet]
    public IActionResult GetSecretData()
    {
        var userName = User.Identity.Name;
        return Ok($"Hello, {userName}. This is secret data!");
    }
}

✅总结对比表

参数类型 Postman位置 主要用途 常用HTTP方法 .NET 8接收属性
Query Params Params标签 过滤、分页、搜索 GET [FromQuery]
Path Variables URL中定义 标识唯一资源 GET, PUT, DELETE [FromRoute]
Body: form-data Body标签 带文件上传的表单 POST, PUT [FromForm], IFormFile
Body: x-www-form-urlencoded Body标签 纯文本表单 POST [FromForm]
Body: raw (JSON) Body标签 复杂结构化数据 POST, PUT, PATCH [FromBody]
Body: binary Body标签 发送单个二进制文件 POST, PUT Request.Body流
Headers Headers标签 元信息、授权 所有 [FromHeader]
Authorization Authorization标签 自动管理授权凭证 所有 认证中间件

结语🎯

掌握Postman各种参数类型的使用场景和对应的后端接收方式，是API开发和测试中的核心技能。希望本文能帮助你更加游刃有余地进行接口测试和开发工作。如果有任何疑问或建议，欢迎在评论区留言讨论！

热门推荐
01UV安装并设置国内源02Cursor 快速入门指南：从安装到核心功能03【2025.08.06最新版】Android Studio下载、安装及配置记录（自动下载sdk）04KGG转MP3工具|非KGM文件|解密音频0520个国内外主流AI绘画工具大汇总（最新免费可用~）06如何在Windows/Linux系统上安装adb07【踩坑笔记】50系显卡适配的 PyTorch 安装08Claude Code VSCode集成开发指南：AI编程助手完整配置092025最新国内服务器可用docker源仓库地址大全（2025年8月更新）10UnityHub Validation Failed下载编辑器错误，添加模块报错的解决方案