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

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 products
        var 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 database
        return 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 的路径参数。

何时使用路径参数？

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

.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 ID
        var product = GetProductFromDatabase(id);
        if (product == null)
        {
            return NotFound();
        }
        return Ok(product);
    }
    private Product GetProductFromDatabase(int id)
    {
        // Placeholder method to get a product from a database
        var 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; }
}

结论

了解何时使用查询字符串参数和路径参数对于设计直观有效的 REST API 至关重要。查询字符串参数非常适合过滤、排序和分页，而路径参数则用于资源识别。将两者结合起来可以提供一种灵活而强大的方式与您的 API 进行交互。

通过遵循本文提供的指南和示例，您可以设计结构良好、易于使用和维护的 REST API。