最小可运行示例：用豆瓣电影信息API查询电影详情

适用场景

在开发涉及电影内容的项目时，获取电影的详细信息（评分、导演、演员、类型等）是一个常见需求。豆瓣电影信息 API 允许开发者通过豆瓣电影 ID 或 URL 直接查询电影详情，适用于以下场景：

• 影视资讯类应用：展示电影评分、简介、主创团队等基础信息。
• 个人学习或原型开发：快速验证业务逻辑，无需数据库即可获取结构化数据。
• 数据分析：采集电影元数据用于统计分析或推荐系统。
• 自动化脚本：批量查询多部电影的信息并写入本地文件。

该接口返回 JSON 格式的数据，结构紧凑，非常适合作为 REST API 入门的练手素材。

接口能力边界

在使用之前，需要明确该接口的能力范围：

注意：该接口仅支持通过电影 ID 或 URL 查询，不支持按名称模糊搜索。如果需要搜索，请使用其他搜索类接口。

参数与鉴权

请求参数

接口只接受一个查询参数id，其值可以是以下两种格式之一：

1. 纯数字 ID：例如1292052（《肖申克的救赎》的豆瓣 ID）。
2. 完整电影 URL：例如https://movie.douban.com/subject/1292052/。

两种格式效果相同，推荐使用纯数字 ID，避免 URL 解析开销。

鉴权方式

调用接口需要在 HTTP 头部添加X-API-Key字段，值为你在 API 平台申请的密钥。具体获取方式请参考文档（参见文末参考文档）。

示例 Headers：

X-API-Key: your_api_key_here

安全提示：请勿将 API Key 硬编码在公开仓库中，建议使用环境变量管理。

curl 请求示例（最小可运行）

以下是一个完整的 curl 命令，可直接复制后替换<API_KEY>与电影 ID 运行：

curl -sS \ -X GET \ -H "X-API-Key: <API_KEY>" \ "https://v1.apizero.cn/api/douban-movie?id=1292052"

参数说明

• -sS：静默模式并显示错误信息（便于调试）。
• -X GET：显式指定请求方法（默认 GET 可省略）。
• -H：设置请求头。
• id：必填，这里用1292052代表《肖申克的救赎》。

预期返回示例

{ "code": 0, "msg": "成功", "data": { "director": "弗兰克·德拉邦特", "douban_id": "1292052", "name": "肖申克的救赎", "score": "9.7", "year": "1994" } }

注意：实际返回的数据字段比示例更丰富，下面的返回值解读会列出完整字段。

代码接入示例（Python）

为了在生产环境中更方便地调用，可以使用 Python 的requests库。以下是一个最小可运行的脚本示例：

import requests import os def get_douban_movie(movie_id: str) -> dict: """ 通过豆瓣电影 ID 查询电影详情 :param movie_id: 豆瓣电影 ID（如 '1292052'） :return: 解析后的 JSON 字典 """ api_key = os.getenv("DOUBAN_API_KEY") # 从环境变量获取 API Key url = "https://v1.apizero.cn/api/douban-movie" headers = {"X-API-Key": api_key} params = {"id": movie_id} response = requests.get(url, headers=headers, params=params) response.raise_for_status() # 非 2xx 状态码抛出异常 return response.json() if __name__ == "__main__": movie_id = "1292052" result = get_douban_movie(movie_id) print(result)

运行前准备

1. 安装requests库：pip install requests
2. 设置环境变量DOUBAN_API_KEY：
   • Linux/macOS：export DOUBAN_API_KEY=your_api_key
   • Windows (CMD)：set DOUBAN_API_KEY=your_api_key
   • Windows (PowerShell)：$env:DOUBAN_API_KEY="your_api_key"
3. 执行脚本：python douban_movie.py

示例输出（截取部分字段）

{ "code": 0, "msg": "成功", "data": { "director": "弗兰克·德拉邦特", "douban_id": "1292052", "name": "肖申克的救赎", "score": "9.7", "year": "1994", "actors": ["蒂姆·罗宾斯", "摩根·弗里曼", "鲍勃·冈顿"], "genres": ["剧情", "犯罪"], "region": "美国", "duration": "142分钟", "episodes": "1" } }

返回字段解读

成功的响应（code为 0）中，data字段包含电影详细信息。以下是常见字段及说明：

注意：hot_comments字段并非每次请求都会返回，它与豆瓣公开 JSON API 的实时性有关。如果返回中缺少该字段，无需担心。

常见错误处理

错误码一览

注意：错误响应体中的msg字段会提供更详细的中文说明。例如：

{ "code": 400, "msg": "参数错误：缺少id", "data": null }

网络层面异常

• requests.exceptions.ConnectionError：网络不通或接口域名无法解析。
• requests.exceptions.Timeout：请求超时，建议设置合理的timeout参数（如 10 秒）。
• requests.exceptions.HTTPError：服务端返回非 2xx 状态码，可通过response.status_code判断。

工程化注意事项

1. API Key 安全：不要将 API Key 写在代码中或上传到公开仓库。使用环境变量、配置文件（.gitignore）或密钥管理服务。
2. 频率控制：接口限制 5 QPS，注意不要短时间内发起大量请求。可以使用限流器（如 Python 的time.sleep(0.2)或ratelimit库）。
3. 错误重试机制：至少重试一次 500 错误和网络异常，使用指数退避策略。
4. 数据缓存：电影元数据更新频率很低，建议缓存结果减少重复请求。可以使用 Redis 或本地文件缓存（TTL 设为 1 小时以上）。
5. 接口版本稳定性：v1路径表明当前版本；如有更新，文档会注明。建议订阅文档变化。
6. 参数处理：如果从用户输入中获取电影 ID，务必验证格式（仅允许数字或特定域名 URL），防止注入或其他攻击。
7. 超时设置：建议设置 10 秒连接超时和 15 秒读取超时。

参考文档

• 豆瓣电影信息 API 文档
• 原始 Markdown 文档

以上文档包含更详细的参数说明、错误码列表及更新日志，建议在实际集成前仔细阅读。