243 lines
10 KiB
Markdown
243 lines
10 KiB
Markdown
# 材质搜索
|
||
|
||
<cite>
|
||
**本文引用的文件**
|
||
- [routes.go](file://internal/handler/routes.go)
|
||
- [texture_handler.go](file://internal/handler/texture_handler.go)
|
||
- [texture_service.go](file://internal/service/texture_service.go)
|
||
- [texture_repository.go](file://internal/repository/texture_repository.go)
|
||
- [texture.go](file://internal/model/texture.go)
|
||
- [common.go](file://internal/types/common.go)
|
||
- [texture_service_test.go](file://internal/service/texture_service_test.go)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [简介](#简介)
|
||
2. [项目结构](#项目结构)
|
||
3. [核心组件](#核心组件)
|
||
4. [架构总览](#架构总览)
|
||
5. [详细组件分析](#详细组件分析)
|
||
6. [依赖关系分析](#依赖关系分析)
|
||
7. [性能考量](#性能考量)
|
||
8. [故障排查指南](#故障排查指南)
|
||
9. [结论](#结论)
|
||
10. [附录](#附录)
|
||
|
||
## 简介
|
||
本文件面向“材质搜索API”的使用与实现，围绕关键词搜索、材质类型过滤、公开性筛选与分页功能进行深入解析。基于仓库中的 SearchTextures 查询流程，解释关键词匹配（名称与描述）、类型过滤、公开状态筛选的实现细节，并结合分页测试用例说明分页参数的处理规则（page小于1时设为1，pageSize超过100时设为20）。同时提供请求示例、响应数据结构说明与错误处理机制，并解释搜索结果中上传者信息的预加载机制（Preload）及其对性能的影响。
|
||
|
||
## 项目结构
|
||
材质搜索API由三层协作完成：
|
||
- 路由层：注册 /api/v1/texture 的 GET 搜索接口
|
||
- 处理层：解析查询参数、调用服务层并返回分页响应
|
||
- 服务层：规范化分页参数、调用仓储层执行查询
|
||
- 仓储层：构建查询条件、统计总数、分页查询并预加载上传者信息
|
||
|
||
```mermaid
|
||
graph TB
|
||
Client["客户端"] --> Routes["路由: /api/v1/texture(GET)"]
|
||
Routes --> Handler["处理器: SearchTextures"]
|
||
Handler --> Service["服务: SearchTextures"]
|
||
Service --> Repo["仓储: SearchTextures"]
|
||
Repo --> DB["数据库"]
|
||
Handler --> Resp["分页响应: list,total,page,page_size,total_pages"]
|
||
```
|
||
|
||
图表来源
|
||
- [routes.go](file://internal/handler/routes.go#L43-L61)
|
||
- [texture_handler.go](file://internal/handler/texture_handler.go#L225-L291)
|
||
- [texture_service.go](file://internal/service/texture_service.go#L93-L103)
|
||
- [texture_repository.go](file://internal/repository/texture_repository.go#L71-L112)
|
||
|
||
章节来源
|
||
- [routes.go](file://internal/handler/routes.go#L43-L61)
|
||
|
||
## 核心组件
|
||
- 路由注册：在 v1 组下将 GET /api/v1/texture 绑定到处理器 SearchTextures
|
||
- 处理器：读取 keyword、type、public_only、page、page_size 查询参数，调用服务层，转换为统一响应结构
|
||
- 服务层：对分页参数进行边界校正（page<1 设为1；pageSize<1 或 >100 设为20），再调用仓储层
|
||
- 仓储层：按状态=1 进行基础过滤；公开筛选、类型筛选、关键词模糊匹配；先 Count 再分页查询；使用 Preload 预加载上传者信息
|
||
|
||
章节来源
|
||
- [texture_handler.go](file://internal/handler/texture_handler.go#L225-L291)
|
||
- [texture_service.go](file://internal/service/texture_service.go#L93-L103)
|
||
- [texture_repository.go](file://internal/repository/texture_repository.go#L71-L112)
|
||
|
||
## 架构总览
|
||
下面以序列图展示一次完整搜索请求的调用链路：
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant C as "客户端"
|
||
participant R as "路由"
|
||
participant H as "处理器"
|
||
participant S as "服务层"
|
||
participant RE as "仓储层"
|
||
participant D as "数据库"
|
||
C->>R : GET /api/v1/texture?keyword=&type=&public_only=&page=&page_size=
|
||
R->>H : 调用 SearchTextures
|
||
H->>H : 解析查询参数<br/>keyword,type,public_only,page,page_size
|
||
H->>S : SearchTextures(db, keyword, type, public_only, page, page_size)
|
||
S->>S : 校正分页参数<br/>page<1→1；pageSize<1或>100→20
|
||
S->>RE : SearchTextures(keyword, type, public_only, page, page_size)
|
||
RE->>D : 构建查询条件(status=1)<br/>公开筛选(is_public=?)<br/>类型筛选(type=?)
|
||
RE->>D : 关键词模糊匹配(name/description)<br/>Count统计总数
|
||
RE->>D : 分页查询(Offset/Limit)<br/>Preload上传者信息
|
||
D-->>RE : 结果集+总数
|
||
RE-->>S : 返回结果集+总数
|
||
S-->>H : 返回结果集+总数
|
||
H-->>C : 200 + 分页响应
|
||
```
|
||
|
||
图表来源
|
||
- [routes.go](file://internal/handler/routes.go#L43-L61)
|
||
- [texture_handler.go](file://internal/handler/texture_handler.go#L225-L291)
|
||
- [texture_service.go](file://internal/service/texture_service.go#L93-L103)
|
||
- [texture_repository.go](file://internal/repository/texture_repository.go#L71-L112)
|
||
|
||
## 详细组件分析
|
||
|
||
### 请求参数与处理规则
|
||
- 查询参数
|
||
- keyword：关键词，支持名称与描述的模糊匹配
|
||
- type：材质类型，可选 SKIN/CAPE
|
||
- public_only：布尔值，仅返回公开材质
|
||
- page：页码，默认1
|
||
- page_size：每页数量，默认20
|
||
- 参数边界校正（服务层）
|
||
- page 小于1时设为1
|
||
- page_size 小于1时设为20；大于100时也设为20
|
||
- 类型与公开筛选
|
||
- 类型为空字符串时不参与筛选
|
||
- public_only 为真时追加 is_public=true 条件
|
||
- 关键词匹配
|
||
- 同时对 name 和 description 使用 LIKE 模糊匹配
|
||
- 排序与分页
|
||
- 默认按 created_at 降序排序
|
||
- Offset=(page-1)*page_size，Limit=page_size
|
||
- 预加载上传者信息
|
||
- 使用 Preload("Uploader") 预加载关联用户信息，便于直接返回上传者字段
|
||
|
||
章节来源
|
||
- [texture_handler.go](file://internal/handler/texture_handler.go#L225-L291)
|
||
- [texture_service.go](file://internal/service/texture_service.go#L93-L103)
|
||
- [texture_repository.go](file://internal/repository/texture_repository.go#L71-L112)
|
||
- [texture_service_test.go](file://internal/service/texture_service_test.go#L163-L215)
|
||
|
||
### 数据模型与关联
|
||
- 材质模型包含上传者外键关联，仓储层通过 Preload 加载上传者信息
|
||
- 上传者信息在响应中以嵌套对象形式返回，便于前端直接显示
|
||
|
||
章节来源
|
||
- [texture.go](file://internal/model/texture.go#L16-L35)
|
||
|
||
### 响应数据结构
|
||
- 分页响应包含：
|
||
- list：结果数组（元素为材质信息）
|
||
- total：总条目数
|
||
- page：当前页码
|
||
- page_size：每页数量
|
||
- total_pages：总页数（由通用分页响应类型计算）
|
||
|
||
章节来源
|
||
- [common.go](file://internal/types/common.go#L18-L25)
|
||
- [texture_handler.go](file://internal/handler/texture_handler.go#L225-L291)
|
||
|
||
### 错误处理机制
|
||
- 参数解析失败：返回 400 错误
|
||
- 服务内部错误：返回 500 错误
|
||
- 业务错误（如材质不存在等）在其他接口中体现，搜索接口主要返回 500 表示查询失败
|
||
|
||
章节来源
|
||
- [texture_handler.go](file://internal/handler/texture_handler.go#L225-L291)
|
||
|
||
### 分页测试用例要点
|
||
- page<1 → 1
|
||
- pageSize<1 → 20
|
||
- pageSize>100 → 20
|
||
- 以上规则在服务层统一应用，确保查询稳定性
|
||
|
||
章节来源
|
||
- [texture_service_test.go](file://internal/service/texture_service_test.go#L163-L215)
|
||
|
||
## 依赖关系分析
|
||
- 路由层依赖处理器层
|
||
- 处理器层依赖服务层
|
||
- 服务层依赖仓储层
|
||
- 仓储层依赖数据库层
|
||
- 响应结构依赖通用分页类型
|
||
|
||
```mermaid
|
||
graph LR
|
||
Routes["routes.go"] --> Handler["texture_handler.go"]
|
||
Handler --> Service["texture_service.go"]
|
||
Service --> Repo["texture_repository.go"]
|
||
Repo --> Model["texture.go"]
|
||
Handler --> Types["common.go"]
|
||
Service --> Types
|
||
```
|
||
|
||
图表来源
|
||
- [routes.go](file://internal/handler/routes.go#L43-L61)
|
||
- [texture_handler.go](file://internal/handler/texture_handler.go#L225-L291)
|
||
- [texture_service.go](file://internal/service/texture_service.go#L93-L103)
|
||
- [texture_repository.go](file://internal/repository/texture_repository.go#L71-L112)
|
||
- [texture.go](file://internal/model/texture.go#L16-L35)
|
||
- [common.go](file://internal/types/common.go#L18-L25)
|
||
|
||
## 性能考量
|
||
- 预加载上传者信息（Preload）会增加单次查询的 JOIN 数量，导致额外的网络往返与内存占用。建议：
|
||
- 在高频搜索场景中评估是否需要返回上传者信息；若不需要，可在仓储层移除 Preload
|
||
- 对搜索结果进行缓存（如 Redis）以减少重复 COUNT 与分页查询
|
||
- 为常用筛选维度建立合适索引（例如 idx_textures_public_type_status、idx_textures_download_count 等）
|
||
- 关键词模糊匹配使用 LIKE 百分号前缀可能导致索引失效，建议：
|
||
- 评估是否需要全文检索或倒排索引
|
||
- 对高并发场景考虑异步搜索或搜索引擎（如 Elasticsearch）
|
||
|
||
章节来源
|
||
- [texture_repository.go](file://internal/repository/texture_repository.go#L71-L112)
|
||
- [texture.go](file://internal/model/texture.go#L16-L35)
|
||
|
||
## 故障排查指南
|
||
- 搜索无结果
|
||
- 检查 keyword 是否过短或包含特殊字符
|
||
- 确认 public_only 是否设置为 true 导致过滤掉私有材质
|
||
- 确认 type 是否正确传入（SKIN/CAPE）
|
||
- 分页异常
|
||
- page 小于1会被自动修正为1
|
||
- page_size 超过100会被修正为20
|
||
- 参数错误
|
||
- 确认查询参数类型与默认值是否符合预期
|
||
- 服务器错误
|
||
- 查看服务层日志，确认数据库连接与查询是否报错
|
||
|
||
章节来源
|
||
- [texture_handler.go](file://internal/handler/texture_handler.go#L225-L291)
|
||
- [texture_service.go](file://internal/service/texture_service.go#L93-L103)
|
||
- [texture_service_test.go](file://internal/service/texture_service_test.go#L163-L215)
|
||
|
||
## 结论
|
||
材质搜索API通过清晰的三层职责划分，实现了关键词、类型与公开性三类筛选，并以稳健的分页参数校正保障了查询稳定性。预加载上传者信息提升了前端展示效率，但需关注其带来的性能成本。建议在生产环境中结合缓存与索引优化，进一步提升搜索吞吐与延迟表现。
|
||
|
||
## 附录
|
||
|
||
### 请求示例
|
||
- 基础搜索（关键词）
|
||
- GET /api/v1/texture?keyword=steve
|
||
- 类型筛选
|
||
- GET /api/v1/texture?type=SKIN
|
||
- 公开性筛选
|
||
- GET /api/v1/texture?public_only=true
|
||
- 组合查询
|
||
- GET /api/v1/texture?keyword=cape&type=CAPE&public_only=true&page=1&page_size=20
|
||
|
||
章节来源
|
||
- [texture_handler.go](file://internal/handler/texture_handler.go#L225-L291)
|
||
|
||
### 响应示例
|
||
- 成功响应包含分页字段：list、total、page、page_size、total_pages
|
||
- 每个材质项包含：id、uploader_id、name、description、type、url、hash、size、is_public、download_count、favorite_count、is_slim、status、created_at、updated_at
|
||
|
||
章节来源
|
||
- [common.go](file://internal/types/common.go#L18-L25)
|
||
- [texture_handler.go](file://internal/handler/texture_handler.go#L225-L291) |