好词好句 API

简单、高效的好词好句获取接口

一、API 设计文档

1. 访问格式

API 访问格式：https://域名/a/b

2. 参数说明

3. 返回示例

请求示例：https://域名/5/chinese-poetry

{"success": true, "total": 5, "type": "chinese-poetry", "data": [
  {"id": 1, "content": "床前明月光，疑是地上霜。", "type": "chinese-poetry", "source": "李白《静夜思》"},
  {"id": 3, "content": "春眠不觉晓，处处闻啼鸟。", "type": "chinese-poetry", "source": "孟浩然《春晓》"},
  {"id": 5, "content": "白日依山尽，黄河入海流。", "type": "chinese-poetry", "source": "王之涣《登鹳雀楼》"},
  {"id": 7, "content": "红豆生南国，春来发几枝。", "type": "chinese-poetry", "source": "王维《相思》"},
  {"id": 9, "content": "独在异乡为异客，每逢佳节倍思亲。", "type": "chinese-poetry", "source": "王维《九月九日忆山东兄弟》"}
]}

4. 错误码表

错误描述 可能原因 解决方法
参数不足，需要提供数量和分类类型 请求URL格式不正确，缺少必要参数 确保URL格式为https://域名/a/b，其中a为数字，b为分类类型
数量必须是非负整数 参数a不是有效数字或小于等于0 确保参数a为大于0的整数
不支持的分类类型 参数b不是支持的分类类型 使用支持的分类类型：chinese-poetry, foreign-poetry, chinese-sentence, foreign-sentence
URL解析错误 请求URL格式不正确 检查URL格式是否正确

二、API 测试

测试结果：

请点击测试按钮获取结果...

三、代码实现

HTML 页面
API 逻辑
数据存储

当前页面即为HTML实现，完整代码请查看页面源代码。

// 核心逻辑代码请查看 api.js 文件
// 主要功能包括：
// 1. 解析URL参数
// 2. 验证参数有效性
// 3. 根据参数筛选数据
// 4. 返回JSON格式结果
// 数据存储代码请查看 data.js 文件
// 包含：
// 1. 本地数据存储（JavaScript数组）
// 2. 外部存储方案（localStorage和JSON文件）
// 3. 各类好词好句样本数据（每类至少10条）

四、测试指南

1. 本地运行测试

  1. 将三个文件（index.html, api.js, data.js）放在同一目录下
  2. 使用浏览器打开index.html文件
  3. 在API测试区域填写参数，点击"测试API"按钮查看结果

2. 调用示例及预期结果

五、扩展建议

1. 新增分类类型

要新增分类类型，只需在data.js文件中的data对象中添加新的分类及其数据，例如：

const data = {
  // 现有分类...
  'ancient-chinese': [
    { id: 1, content: '三人行，必有我师焉。', type: 'ancient-chinese', source: '《论语》' },
    // 更多数据...
  ]
};

2. 对接真实后端数据库

若要对接真实后端数据库，可以：

  1. 使用Node.js + Express/Koa等框架构建后端API
  2. 将数据存储在MySQL/MongoDB等数据库中
  3. 修改api.js中的数据获取逻辑，从数据库中查询数据

3. 优化数据加载速度