何时使用查询字符串参数和路径参数

何时使用查询字符串参数和路径参数_2024-06-28

REST API 已成为构建和使用 Web 服务的标准。在设计 REST API 时，一个重要方面是决定如何构造 URL 和参数。向 API 传递参数的两种常见方法是通过查询字符串参数和路径参数。本文将解释这两种方法之间的区别、何时使用每种方法，并提供示例来说明它们的用法。

查询字符串参数

什么是查询字符串参数？

查询字符串参数是附加到 URL 末尾的键值对，位于问号 (?) 后面。多个参数用与号 (&) 分隔。它们通常用于过滤、排序或分页数据。

查询字符串参数示例

以下是用于过滤结果的查询字符串参数的简单示例：

GET /api/products?category=electronics&sort=price

在这个例子中

category 是用于按电子类别过滤产品的查询参数。
sort 是一个查询参数，用于按价格对产品进行排序。

何时使用查询字符串参数？

过滤：当您需要根据特定标准过滤项目列表时。
排序：当您需要对项目列表进行排序时。
分页：当您需要对项目列表进行分页时（例如，page=2&limit=20）。
可选参数：参数是可选的，并且可能并不总是提供。

.NET Core 中的示例

下面是如何在 ASP.NET Core 控制器中处理查询字符串参数的示例：

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{[HttpGet]public IActionResult GetProducts([FromQuery] string category, [FromQuery] string sort){// Example logic to filter and sort productsvar products = GetProductsFromDatabase();if (!string.IsNullOrEmpty(category)){products = products.Where(p => p.Category == category).ToList();}if (!string.IsNullOrEmpty(sort)){products = sort switch{"price" => products.OrderBy(p => p.Price).ToList(),_ => products};}return Ok(products);}private List<Product> GetProductsFromDatabase(){// Placeholder method to get products from a databasereturn new List<Product>{new Product { Id = 1, Name = "Laptop", Category = "electronics", Price = 1000 },new Product { Id = 2, Name = "Phone", Category = "electronics", Price = 500 },// More products...};}
}
public class Product
{public int Id { get; set; }public string Name { get; set; }public string Category { get; set; }public decimal Price { get; set; }
}

路径参数

什么是路径参数？

路径参数是 URL 路径本身的一部分，用于标识特定资源。它们直接嵌入到 URL 中，通常用于检索、更新或删除特定资源。

路径参数示例

以下是用于通过 ID 检索特定产品的路径参数的示例：

GET /api/products/123

在这个例子中

123 是用于指定要检索的产品的 ID 的路径参数。

何时使用路径参数？

资源标识：当需要该参数来识别特定资源时。
强制参数：需要该参数来完成请求。

.NET Core 中的示例

下面是如何在 ASP.NET Core 控制器中处理路径参数的示例。

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{[HttpGet("{id}")]public IActionResult GetProductById(int id){// Example logic to retrieve a product by IDvar product = GetProductFromDatabase(id);if (product == null){return NotFound();}return Ok(product);}private Product GetProductFromDatabase(int id){// Placeholder method to get a product from a databasevar products = new List<Product>{new Product { Id = 1, Name = "Laptop", Category = "electronics", Price = 1000 },new Product { Id = 2, Name = "Phone", Category = "electronics", Price = 500 },// More products...};return products.FirstOrDefault(p => p.Id == id);}
}

组合查询字符串和路径参数

在单个 API 中同时使用查询字符串和路径参数通常很有用。例如，您可以使用路径参数来标识特定资源，并使用查询字符串参数来过滤或排序相关数据。

例子

这是一个 API 示例，它检索特定客户（由路径参数标识）的订单，并支持按订单状态进行过滤（使用查询字符串参数）。

GET /api/customers/123/orders?status=shipped

.NET Core 中的示例

以下是如何在 ASP.NET Core 控制器中实现此功能。

[ApiController]
[Route("api/[controller]")]
public class CustomersController : ControllerBase
{// 处理GET请求，路径为api/customers/{customerId}/orders[HttpGet("{customerId}/orders")]public IActionResult GetCustomerOrders(int customerId, [FromQuery] string status){// 示例逻辑：检索特定客户的订单，并根据状态进行筛选var orders = GetOrdersFromDatabase(customerId);// 如果status参数不为空，则筛选出该状态的订单if (!string.IsNullOrEmpty(status)){orders = orders.Where(o => o.Status == status).ToList();}// 返回筛选后的订单列表return Ok(orders);}// 从数据库获取订单列表的占位方法private List<Order> GetOrdersFromDatabase(int customerId){return new List<Order>{new Order { Id = 1, CustomerId = 123, Status = "shipped", Total = 50.00m },new Order { Id = 2, CustomerId = 123, Status = "processing", Total = 100.00m },// 更多订单...};}
}// 订单类
public class Order
{public int Id { get; set; }public int CustomerId { get; set; }public string Status { get; set; }public decimal Total { get; set; }
}