📚 豆瓣图书 API

基于 ISBN 抓取豆瓣图书信息，部署于 EdgeOne 边缘函数，支持令牌鉴权与 KV 缓存。

在线测试

ISBN 鉴权令牌（AUTH_TOKEN）

一、接口地址

基础地址即你的 EdgeOne 项目域名，路由自动映射为：

GET {当前站点域名}/api/book?isbn=<ISBN>

例如：https://你的项目.edgeone.app/api/book?isbn=9787111112112

二、身份认证

所有请求必须在请求头携带令牌，二选一：

Authorization: Bearer <AUTH_TOKEN>
# 或
x-api-key: <AUTH_TOKEN>

令牌来自 EdgeOne 项目环境变量 AUTH_TOKEN。未携带或错误返回 401 Unauthorized；未配置该变量返回 500。

三、请求参数

参数	位置	必填	说明
`isbn`	Query	是	图书 ISBN（10 或 13 位），如 `9787111112112`
`refresh`	Query	否	设为 `1` 时忽略缓存，强制重新抓取并覆盖 KV 缓存

四、缓存机制（KV）

查询过的数据写入 EdgeOne KV（绑定变量名 BOOK_CACHE），下次同 ISBN 直接从缓存返回，不再请求豆瓣。

响应头 x-cache 标识数据来源：

值	含义
`HIT`	命中 KV 缓存，直接返回
`MISS`	缓存未命中，实时抓取后写入缓存
`REFRESH`	因 `refresh=1` 强制刷新

缓存 key 形如 book_<清洗后的ISBN>（KV key 仅允许字母/数字/下划线）。
有效期由环境变量 CACHE_TTL_SECONDS 控制，默认 604800（7 天），0 表示不过期。
清除某条缓存：控制台 KV 命名空间删除对应 key，或用 refresh=1 覆盖。

五、返回字段

字段	类型	说明
`title`	string	书名
`subtitle`	string	副标题
`original_title`	string	原作名
`author`	array	作者，元素含 `name`
`translator`	string	译者
`logo`	string	封面图 URL
`publisher`	string	出版社
`published`	string	出版年
`page`	string	页数
`price`	string	定价
`designed`	string	装帧
`series`	string	丛书
`isbn13`	string	ISBN
`rating`	number\|null	评分；部分书页无评分时为 `null`
`rating_count`	number	评分人数
`description`	string	内容简介（完整版，非截断）

六、调用示例

正常请求（首次 MISS，二次 HIT）

curl "https://<你的域名>/api/book?isbn=9787111112112" \
  -H "Authorization: Bearer <AUTH_TOKEN>"

强制刷新缓存

curl "https://<你的域名>/api/book?isbn=9787111112112&refresh=1" \
  -H "Authorization: Bearer <AUTH_TOKEN>"

鉴权失败

curl "https://<你的域名>/api/book?isbn=9787111112112"
# => 401 { "error": "Unauthorized" }

七、注意事项

预览环境访问保护：使用 preview 环境部署时，EdgeOne 会附加 eo_token / eo_time 预览令牌（链接带参、首次访问 302 写入 Cookie）。浏览器访问本页与调用接口均会自动处理，无需手动操作；部署到 production 后该保护消失，调用方式不变。
本地模式：项目根 api.js 为本地 Express 服务（npm install && npm start），无鉴权、无 KV 缓存，便于调试。

八、环境变量一览

变量名	必填	说明
`AUTH_TOKEN`	是	接口鉴权令牌（建议 Secret 类型）
`BOOK_CACHE`	是*	KV 命名空间绑定变量名（*绑定 KV 后才需；可用 `KV_BINDING_NAME` 改）
`CACHE_TTL_SECONDS`	否	缓存有效期（秒），默认 604800，0=不过期