bittern.cn
4API Design Patterns

搜索与过滤

查询模式

搜索过滤排序字段掩码

🎯 AI 时代的学习建议：不要只读理论。理解这一章的设计动机（为什么需要这个概念？）和边界条件（什么情况下会失效？）。当 AI 生成的代码涉及这些概念时，你能判断它是否用对了场景。AI 能帮你总结内容，但无法替代你亲手阅读、思考、建立直觉的过程。

第4章：搜索与过滤（Search and Filter）

一、导读

1.1 本章学习目标

第4章讲解搜索和过滤模式——让用户找到需要的数据。

本章的核心学习目标包括：

  • 掌握搜索 API 的设计
  • 理解过滤表达式的语法
  • 学会设计高效的搜索 API

1.2 为什么本章如此重要

搜索和过滤是用户体验的关键。设计不当会导致搜索慢、结果不准确、用户体验差。

1.3 核心问题引导

搜索 API 和列表 API 有什么区别？

如何设计灵活的过滤表达式？

全文搜索 API 应该如何设计？

搜索结果的排序和评分如何处理？

二、核心概念详解

2.1 搜索 API

// 简单搜索
GET /api/v1/users?q=alice

// 高级搜索
GET /api/v1/users?query=name:alice AND department:engineering

// 搜索结果
{
  "results": [...],
  "totalSize": 42,
  "nextPageToken": "...",
  "facets": {
    "department": [
      {"value": "engineering", "count": 30},
      {"value": "marketing", "count": 12}
    ]
  }
}

2.2 过滤表达式

// 基本过滤
GET /api/v1/orders?filter=status=SHIPPED

// 多条件
GET /api/v1/orders?filter=status=SHIPPED AND total>100

// 嵌套字段
GET /api/v1/orders?filter=customer.email=@example.com

// 日期范围
GET /api/v1/orders?filter=createdAt>=2024-01-01 AND createdAt<2024-02-01

2.3 全文搜索

// 搜索端点
POST /api/v1/search
{
  "query": "wireless bluetooth headphones",
  "types": ["product", "review"],
  "filters": {
    "price": {"min": 50, "max": 200},
    "rating": {"min": 4}
  },
  "sort": "relevance",
  "pageSize": 20
}

// 响应
{
  "results": [
    {
      "type": "product",
      "id": "prod_123",
      "score": 0.95,
      "highlight": {
        "title": "<em>wireless</em> <em>bluetooth</em> <em>headphones</em>",
        "description": "Premium <em>wireless</em>..."
      }
    }
  ],
  "totalSize": 150,
  "facets": {...}
}

三、实战案例

3.1 案例一：电商搜索 API

搜索 API 设计：

POST /api/v1/search
{
  "query": "running shoes",
  "filters": {
    "category": "shoes",
    "brand": ["Nike", "Adidas"],
    "price": {"min": 50, "max": 200},
    "size": [9, 10, 11],
    "color": ["black", "white"]
  },
  "sort": "relevance",
  "pageSize": 20,
  "pageToken": "..."
}

响应：
{
  "results": [...],
  "totalSize": 342,
  "nextPageToken": "...",
  "facets": {
    "brand": [
      {"value": "Nike", "count": 150},
      {"value": "Adidas", "count": 120},
      {"value": "Puma", "count": 72}
    ],
    "size": [
      {"value": 9, "count": 200},
      {"value": 10, "count": 280},
      {"value": 11, "count": 180}
    ]
  }
}

四、本章小结

搜索 API：支持全文搜索、过滤、排序、分面。

过滤表达式：灵活的查询语法。

全文搜索：相关性评分、高亮、分面导航。

五、思考与练习

设计一个支持复杂过滤的订单搜索 API。

搜索 API 的分面（facets）如何设计？

如何处理搜索结果的相关性评分？

4/7搜索与过
0%