DaShangDao/daShangDao_centerBook

Fork 0

97694731 0546fce601 sync

2026-06-15 18:05:22 +08:00

32 KiB

Raw Blame History

选品中心系统 API 文档

基础信息

项目名称: 选品中心 (centerBook)
Base URL: http://localhost:9009
API 版本: v2.0
数据格式: JSON
字符编码: UTF-8
基础技术栈: Go 1.24 + Gin + Elasticsearch + MySQL + Redis

通用说明
一、ES 图书搜索接口
二、ES 图书管理接口（新版 Controller）
三、ES 图书管理接口（旧版 Service）
四、API 监控接口
五、ERP 接口
六、WebSocket
七、定价加密/解密接口（已注释）
八、SQL 健康监控接口（已注释）
九、图书管理接口 MySQL 版（已注释）
附录：ESBook 完整字段说明
附录：通用错误码
附录：curl 请求示例汇总

通用说明

成功响应格式

{
  "code": 200,
  "message": "success",
  "data": { ... }
}

错误响应格式

{
  "error": "错误描述",
  "details": "详细错误信息"
}

分页响应格式

{
  "current_page": 1,
  "data": [...],
  "per_page": 10,
  "total": 100
}

全局中间件

所有请求经过以下中间件处理：

中间件	说明
CORS	允许来源: `localhost:82`, `103.236.91.138:9009`, `test.centerbook.buzhiyushu.cn`, `centerbook.buzhiyushu.cn`
RequestAuditLogger	统一请求审计日志（记录 endpoint、URI、状态码、IP、UA、耗时）
NotFoundHandler	未匹配路由统一处理（记录 404 来源）

响应字段说明

字段	说明
`fix_price`	定价，单位为分（需除以 100 转换为元）
`update_time`	更新时间，Unix 时间戳（秒）
`publication_time`	出版时间，格式为 `2006-01`
`page`	页码，从 1 开始
`per_page` / `pageSize`	每页数量，最大支持 1000
`book_pic`	图片对象，格式: `{"localPath": "", "pddPath": "http://..."}`
`book_pic_s`	小图对象，格式: `{"localPath": "", "pddResponse": "http://..."}`

一、ES 图书搜索接口

1.1 ISBN 模糊搜索

GET /api/es/searchByISBNLike

功能说明: 根据 ISBN 进行模糊搜索，优先查 Redis，未命中则查询 ES，并异步从孔夫子抓取补充数据。

请求参数:

参数名	类型	必填	说明
isbn	string	是	ISBN 号（支持模糊匹配）

响应示例:

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": 123456,
      "book_name": "Go语言编程",
      "isbn": "9787111111111",
      "author": "作者名",
      "publisher": "清华大学出版社",
      "category": "图书/计算机/编程",
      "fix_price": 9900,
      "book_pic": {"localPath": "", "pddPath": "http://example.com/image.jpg"},
      "book_pic_s": {"localPath": "", "pddResponse": "http://example.com/image_s.jpg"},
      "sell_counts": 100,
      "buy_counts": 500,
      "day_sale_7": 10,
      "day_sale_15": 25,
      "day_sale_30": 60,
      "total_sale": 1000
    }
  ]
}

1.2 ISBN 精确搜索

GET /api/es/searchByISBN

功能说明: 根据 ISBN 精确查询图书信息，支持 Redis 缓存、数据库和外部 API 三级回退查询。

请求参数:

参数名	类型	必填	说明
isbn	string	是	ISBN 号（精确匹配）

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123456,
    "book_name": "Go语言编程",
    "isbn": "9787111111111",
    "author": "作者名",
    "publisher": "清华大学出版社",
    "fix_price": 9900,
    "book_pic": {"localPath": "", "pddPath": "http://example.com/image.jpg"},
    "book_pic_s": {"localPath": "", "pddResponse": ""},
    "sell_counts": 100,
    "buy_counts": 500,
    "day_sale_7": 10,
    "day_sale_15": 25,
    "day_sale_30": 60,
    "day_sale_180": 200,
    "day_sale_365": 800,
    "total_sale": 1000,
    "is_suit": 0,
    "is_illegal": 0,
    "is_return": 0,
    "update_time": "1705228800"
  },
  "source": "es"
}

数据来源说明: source 字段标识数据来源，取值: redis / database / external_api / es

1.3 咸鱼商品下架回调搜索

GET /api/es/searchByISBNByXyCallBack

功能说明: 为咸鱼（Xianyu）商品下架回调提供的 ISBN 精确搜索接口。

请求参数:

参数名	类型	必填	说明
isbn	string	是	ISBN 号

响应: 同 1.2 ISBN 精确搜索

1.4 PSI 系统搜索

GET /api/es/searchByISBNtoPsi

功能说明: 为 PSI 系统提供的 ISBN 精确搜索接口，返回包含 cat_id （类目信息）的完整数据。

请求参数:

参数名	类型	必填	说明
isbn	string	是	ISBN 号

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123456,
    "book_name": "Go语言编程",
    "isbn": "9787111111111",
    "cat_id": {
      "pin_duo_duo_cat_id": "12345",
      "kong_fu_zi_cat_id": "67890",
      "xian_yu_cat_id": "11121"
    },
    "...": "..."
  }
}

1.5 书名搜索

GET /api/es/searchByBookName

功能说明: 根据书名进行模糊搜索。

请求参数:

参数名	类型	必填	说明
book_name	string	是	书名（支持模糊匹配）
page	int	否	页码，默认 1
size	int	否	每页数量，默认 10

响应示例:

{
  "code": 200,
  "message": "success",
  "data": [...],
  "count": 50
}

1.6 全字段搜索

GET /api/es/searchAll

功能说明: 在所有文本字段（书名、作者、ISBN、出版社等）中进行关键词搜索。

请求参数:

参数名	类型	必填	说明
q	string	是	搜索关键词
page	int	否	页码，默认 1
size	int	否	每页数量，默认 10

响应示例:

{
  "code": 200,
  "message": "success",
  "data": [...],
  "count": 100
}

1.7 条件搜索图书基础信息（新版）

GET /api/es/getBookBaseInfoES

功能说明: 根据多条件查询 ES 图书信息（新版 Controller 重构版本）。支持精确匹配、范围查询、模糊搜索等。

请求参数:

参数名	类型	必填	说明
page	int	否	页码，默认 1
pageSize / per_page	int	否	每页数量，默认 10
saleSelect	string	否	销量维度选择: `7`(7天), `15`, `30`, `60`, `90`, `180`, `365`, `0`(今年), `1`(去年)
book_name	string	否	书名（精确匹配）
isbn	string	否	ISBN（精确匹配）
author	string	否	作者（精确匹配）
category	string	否	分类（模糊匹配）
publisher	string	否	出版社（精确匹配）
publication_time	string	否	出版时间范围，逗号分隔，如 `2000,2020`
binding_layout	string	否	装帧
fix_price	string	否	定价范围，如 `1000,5000`（分为单位）
isSuit	string	否	是否套装: `0`(否), `1`(是)
is_return	string	否	是否驳回: `0`(否), `1`(是)
is_filter	string	否	过滤字段
book_pic	string	否	是否有图: `0`(无图), `1`(有图)
picType	string	否	图片类型: `1`(官图), `2`(小图)
buy_counts	string	否	购买次数范围，如 `100,1000`（受 saleSelect 影响）
sell_counts	string	否	在售数量范围，如 `10,1000`
day_sale_7 ~ day_sale_365	string	否	各维度销量范围
this_year_sale	string	否	今年销量范围
last_year_sale	string	否	去年销量范围
totalSale_range	string	否	总销量范围
id	string	否	ES 文档 ID
page_count	string	否	页数
word_count	string	否	字数
kongfz_categories	string	否	孔夫子分类列表，多个用逗号分隔
kongfz_include	int8	否	是否涵盖: `1`(是), `2`(否)
shopType	string	否	店铺类型

响应示例:

{
  "current_page": 1,
  "data": [
    {
      "id": 123456,
      "book_name": "Go语言编程",
      "book_pic": {"localPath": "", "pddPath": "http://example.com/image.jpg"},
      "book_pic_s": {"localPath": "", "pddResponse": ""},
      "book_pic_b": "",
      "book_pic_w": {},
      "book_def_pic": {"localPath": "", "pddPath": ""},
      "isbn": "9787111111111",
      "author": "作者名",
      "category": "图书/计算机/编程",
      "publisher": "清华大学出版社",
      "publication_time": "2020-01",
      "binding_layout": "平装",
      "fix_price": 9900,
      "content": "图书简介内容",
      "is_suit": 0,
      "day_sale_7": 10,
      "day_sale_15": 25,
      "day_sale_30": 60,
      "day_sale_60": 120,
      "day_sale_90": 200,
      "day_sale_180": 400,
      "day_sale_365": 800,
      "this_year_sale": 50,
      "last_year_sale": 800,
      "total_sale": 1500,
      "buy_counts": 500,
      "sell_counts": 100,
      "book_pic_obj": {},
      "book_pic_obj_s": {},
      "update_time": "1705228800",
      "is_illegal": 0,
      "is_return": 0,
      "is_filter": "",
      "page_count": "300",
      "word_count": "200000",
      "book_format": "16",
      "other": {}
    }
  ],
  "per_page": 10,
  "total": 156
}

1.8 批量获取图书基础信息

GET /api/es/batchGetBookBaseInfoES

功能说明: 为核价软件提供的批量获取接口，根据条件批量查询 ES 图书信息。

请求参数: 同 1.7，增加以下参数：

参数名	类型	必填	说明
isbns	string	否	ISBN 列表，逗号分隔（最多 50 个）

响应示例:

{
  "code": 200,
  "message": "success",
  "data": [...],
  "count": 50
}

1.9 多条件高级搜索

GET /api/es/searchAdvanced

功能说明: 多条件 AND 逻辑高级搜索，所有参数同时参与过滤。

请求参数: 同 1.7

响应: 同 1.7

1.10 ID 范围计数

GET /api/es/countByIDRange

功能说明: 统计指定 ID 范围内的文档数量。

请求参数:

参数名	类型	必填	说明
minID	int	是	最小 ID
maxID	int	是	最大 ID

响应示例:

{
  "code": 200,
  "minID": 1,
  "maxID": 100000,
  "count": 50000
}

二、ES 图书管理接口（新版 Controller）

2.1 添加/更新图书

POST /api/es/addBookToES

功能说明: 根据 ISBN 查询 ES 中是否存在，不存在则新增数据，存在则根据参数更新。同时同步数据到 Redis。

请求体 (JSON):

{
  "book_name": "Go语言编程实战",
  "isbn": "9787111122222",
  "author": "作者名",
  "publisher": "出版社",
  "category": "图书/计算机/编程",
  "fix_price": 8900,
  "binding_layout": "平装",
  "publication_time": "2023-01",
  "content": "图书简介",
  "book_pic": {
    "localPath": "",
    "pddPath": "http://example.com/image.jpg"
  },
  "book_pic_s": {
    "localPath": "",
    "pddResponse": "http://example.com/image_s.jpg"
  },
  "is_suit": 0,
  "day_sale_7": 0,
  "day_sale_15": 0,
  "day_sale_30": 0,
  "day_sale_60": 0,
  "day_sale_90": 0,
  "day_sale_180": 0,
  "day_sale_365": 0,
  "this_year_sale": 0,
  "last_year_sale": 0,
  "total_sale": 0,
  "buy_counts": 0,
  "sell_counts": 0
}

响应示例:

{
  "data": {
    "id": 123457,
    "book_name": "Go语言编程实战",
    "isbn": "9787111122222",
    "...": "..."
  },
  "source": "service"
}

source 字段: es（已存在，从 ES 返回） / service（新增插入）

2.2 更新图书字段

POST /api/es/updateBookFieldsByISBN

功能说明: 根据 ISBN 通用更新图书字段，支持动态指定要更新的字段。

data 中的所有字段（含 is_suit）都会更新到 v2 索引
is_suit=1 时，额外将文档同步到 books-from-mysql-v3 索引（存在则覆盖，不存在则新增）
is_suit=0 时，额外从 books-from-mysql-v3 索引中删除该 ISBN 的文档
同步 Redis（db1），包含完整数据含 cat_id

请求体 (JSON):

{
  "isbn": "9787111111111",
  "data": {
    "fix_price": 8800,
    "author": "新作者名",
    "is_suit": 1
  }
}

参数说明:

参数	位置	类型	必需	说明
`isbn`	body	string	是	ISBN 号
`data`	body	object	是	要更新的字段键值对
`data.is_suit`	body.data	int	否	1→同步到v3，0→从v3删除，不传→不操作v3

响应示例:

{
  "code": 200,
  "message": "success",
  "isbn": "9787111111111",
  "updated": 1,
  "fields_updated": 3,
  "updated_fields": ["fix_price", "author", "total_sale"]
}

2.3 更新商品分类

POST /api/es/updateBookCatIdByISBN

功能说明: 根据 ISBN 更新商品分类字段（cat_id），支持拼多多、孔夫子、闲鱼三个平台的分类同时更新或只更新传入平台的分类。

请求体 (JSON):

{
  "isbn": "9787111111111",
  "data": {
    "cat_id": {
      "pin_duo_duo_cat_id": "12345",
      "kong_fu_zi_cat_id": "67890",
      "xian_yu_cat_id": "11121"
    }
  }
}

响应示例:

{
  "code": 200,
  "message": "success",
  "isbn": "9787111111111",
  "updated": 1,
  "fields_updated": 1,
  "updated_fields": ["cat_id"]
}

2.4 根据 ISBN 删除图书

GET /api/es/DeleteBookByISBN

功能说明: 根据 ISBN 删除 ES 中的图书数据。

请求参数:

参数名	类型	必填	说明
isbn	string	是	ISBN 号

响应示例:

{
  "code": 200,
  "message": "删除成功"
}

2.5 根据 ID 删除图书

GET /api/es/DeleteBookByID

功能说明: 根据 ES 文档 ID 删除图书数据。

请求参数:

参数名	类型	必填	说明
id	string	是	ES 文档 ID

响应示例:

{
  "code": 200,
  "message": "删除成功",
  "data": {
    "id": "123456",
    "deleted": true
  }
}

三、ES 图书管理接口（旧版 Service）

3.1 更新在售数量（自动获取）

POST /api/es/updateSellCountsByISBN

功能说明: 根据 ISBN 调用 Tail 外部 API 获取在售数量并更新到 ES。

请求参数:

参数名	类型	必填	说明
isbn	string	是	ISBN 号

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "isbn": "9787111111111",
    "on_sale_count": 150,
    "async": true
  }
}

async: true 表示操作为异步执行

3.2 直接更新在售数量

POST /api/es/updateSellCountsDirect

功能说明: 按入参直接更新在售数量到 ES。

请求体 (JSON):

{
  "isbn": "9787111111111",
  "sell_counts": 100
}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "isbn": "9787111111111",
    "sell_counts": 100,
    "async": true
  }
}

3.3 更新套装标记

POST /api/es/updateBookSuitByISBN

功能说明: 根据 ISBN 自动判断书名是否包含套装关键字并更新 is_suit 字段。

请求参数:

参数名	类型	必填	说明
isbn	string	是	ISBN 号

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "isbn": "9787111111111",
    "book_name": "Go语言编程（套装全三册）",
    "is_suit": 1,
    "updated": 1,
    "contains_suit_keyword": true
  }
}

3.4 完整插入图书

POST /api/es/addBookFullToES

功能说明: 完整插入接口，支持所有 ESBook 字段，book_name 强制要求 string 类型。

请求体 (JSON):

{
  "book_name": "Go语言编程",
  "isbn": "9787111111111",
  "author": "作者名",
  "publisher": "清华大学出版社",
  "category": "图书/计算机/编程",
  "publication_time": "2020-01",
  "binding_layout": "平装",
  "fix_price": 9900,
  "content": "图书简介内容",
  "is_suit": 0,
  "book_pic": {"localPath": "", "pddPath": "http://example.com/image.jpg"},
  "book_pic_s": {"localPath": "", "pddResponse": "http://example.com/image_s.jpg"},
  "book_pic_b": "",
  "book_pic_w": {},
  "day_sale_7": 0,
  "day_sale_15": 0,
  "day_sale_30": 0,
  "day_sale_60": 0,
  "day_sale_90": 0,
  "day_sale_180": 0,
  "day_sale_365": 0,
  "this_year_sale": 0,
  "last_year_sale": 0,
  "total_sale": 0,
  "buy_counts": 0,
  "sell_counts": 0,
  "is_illegal": 0,
  "is_return": 0,
  "is_filter": ""
}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123457,
    "result": "created"
  }
}

3.5 批量插入图书

POST /api/es/batchAddBookToES

功能说明: 批量插入多本图书到 ES，单次最多 100 本。

请求体 (JSON):

{
  "books": [
    {
      "book_name": "Go语言编程",
      "isbn": "9787111111111",
      "author": "作者1",
      "publisher": "出版社1",
      "fix_price": 9900
    },
    {
      "book_name": "Python实战",
      "isbn": "9787111133333",
      "author": "作者2",
      "publisher": "出版社2",
      "fix_price": 8900
    }
  ]
}

响应示例:

{
  "code": 200,
  "message": "批量插入完成",
  "data": {
    "total_count": 2,
    "success_count": 2,
    "failed_count": 0,
    "results": [
      {
        "index": 0,
        "isbn": "9787111111111",
        "success": true,
        "document": "9787111111111"
      },
      {
        "index": 1,
        "isbn": "9787111133333",
        "success": true,
        "document": "9787111133333"
      }
    ]
  }
}

3.6 检查图书是否存在

GET /api/es/checkBookExists
POST /api/es/checkBookExists

功能说明: 根据 ISBN 检查书籍是否在 ES 中存在，支持 GET 和 POST 两种方式。

请求参数 (GET):

参数名	类型	必填	说明
isbn	string	是	ISBN 号

请求体 (POST):

{
  "isbn": "9787111111111"
}

响应示例:

{
  "code": 200,
  "success": true,
  "data": {
    "exists": true,
    "isbn": "9787111111111",
    "book_id": "123456",
    "book_name": "Go语言编程",
    "message": "书籍存在"
  }
}

3.7 检查套装书

GET /api/es/checkBookSuit

功能说明: 检查书名是否包含套装关键字（如"套装"、"全册"等）。

请求参数:

参数名	类型	必填	说明
bookName	string	是	书名

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "book_name": "Go语言编程（套装全三册）",
    "is_suit": true
  }
}

四、API 监控接口

API 监控用于追踪 ES 和 Redis 调用的性能指标，支持实时统计和历史查询。

4.1 获取指定 API 统计

GET /api/api-monitor/stats

请求参数:

参数名	类型	必填	说明
endpoint	string	是	接口端点名称，如 `/api/es/searchByISBN`

响应示例:

{
  "status": "success",
  "data": {
    "endpoint": "/api/es/searchByISBN",
    "total_calls": 1500,
    "success_calls": 1490,
    "failed_calls": 10,
    "avg_duration_ms": 45.5,
    "max_duration_ms": 1200,
    "min_duration_ms": 5,
    "total_es_calls": 800,
    "total_redis_calls": 700,
    "qps": 2.5
  },
  "timestamp": "2025-01-14 10:30:00"
}

4.2 获取所有 API 统计

GET /api/api-monitor/all-stats

功能说明: 获取所有被监控接口的统计信息，按接口名排序。

响应示例:

{
  "status": "success",
  "data": [
    {
      "endpoint": "/api/es/searchByISBN",
      "total_calls": 1500,
      "...": "..."
    }
  ],
  "count": 5,
  "timestamp": "2025-01-14 10:30:00"
}

4.3 获取 ES 调用记录

GET /api/api-monitor/es-calls

请求参数:

参数名	类型	必填	说明
endpoint	string	是	接口端点名称
page	int	否	页码，默认 1
page_size	int	否	每页数量，默认 50，最大 500

响应示例:

{
  "status": "success",
  "data": {
    "calls": [
      {
        "id": 1,
        "timestamp": "2025-01-14 10:30:00",
        "duration_ms": 35,
        "success": true,
        "operation": "search",
        "index": "books-from-mysql-v2",
        "query": "{...}"
      }
    ],
    "count": 50,
    "total": 800,
    "page": 1,
    "page_size": 50,
    "total_pages": 16
  },
  "timestamp": "2025-01-14 10:30:00"
}

4.4 获取 Redis 调用记录

GET /api/api-monitor/redis-calls

请求参数: 同 4.3

响应: 同 4.3（返回 Redis 调用记录）

4.5 获取调用详情

GET /api/api-monitor/call-detail

请求参数:

参数名	类型	必填	说明
endpoint	string	是	接口端点名称
call_id	string	是	调用记录 ID
type	string	是	调用类型: `es` 或 `redis`

响应示例:

{
  "status": "success",
  "data": {
    "id": 1,
    "type": "ES",
    "timestamp": "2025-01-14 10:30:00",
    "duration_ms": 35,
    "success": true,
    "error": "",
    "operation": "search",
    "key_or_index": "books-from-mysql-v2",
    "query": "{\"query\":{\"match\":{\"isbn\":\"...\"}}}",
    "request": "...",
    "response": "..."
  }
}

4.6 监控仪表板

GET /api/api-monitor/dashboard

功能说明: 返回 HTML 格式的 API 监控仪表板页面，包含可视化统计数据。

响应: HTML 页面（Content-Type: text/html）

五、ERP 接口

5.1 插入筛选集合

POST /api/erp/insertFilterSet

功能说明: 插入 ERP 筛选集合数据。

请求参数: 通过 Query 参数传递

参数名	类型	必填	说明
(各类参数)	-	-	按 ERP 模块定义

六、WebSocket

6.1 WebSocket 连接

GET /ws

功能说明: 升级 HTTP 连接为 WebSocket，用于实时消息推送。

协议: 支持文本消息通信，服务器端维护活跃客户端列表并支持广播。

七、定价加密/解密接口（已注释）

⚠️ 以下接口代码仍存在但路由已注释，未在线上启用。

定价链接加密

GET /pricingLink

定价链接解密

GET /pricingLinkDec

加密方式: RSA-OAEP + AES-256-GCM 混合加密

八、SQL 健康监控接口（已注释）

⚠️ 以下接口代码仍存在但路由已注释，未在线上启用。

8.1 获取 SQL 统计

GET /api/sql-health/stats

8.2 获取最近 SQL 记录

GET /api/sql-health/recent

参数: limit(默认 50，最大 500)

8.3 获取慢查询

GET /api/sql-health/slow-queries

参数: threshold(阈值 ms，默认 1000)

8.4 获取失败查询

GET /api/sql-health/failed-queries

8.5 清除 SQL 记录

POST /api/sql-health/clear

8.6 SQL 监控仪表板

GET /api/sql-health/dashboard

九、图书管理接口 MySQL 版（已注释）

⚠️ 以下接口基于 MySQL 数据库，所有路由已注释，功能已迁移至 ES。

方法	路径	Handler 函数	说明
GET	`/api/bookBase/getBookBaseInfo`	`GetBookBaseInfo`	条件查询（含缓存）
GET	`/api/bookBase/getRandomBookBaseInfo`	`GetRandomBookBaseInfo`	随机查询
GET	`/api/bookBase/GetBookBaseInfoOptimized`	`GetBookBaseInfoOptimized`	优化查询
GET	`/api/bookBase/getBookByISBN`	`GetBookByISBN`	ISBN 查询（Redis → MySQL → 外部API）
GET	`/api/bookBase/getBookById`	`GetBookByID`	ID 查询
POST	`/api/bookBase/putBookBaseInfoToIll`	`SetBookBaseInfoToIll`	批量设置违规（按ID）
POST	`/api/bookBase/putBookBaseInfoToIllByISBN`	`SetBookBaseInfoToIllByISBN`	批量设置违规（按ISBN）
POST	`/api/bookBase/putBookBaseName`	`SetBookBaseInfoBookName`	修改书名
POST	`/api/bookBase/addBookBaseInfo`	`InsertBaseInfo`	新增图书（ISBN 去重）
POST	`/api/bookBase/updateSales`	`UpdateSales`	更新销量
GET	`/api/bookBase/getBookPicByISBN`	`GetBookPicByISBN`	获取图片
POST	`/api/bookBase/uploadBookPic`	`UploadBookPic`	上传图片
GET/POST	`/api/bookBase/getBookByIsbnXcx`	`getBookByIsbnXcx`	小程序查询
GET	`/api/bookBase/deleterIsbn`	`exportISBNs`	导出 ISBN 到 Excel
GET	`/api/bookBase/updateBooks`	`updateBooks`	批量更新图书

附录：ESBook 完整字段说明

响应字段 (ESBookResponse)

字段名	类型	说明
`id`	int64	ES 文档 ID
`book_name`	string	书名
`isbn`	string	ISBN
`author`	string	作者
`publisher`	string	出版社
`category`	string	分类路径，如 `图书/计算机/编程`
`publication_time`	string	出版时间，格式化后为 `2006-01`
`binding_layout`	string	装帧（平装/精装）
`fix_price`	float64	定价，单位：分
`content`	string	内容简介
`book_pic`	object	大图对象 `{localPath, pddPath}`
`book_pic_s`	object	小图对象 `{localPath, pddResponse}`
`book_pic_b`	string	大图地址
`book_pic_w`	object	水印图对象
`book_def_pic`	object	自制官图 `{localPath, pddPath}`
`book_pic_obj`	object	图片对象（扩展）
`book_pic_obj_s`	object	小图对象（扩展）
`is_suit`	int	是否套装: 0-否, 1-是
`is_illegal`	int	是否非法
`is_return`	int	是否驳回: 0-否, 1-是
`is_filter`	string	过滤字段
`day_sale_7` ~ `day_sale_365`	int	各维度天数销量
`this_year_sale`	int	今年销量
`last_year_sale`	int	去年销量
`total_sale`	int	总销量
`buy_counts`	int64	购买次数
`sell_counts`	int64	在售/售卖次数
`page_count`	number/string	页数
`word_count`	number/string	字数
`book_format`	number/string	开本
`update_time`	number/string	更新时间戳
`cat_id`	object	类目信息（仅 PSI 响应包含）
`other`	object	扩展字段

类目对象 (CatIdObject)

字段名	类型	说明
`pin_duo_duo_cat_id`	string	拼多多分类 ID
`kong_fu_zi_cat_id`	string	孔夫子分类 ID
`xian_yu_cat_id`	string	闲鱼分类 ID

附录：通用错误码

错误码	说明
200	成功
400	请求参数错误（缺少必填参数、参数格式错误）
404	资源不存在（未找到指定数据）
500	服务器内部错误（数据库查询失败、ES 操作异常等）

常见错误信息

错误信息	可能原因
`ISBN不能为空`	未提供 isbn 参数
`缺少 endpoint 参数`	监控接口未指定接口名
`该接口暂无监控数据`	指定的 endpoint 未被监控
`处理失败` / `更新失败` / `删除失败`	ES 操作异常或服务端错误

附录：curl 请求示例汇总

# ========== ES 搜索 ==========

# ISBN 模糊搜索
curl "http://localhost:9009/api/es/searchByISBNLike?isbn=978711"

# ISBN 精确搜索
curl "http://localhost:9009/api/es/searchByISBN?isbn=9787111111111"

# 书名搜索
curl "http://localhost:9009/api/es/searchByBookName?book_name=Go语言&page=1&size=10"

# 全字段搜索
curl "http://localhost:9009/api/es/searchAll?q=Go语言编程"

# 条件搜索
curl "http://localhost:9009/api/es/getBookBaseInfoES?book_name=Go语言&page=1&pageSize=10"

# 高级搜索
curl "http://localhost:9009/api/es/searchAdvanced?author=张三&publisher=清华大学出版社&page=1&pageSize=20"

# ID 范围计数
curl "http://localhost:9009/api/es/countByIDRange?minID=1&maxID=100000"

# ========== ES 图书管理 ==========

# 添加/更新图书
curl -X POST "http://localhost:9009/api/es/addBookToES" \
  -H "Content-Type: application/json" \
  -d '{"book_name":"Go语言编程","isbn":"9787111111111","author":"作者名","publisher":"出版社","fix_price":9900}'

# 更新图书字段（普通更新，不操作v3）
curl -X POST "http://localhost:9009/api/es/updateBookFieldsByISBN" \
  -H "Content-Type: application/json" \
  -d '{"isbn":"9787111111111","data":{"fix_price":8800,"author":"新作者名"}}'

# 更新图书字段（is_suit=1，同步到v3）
curl -X POST "http://localhost:9009/api/es/updateBookFieldsByISBN" \
  -H "Content-Type: application/json" \
  -d '{"isbn":"9787111111111","data":{"fix_price":8800,"is_suit":1}}'

# 更新图书字段（is_suit=0，从v3删除）
curl -X POST "http://localhost:9009/api/es/updateBookFieldsByISBN" \
  -H "Content-Type: application/json" \
  -d '{"isbn":"9787111111111","data":{"fix_price":8800,"is_suit":0}}'

# 更新类目
curl -X POST "http://localhost:9009/api/es/updateBookCatIdByISBN" \
  -H "Content-Type: application/json" \
  -d '{"isbn":"9787111111111","data":{"cat_id":{"pin_duo_duo_cat_id":"12345","kong_fu_zi_cat_id":"67890","xian_yu_cat_id":"11121"}}}'

# 删除图书（按 ISBN）
curl "http://localhost:9009/api/es/DeleteBookByISBN?isbn=9787111111111"

# 删除图书（按 ID）
curl "http://localhost:9009/api/es/DeleteBookByID?id=123456"

# 完整插入
curl -X POST "http://localhost:9009/api/es/addBookFullToES" \
  -H "Content-Type: application/json" \
  -d '{"book_name":"Go语言编程","isbn":"9787111111111","author":"作者名","publisher":"出版社","fix_price":9900}'

# 批量插入
curl -X POST "http://localhost:9009/api/es/batchAddBookToES" \
  -H "Content-Type: application/json" \
  -d '{"books":[{"book_name":"Go语言","isbn":"9787111111111","author":"作者1"},{"book_name":"Python","isbn":"9787111133333","author":"作者2"}]}'

# 检查图书存在
curl "http://localhost:9009/api/es/checkBookExists?isbn=9787111111111"

# 检查套装书
curl "http://localhost:9009/api/es/checkBookSuit?bookName=Go语言编程（套装）"

# ========== 在售数量 ==========

# 自动获取更新
curl -X POST "http://localhost:9009/api/es/updateSellCountsByISBN?isbn=9787111111111"

# 直接更新
curl -X POST "http://localhost:9009/api/es/updateSellCountsDirect" \
  -H "Content-Type: application/json" \
  -d '{"isbn":"9787111111111","sell_counts":100}'

# 更新套装标记
curl -X POST "http://localhost:9009/api/es/updateBookSuitByISBN?isbn=9787111111111"

# ========== API 监控 ==========

# 获取指定 API 统计
curl "http://localhost:9009/api/api-monitor/stats?endpoint=/api/es/searchByISBN"

# 获取所有 API 统计
curl "http://localhost:9009/api/api-monitor/all-stats"

# 获取 ES 调用记录
curl "http://localhost:9009/api/api-monitor/es-calls?endpoint=/api/es/searchByISBN&page=1&page_size=50"

# 获取 Redis 调用记录
curl "http://localhost:9009/api/api-monitor/redis-calls?endpoint=/api/es/searchByISBN"

# 获取调用详情
curl "http://localhost:9009/api/api-monitor/call-detail?endpoint=/api/es/searchByISBN&call_id=1&type=es"

# 监控仪表板（浏览器访问）
curl "http://localhost:9009/api/api-monitor/dashboard"

更新日志

版本	日期	更新内容
v2.0	2025-06-13	全面重构，新增新版 Controller 接口、API 监控接口，统一响应格式说明
v1.0	2025-01-14	初始 API 文档

最后更新: 2025-06-13

32 KiB Raw Blame History Unescape Escape

选品中心系统 API 文档

基础信息

目录

通用说明

成功响应格式

错误响应格式

分页响应格式

全局中间件

响应字段说明

一、ES 图书搜索接口

1.1 ISBN 模糊搜索

1.2 ISBN 精确搜索

1.3 咸鱼商品下架回调搜索

1.4 PSI 系统搜索

1.5 书名搜索

1.6 全字段搜索

1.7 条件搜索图书基础信息（新版）

1.8 批量获取图书基础信息

1.9 多条件高级搜索

1.10 ID 范围计数

二、ES 图书管理接口（新版 Controller）

2.1 添加/更新图书

2.2 更新图书字段

2.3 更新商品分类

2.4 根据 ISBN 删除图书

2.5 根据 ID 删除图书

三、ES 图书管理接口（旧版 Service）

3.1 更新在售数量（自动获取）

3.2 直接更新在售数量

3.3 更新套装标记

3.4 完整插入图书

3.5 批量插入图书

3.6 检查图书是否存在

3.7 检查套装书

四、API 监控接口

4.1 获取指定 API 统计

4.2 获取所有 API 统计

4.3 获取 ES 调用记录

4.4 获取 Redis 调用记录

4.5 获取调用详情

4.6 监控仪表板

五、ERP 接口

5.1 插入筛选集合

六、WebSocket

6.1 WebSocket 连接

七、定价加密/解密接口（已注释）

定价链接加密

定价链接解密

八、SQL 健康监控接口（已注释）

8.1 获取 SQL 统计

8.2 获取最近 SQL 记录

8.3 获取慢查询

8.4 获取失败查询

8.5 清除 SQL 记录

8.6 SQL 监控仪表板

九、图书管理接口 MySQL 版（已注释）

附录：ESBook 完整字段说明

响应字段 (ESBookResponse)

类目对象 (CatIdObject)

附录：通用错误码

常见错误信息

附录：curl 请求示例汇总

更新日志

32 KiB

Raw Blame History