DaShangDao/daShangDao_centerBook

Fork 0

97694731 9c9692f8d7 初始化

2026-02-28 14:27:33 +08:00

10 KiB

Raw Blame History

图书中心系统 API 文档

基础信息

Base URL: http://localhost:9009
API 版本: v1.0
数据格式: JSON
字符编码: UTF-8

通用响应格式

成功响应

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

错误响应

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

分页响应

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

图书管理

1. 根据 ISBN 查询图书

请求:

GET /api/book/isbn?isbn=9787111111111

参数:

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

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123456,
    "isbn": "9787111111111",
    "book_name": "Go语言编程",
    "author": "作者名",
    "publisher": "清华大学出版社",
    "fix_price": 99.00,
    "book_pic": "http://example.com/image.jpg",
    "update_time": "1705228800"
  }
}

2. 添加图书到 ES

请求:

POST /api/es/book
Content-Type: application/json

{
  "book_name": "Go语言编程实战",
  "isbn": "9787111122222",
  "author": "作者名",
  "publisher": "出版社",
  "fix_price": 89.00,
  "book_pic": {
    "localPath": "",
    "pddPath": "http://example.com/image.jpg"
  },
  "book_pic_s": {
    "localPath": "",
    "pddResponse": "http://example.com/image_s.jpg"
  }
}

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "id": 123457,
    "source": "service"
  }
}

3. 批量添加图书

请求:

POST /api/es/books/batch
Content-Type: application/json

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

响应示例:

{
  "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"
      }
    ]
  }
}

4. 检查图书是否存在

请求:

GET /api/es/book/exists?isbn=9787111111111

响应示例:

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

5. 更新图书字段

请求:

PUT /api/es/book/fields
Content-Type: application/json

{
  "isbn": "9787111111111",
  "data": {
    "fix_price": 88.00,
    "author": "新作者名",
    "total_sale": 1000
  }
}

响应示例:

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

6. 删除图书

请求:

DELETE /api/es/book?isbn=9787111111111

或

DELETE /api/es/book?id=123456

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "deleted": true
  }
}

搜索服务

1. 关键词搜索

请求:

GET /api/search?keyword=Go语言&page=1&pageSize=10

参数:

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

响应示例:

{
  "count": 100,
  "data": [
    {
      "id": 123456,
      "book_name": "Go语言编程",
      "author": "作者名",
      "isbn": "9787111111111",
      "publisher": "清华大学出版社",
      "fix_price": 99.00
    }
  ]
}

2. 多条件搜索

请求:

GET /api/search/conditions?book_name=Go&author=张三&page=1&pageSize=20

支持的查询参数:

book_name - 书名
isbn - ISBN
author - 作者
category - 分类
publisher - 出版社
publication_time - 出版时间范围（逗号分隔）
day_sale_7 - 7天销量范围
total_sale - 总销量范围
sell_counts - 在售数量范围
is_suit - 是否套装 (0/1)
is_return - 是否驳回 (0/1)
is_filter - 过滤字段
book_pic - 是否有图 (0/1)
picType - 图片类型 (1-官图, 2-小图)
saleSelect - 销量维度选择 (7/15/30/60/90/180/365/0/1)
categoryType - 分类类型 (1-教材, 其他-非教材)

响应示例:

{
  "code": 200,
  "current_page": 1,
  "data": [...],
  "per_page": 20,
  "total": 156
}

3. 全字段搜索

请求:

GET /api/search/all?q=Go语言编程

参数:

q - 搜索关键词（搜索所有字段）

销量管理

1. 更新在售数量

请求:

POST /api/sellcounts/update?isbn=9787111111111&onSaleCount=100

参数:

参数名	类型	必填	说明
isbn	string	是	图书ISBN
onSaleCount	int	是	在售数量（非负整数）

响应示例:

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

2. 从外部API更新在售数量

请求:

POST /api/sellcounts/fetch?isbn=9787111111111

说明: 自动调用 tail API 获取在售数量并更新

响应示例:

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

图片管理

1. 更新图书图片

请求:

POST /api/book/pic/update?isbn=9787111111111&book_pic=http://example.com/new.jpg&book_pic_s=http://example.com/new_s.jpg

参数:

参数名	类型	必填	说明
isbn	string	是	图书ISBN
book_pic	string	否	大图URL
book_pic_s	string	否	小图URL

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "updated": 1
  }
}

系统监控

1. 健康检查

请求:

GET /health

响应示例:

{
  "status": "healthy",
  "mysql": "connected",
  "redis": "connected",
  "elasticsearch": "connected",
  "timestamp": "2025-01-14T10:30:00Z"
}

2. 服务就绪检查

请求:

GET /ready

响应示例:

{
  "ready": true
}

Elasticsearch 操作

1. 查询所有索引

请求:

GET /api/es/indices

响应示例:

{
  "code": 200,
  "message": "success",
  "data": [
    "books-from-mysql-v2",
    "books-from-mysql-new",
    "test-go-index"
  ]
}

2. 获取索引详情

请求:

GET /api/es/index/detail?indexName=books-from-mysql-v2

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "books-from-mysql-v2": {
      "aliases": {},
      "mappings": { ... },
      "settings": { ... }
    }
  }
}

3. 获取文档数量

请求:

GET /api/es/index/count?indexName=books-from-mysql-v2

响应示例:

{
  "code": 200,
  "message": "success",
  "data": {
    "count": 1000000
  }
}

4. 检查套装书

请求:

GET /api/book/check-suit?bookName=Go语言编程（套装）

响应示例:

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

5. 更新套装标记

请求:

PUT /api/book/suit
Content-Type: application/json

{
  "isbn": "9787111111111"
}

说明: 自动根据书名判断是否为套装书并更新

响应示例:

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

6. 统计ID范围数量

请求:

GET /api/es/count/range?minID=1&maxID=100000

响应示例:

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

错误码说明

错误码	说明
200	成功
400	请求参数错误
404	资源不存在
500	服务器内部错误

请求示例

使用 curl

# 查询图书
curl "http://localhost:9009/api/book/isbn?isbn=9787111111111"

# 搜索图书
curl "http://localhost:9009/api/search?keyword=Go语言&page=1&pageSize=10"

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

# 更新在售数量
curl -X POST "http://localhost:9009/api/sellcounts/update?isbn=9787111111111&onSaleCount=100"

使用 Go

import "net/http"

// 查询图书
resp, err := http.Get("http://localhost:9009/api/book/isbn?isbn=9787111111111")
if err != nil {
    log.Fatal(err)
}
defer resp.Body.Close()

// 解析响应
var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)

使用 JavaScript

// 查询图书
fetch('http://localhost:9009/api/book/isbn?isbn=9787111111111')
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error(error));

注意事项

所有时间戳格式: Unix 时间戳（秒）
价格单位: 分（需要除以100转换为元）
分页参数: page 从 1 开始
异步操作: 部分更新操作为异步执行，返回 async: true
CORS: 默认允许跨域请求

更新日志

v1.0.0 (2025-01-14)

初始 API 文档
完整的图书管理接口
Elasticsearch 操作接口
销量管理接口

最后更新: 2025-01-14

10 KiB Raw Blame History Unescape Escape

图书中心系统 API 文档

基础信息

目录

通用响应格式

成功响应

错误响应

分页响应

图书管理

1. 根据 ISBN 查询图书

2. 添加图书到 ES

3. 批量添加图书

4. 检查图书是否存在

5. 更新图书字段

6. 删除图书

搜索服务

1. 关键词搜索

2. 多条件搜索

3. 全字段搜索

销量管理

1. 更新在售数量

2. 从外部API更新在售数量

图片管理

1. 更新图书图片

系统监控

1. 健康检查

2. 服务就绪检查

Elasticsearch 操作

1. 查询所有索引

2. 获取索引详情

3. 获取文档数量

4. 检查套装书

5. 更新套装标记

6. 统计ID范围数量

错误码说明

请求示例

使用 curl

使用 Go

使用 JavaScript

注意事项

更新日志

v1.0.0 (2025-01-14)

10 KiB

Raw Blame History