接口简介
「导游资格题库」是数据鱼API平台提供的导游资格考试练习接口,Base 路径 /api/daoyou,共 18 个端点。它把题库查询、关键词搜索、随机抽题、每日一题、组卷、判分和批量导入放在同一套路由下,适合做刷题页、模拟卷和考前自测工具。
当前题库共 301 道题,分为旅游政策与法规、导游业务、全国导游基础知识 3 个分类,其中单选题 249 道、判断题 36 道、多选题 16 道,语言均为中文。题目含题干、选项、难度、模块、地区、年份与考点等字段;答案与解析默认不下发,需显式打开参数。
端点分三层:查询层含列表、详情、搜索和分面聚合;练习层含随机题、每日一题、相似题和答案校验;试卷层含组卷与整卷判分。维护层另有统计、分类、字段字典和受管理员密钥保护的导入端点。
端点总览
方法 路径 说明 鉴权
GET /api/daoyou/ping 服务心跳与能力清单 是
GET /api/daoyou/stats 题库总量与分布统计 是
GET /api/daoyou/categories 分类列表 是
GET /api/daoyou/fields 字段字典 是
GET /api/daoyou/list 分页题目列表 是
GET /api/daoyou/detail 单题详情 是
GET /api/daoyou/search 关键词搜索 是
GET /api/daoyou/random 随机抽题 是
GET /api/daoyou/facets 分面聚合 是
GET /api/daoyou/daily 每日一题 是
GET /api/daoyou/paper 组卷 是
POST /api/daoyou/paper 组卷(JSON 传参) 是
GET /api/daoyou/similar 相似题推荐 是
POST /api/daoyou/exam 整卷判分 是
GET /api/daoyou/image 题目配图 是
POST /api/daoyou/check 单题答案校验 是
POST /api/daoyou/batch 按 ID 批量取题 是
POST /api/daoyou/import 批量导入(管理员) 是
通用约定
所有端点用 X-API-Key 请求头或 api_key 查询参数鉴权,也兼容 token。缺少密钥返回 4011,密钥无效返回 4013;业务参数错误多以 HTTP 200 返回,鉴权失败、资源不存在分别用 401、403、404。数据鱼API的响应统一为 code、msg、data 三段。
布尔参数接受 1/0、true/false、yes/no、on/off。筛选值做宽松处理:category 需为小写短横线标识,type、difficulty、lang 须在白名单内;module 超 64 字符、region 超 32 字符、year 超出 1900 至 2100 时直接忽略,不报错。
错误码 含义
4001 缺少参数或参数无效
4002 参数数量或长度超限
4003 白名单取值不支持,或分页过深
4031 导入端点未配置管理员密钥
4032 管理员密钥无效
4041 题目或资源不存在
5000 服务端处理失败
5001 全站鉴权密钥未配置
分页列表与筛选
list 是主查询入口,支持页码与游标两种分页。页码从 1 开始;每页最多 20 条。after_id 大于 0 且排序为 id 升序时启用游标,返回的 next_after_id 可作下一页入参;偏移超过 100000 返回 4003,并提示改用游标。
参数 类型 必填 默认值 说明
page int 否 1 页码,从 1 开始
page_size int 否 20 每页条数,最大 20
after_id int 否 0 游标,只返回 id 大于该值的记录
brief boolean 否 0 只返回简要字段
with_answer boolean 否 0 返回答案与解析
fields string 否 — 逗号分隔字段,最多 30 个
sort string 否 id id、id_desc、year_desc、year_asc、difficulty_asc、difficulty_desc
category string 否 — 分类标识,如 fagui、yewu、jichu
type string 否 — 单选题、多选题、判断题
difficulty string 否 — easy、medium、hard
lang string 否 — zh、en
module string 否 — 模块或科目,最长 64 字符
sub_category string 否 — 细分题型,最长 64 字符
region string 否 — 地区,最长 32 字符
paper string 否 — 所属试卷
year int 否 0 年份,0 表示不限
has_image boolean 否 — 是否只取带配图的题
GET /api/daoyou/list?page=1&page_size=20&category=yewu&type=单选题&sort=id
返回 page、page_size、sort、next_after_id、list 与 has_more。列表项含题干、选项、难度、模块、细分题型、地区、年份、考点和配图标记;brief 为真时只保留简要字段,answer、analysis 等受 with_answer 控制。
搜索与组卷
search 在题干、选项与解析构成的检索文本上匹配,关键词按空白或逗号分词。match_all 默认为真,要求全部命中;设为假则命中任一即可。mode 表示实际检索方式,通常为 fulltext,退化为模糊匹配时为 like。
参数 类型 必填 默认值 说明
keyword string 是 — 搜索词,最长 128 字符
limit int 否 20 返回条数,最大 20
offset int 否 0 偏移量,最大 100000
match_all boolean 否 1 多词是否全部命中
brief boolean 否 0 只返回简要字段
with_answer boolean 否 0 返回答案与解析
fields string 否 — 逗号分隔字段,最多 30 个
sort string 否 id 排序白名单同列表端点
GET /api/daoyou/search?keyword=导游证&match_all=1&limit=10&with_answer=0
组卷端点同时接受 GET 与 POST。count 默认 20,取值 1 至 100,超过 100 截断为 100;types 用逗号分隔,只保留支持的题型,若非空但全部无效则返回 4003。相同 seed 与相同筛选条件得到完全相同的题目顺序,便于复现试卷。
参数 类型 必填 默认值 说明
count int 否 20 题目数量,1 至 100
types string 否 — 题型配额,逗号分隔
seed string 否 — 随机种子,相同种子结果一致
with_answer boolean 否 0 返回答案与答案卡
category string 否 — 分类筛选
difficulty string 否 — 难度筛选
POST /api/daoyou/paper
Content-Type: application/json
{"count": 30, "types": "单选题,多选题", "seed": "mock-2026", "with_answer": 1}
返回 bank、seed、requested、total、truncated、by_type、questions;打开 with_answer 时另带 answer_sheet。
练习与判分端点
detail 按 id 取单题,id 必须为正整数,不存在返回 4041。random 抽 count 道,默认 10、范围 1 至 20,支持与列表相同的筛选,answer 可作 with_answer 的别名。daily 按日期稳定取一题,date 缺省或格式非法时取当天,同一天结果一致。
facets 省略 dimensions 时默认统计 category、type、difficulty、module,最多 8 个维度,支持 category、type、difficulty、lang、module、sub_category、region、year,每维最多 200 个桶。similar 按分类、题型、难度推荐相近题,limit 默认 5、最大 20,brief 默认开启。
check 传 id 与 answer,答案可为选项字母或选项原文;判断题支持对错、正确错误、勾叉、T/F 归一。开启 reveal 后返回正确答案、选项文本和解析。exam 接收最多 200 条 answers,逐题给出 graded 或 not_found,空答案计入 blank,并按提交数与有效作答数分别计算百分比得分。
batch 的 items 是题目 ID 数组,单次最多 20 个;重复 ID 去重,非法元素跳过,缺失题以 not_found 占位。image 读取 storage/images 下的配图,仅允许 jpg、jpeg、png、gif、webp,成功时返回二进制并缓存一周,文件名不合法返回 4001。
统计与数据维护
stats 返回总量、更新时间、题型与模块分布等统计,缓存一小时;categories 与 fields 分别返回分类元数据和字段字典。
import 的管理员密钥从 X-Admin-Key 请求头或 admin_key 查询参数读取;未配置返回 4031,密钥不符返回 4032。questions 为对象数组,单次最多 500 条,dry_run 只校验并预览前 5 条。校验要求分类存在、题干 2 至 20000 字符、选项 2 至 8 个且键为 A 至 H、answer 为有效字母或选项原文。
典型使用场景
刷题应用用 categories 与 facets 渲染筛选器,用 list 翻页取题,提交后调用 check 判分;每日打卡用 daily 固定当天题目。
模拟考试用 paper 生成固定 seed 的试卷,前端收集作答后提交给 exam,取得总分、分题型正确率与逐题结果;错题复习用 similar 扩展同分类练习,再用 batch 补齐题面。
注意事项
文档把 ping、stats、categories、fields、image 标为免鉴权,但统一鉴权中间件已不再使用 publicPaths 参数,实测这些端点同样需要 API Key,缺失返回 4011。数据鱼API的接入方应统一附带密钥。
文档的列表示例显示 page_size 为 10 且列表为空,属于旧版探测结果;当前默认 20 条,题库实际 301 道题。
detail 示例的 id=0 会返回 4001,请用真实 ID;paper 的 count 文档写最大 20,当前实现为 1 至 100,默认 20。
batch 的 key 只支持 id,items 必须是 ID 数组;import 的管理员密钥不从 JSON 正文读取。
筛选值非法时多被静默忽略并退回全量结果,前端应先用 facets 或 fields 校验取值。
题库内容来自公开考试资料整理,仅用于练习与自测,不代表官方命题范围,也不构成考试通过承诺;法规条文以最新官方文本为准。