C# Web API产品搜索接口优化：是否需为每种查询创建端点？

不需要为每种搜索场景单独创建端点，使用单一端点配合可选查询参数是更符合REST设计原则且扩展性更强的方案。

为什么不推荐多端点方案 #

你之前设想的多个路由会导致API冗余，后续如果需要新增筛选条件（比如价格、品类），就得不断新增端点，维护成本高，也不符合REST“以资源为核心”的设计理念——产品是一个独立资源，搜索只是对这个资源的筛选操作，不该拆分成多个不同的端点。

单一端点的实现方式 #

用一个统一的GET /api/products端点，通过查询参数传递尺寸ID列表和颜色ID，参数设为可选，这样就能覆盖所有你提到的搜索场景，甚至支持更多扩展场景。

示例代码如下：

[ApiController]
[Route("api/[controller]")]
public class ProductsController : ControllerBase
{
    private readonly IProductRepository _productRepository;

    public ProductsController(IProductRepository productRepository)
    {
        _productRepository = productRepository;
    }

    [HttpGet]
    public async Task<IActionResult> GetProducts(
        [FromQuery] List<int>? sizeIds,
        [FromQuery] int? colorId)
    {
        // 校验参数（可选）：比如限制尺寸数量不超过2，根据业务需求调整
        if (sizeIds != null && sizeIds.Count > 2)
        {
            return BadRequest("最多支持同时筛选2个尺寸");
        }

        // 调用仓储层获取筛选后的产品
        var products = await _productRepository.GetFilteredProducts(sizeIds, colorId);
        return Ok(products);
    }
}

客户端调用示例 #

不同搜索场景对应不同的查询参数组合：

• 单一尺寸：GET /api/products?sizeIds=1
• 两个尺寸：GET /api/products?sizeIds=1&sizeIds=2
• 单一尺寸+单一颜色：GET /api/products?sizeIds=1&colorId=3
• 两个尺寸+单一颜色：GET /api/products?sizeIds=1&sizeIds=2&colorId=3
• 仅按颜色筛选：GET /api/products?colorId=3

方案优势 #

1. 扩展性强：后续新增筛选条件（如价格区间、上架时间），只需在方法中添加对应的可选查询参数，不用修改路由结构
2. 维护简单：所有产品筛选逻辑集中在一个方法里，便于统一维护和调试
3. 客户端友好：开发者只需记住一个端点，通过组合参数实现不同筛选需求，无需记忆多个路由规则

内容的提问来源于stack exchange，提问作者Modestas Vacerskas