适用场景豆瓣电影信息 API 为开发者提供通过豆瓣电影 ID 或完整 URL 获取电影详情的接口。常见使用场景包括个人电影收藏/评分网站需要展示影片的评分、导演、演员等基础信息。电影推荐系统根据用户喜好获取电影元数据用于内容过滤。自动化影评分析工具采集热门短评部分接口可能返回。后台管理面板快速查询电影信息进行数据校对。接口能力边界请求方法GET接口地址https://v1.apizero.cn/api/douban-movie频率限制5 QPS每秒查询次数超出会返回 429 状态码。鉴权方式需在请求头中携带X-API-Key。输入参数仅一个必填参数id可为纯数字豆瓣 ID 或完整豆瓣电影页面 URL。返回格式JSON 数组外层数组通常只有一个元素内层包含code、msg、data字段。数据覆盖基于豆瓣公开 JSON API返回字段包括评分、导演、演员、类型、地区、片长、集数剧集、热门短评等具体以实际响应为准。参数详解与鉴权必填参数id类型string字符串是否必填是说明豆瓣电影的唯一标识。支持两种格式纯数字 ID例如1292052《肖申克的救赎》完整豆瓣电影页面 URL例如https://movie.douban.com/subject/1292052/API 会自动解析出 ID。示例值1292052注意若传入无效 ID 或 URL 格式无法解析API 会返回错误码 400。鉴权方式该 API 使用 HTTP 请求头X-API-Key进行身份认证。你需要在调用前在 apizero.cn/console 申请 API Key并将其作为请求头传递。安全建议不要将 API Key 硬编码在源代码中应通过环境变量如$APIZERO_API_KEY注入。在客户端调用时禁止在前端代码中暴露 API Key。curl 请求示例以下示例展示通过 curl 发送请求其中$APIZERO_API_KEY为环境变量请替换为实际密钥。示例 1使用纯数字 IDcurl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/douban-movie?id1292052示例 2使用完整豆瓣 URLcurl -sS \ -X GET \ -H X-API-Key: $APIZERO_API_KEY \ https://v1.apizero.cn/api/douban-movie?idhttps://movie.douban.com/subject/1292052/注意URL 中的id参数值如果包含特殊字符如:,/, curl 会自动进行 URL 编码通常无需手动处理。若在编程语言中构建请求应使用URLEncoder.encode()进行转义。返回字段解读API 响应是一个 JSON 数组典型结构如下以1292052为例[ { code: 0, msg: 成功, data: { director: 弗兰克·德拉邦特, douban_id: 1292052, name: 肖申克的救赎, score: 9.7, year: 1994 } } ]字段说明字段类型含义注意事项codeinteger业务状态码0 表示成功非 0 表示错误需根据msg排查msgstring业务描述信息可用于日志输出或用户提示dataobject电影详情对象包含以下常见子字段以实际返回为准data.directorstring导演姓名可能为空字符串data.douban_idstring豆瓣电影 ID与请求的id一致data.namestring电影名称中文名data.scorestring豆瓣评分字符串如 9.7需要转换为数字时注意保留精度data.yearstring上映年份如 1994除了上述字段文档说明中还提到data对象可能包含actors演员列表、type类型、region地区、duration片长、episodes集数仅剧集、hot_comments热门短评等。如果业务需要这些字段请以实际返回的 JSON 为准并做好容错处理字段缺失时提供默认值。重要提示返回的score是字符串类型在比较或计算时注意类型转换。例如 JavaScript 中应使用parseFloat(data.score)。常见错误与排查HTTP 状态码错误原因排查步骤401API Key 缺失或无效检查请求头是否添加X-API-Key并确认 Key 尚未过期、权限正确。400id参数缺失或格式错误确认id参数已传递且格式正确数字或完整 URL。URL 需包含http://或https://。404电影不存在或 ID 无效检查豆瓣 ID 是否正确可通过豆瓣网站验证。429请求频率超过 QPS 限制5/s在单次请求后等待至少 200ms 再发下一次或实现排队机制。500服务端内部错误稍后重试若持续出现请联系 API 提供方。无响应 / 超时网络问题或 DNS 解析失败检查网络连通性确认能访问v1.apizero.cn。另外注意返回的code字段也可能为非 0 值如code: -1此时msg会说明具体业务错误例如“参数错误”“数据获取失败”等。建议在代码中既判断 HTTP 状态码也判断code字段。工程化注意事项1. API Key 安全管理使用环境变量或密钥管理服务如 Vault存储 API Key禁止写入版本控制系统。在 Node.js 中可通过process.env.APIZERO_API_KEY读取。2. 限流控制QPS 上限为 5即每秒最多 5 次请求。若需要批量查询例如同时查 20 部电影应采用“令牌桶”或“固定间隔”策略固定间隔每 200ms 发送一次请求。批量并发使用信号量限制并发数为 5。示例Python 伪代码import time import requests def fetch_movie(movie_id): headers {X-API-Key: os.environ[APIZERO_API_KEY]} resp requests.get(https://v1.apizero.cn/api/douban-movie, params{id: movie_id}, headersheaders) return resp.json() # 限流每次请求后休眠 0.2 秒 for mid in movie_ids: result fetch_movie(mid) time.sleep(0.2)3. 缓存策略电影信息如评分、导演、年份变化频率极低建议加入本地缓存内存或 Redis以减少重复请求降低被限流风险。缓存时间可设为 1 天或更长但需考虑短评等动态数据的时效性。from functools import lru_cache lru_cache(maxsize128) def get_movie_info(movie_id): # 实际请求代码 pass4. 错误重试与熔断对于 5xx 或网络超时错误可设计指数退避重试最多 3 次。对于 429 错误应等待「Retry-After」头指定的时间若无则默认等待 1 秒。若连续失败次数过多应暂时熔断避免浪费资源。5. 数据类型与空值处理score是字符串需要数值比较时先parseFloat。部分字段可能为空字符串或null建议使用空值合并运算符如??提供默认值。数组字段如actors可能缺失或为[]遍历前先判断长度。6. 请求日志与监控记录每次请求的douban_id、状态码、响应时间、code值便于问题定位和性能分析。参考文档豆瓣电影信息 API 文档原始 Markdown 文档以上文档包含更完整的字段列表、错误码列表以及更新日志。建议开发前仔细阅读。
