type
status
date
slug
summary
tags
category
icon
password

剑桥词典 API 项目实现详解

本文将从零开始详细介绍剑桥词典 API 项目的实现过程，包括网页分析、接口寻找、API 设计与实现。

一、需求分析

我的目标是构建一个 API，能够： 1. 获取单词的释义、例句和发音 2. 支持自动补全（搜索建议） 3. 支持中英文翻译

二、网页源码分析

1. 了解网站结构

首先访问剑桥词典网站 https://dictionary.cambridge.org/dictionary/english-chinese-simplified/，通过观察可以发现：
  • 网站有搜索框，输入时会显示自动补全
  • 单词页面包含释义、例句和发音

2. 分析自动补全功能

当在搜索框中输入字母时，浏览器会发送请求获取建议词。使用浏览器开发者工具（F12）观察网络请求，发现了以下接口：
这个请求会返回 JSON 格式的数据，包含建议词列表：
通过分析，得出以下结论： - dataset 参数指定了词典的语言（英汉简体） - q 参数是搜索关键词 - 返回值是一个包含多个对象的数组，每个对象有 word、url 和 beta 属性 - 只需提取 word 字段即可获取建议词列表
实现自动补全功能的代码：
解析自动补全结果的函数：

3. 详细分析单词页面结构

访问单词页面（如 https://dictionary.cambridge.org/dictionary/english-chinese-simplified/hello），使用浏览器开发者工具检查 HTML 结构。

3.1 页面整体结构

通过观察，会发现每个单词页面都有一个核心结构：

3.2 提取关键信息

基于 HTML 结构分析，可以确定需要提取的关键信息及其对应的 CSS 选择器：
  1. 单词本身：.di-title .hw
  1. 词性：.pos-header .pos
  1. 发音信息：
      • 区域（英/美）：.dpron-i .region
      • 音标：.dpron-i .ipa
      • 音频 URL：.dpron-i audio source[type="audio/mpeg"]
  1. 释义信息（每个 .def-block）：
      • 释义文本：.def
      • CEFR 级别：.def-info .dxref
      • 释义翻译：.def-block > .trans
  1. 例句信息（每个 .examp）：
      • 例句文本：.eg
      • 例句翻译：.examp > .trans

3.3 实际解析代码

构建以下HTML 解析函数

3.4 挑战与处理技巧

在实际解析过程中，会遇到了一些挑战：
  1. 结构变化处理：网页结构可能会有微小变化，因此使用条件判断确保代码健壮性，例如：
    1. 多层嵌套元素：例如释义和例句可能有多个，使用循环处理：
      1. URL 转换：音频链接通常是相对路径，此时需要转换为绝对 URL：
        1. 错误处理：HTML 结构可能因单词不同而变化，使用 try-except 捕获所有异常：

          3.5 测试解析结果

          通过解析 “hello” 单词页面，可以得到如下结构化数据：

          三、实现思路设计

          基于上述分析，Cambridge2API的实现思路如下：
          1. 建立基于 requests 的客户端发送 HTTP 请求
          1. 使用 BeautifulSoup4 解析网页 HTML
          1. 定义数据模型存储结构化的单词信息
          1. 构建命令行接口（CLI）方便直接使用
          1. 使用 FastAPI 提供 Web API 服务

          四、详细实现步骤

          1. 项目结构设计

          首先，设计清晰的项目结构：

          2. 定义数据模型

          数据模型决定了如何存储从网页提取的信息。使用 Python 的 dataclass 来定义模型：

          3. 自定义异常类

          为了更好地处理错误，定义了自定义异常类：

          4. 实现 API 客户端

          客户端负责发送 HTTP 请求并处理响应：

          5. 构建 Web API 服务

          使用 FastAPI 构建 RESTful API，提供更广泛的访问方式：

          6. 实现命令行工具

          为了方便在终端直接使用，可以实现如下命令行工具：

          五、运行与测试

          1. 安装依赖

          首先安装项目依赖：
          依赖包括： - requests: HTTP 请求库 - beautifulsoup4: HTML 解析库 - fastapi: Web 框架 - uvicorn: ASGI 服务器 - pydantic: 数据验证库

          2. 安装项目

          3. 自动补全功能测试

          使用 Python 客户端测试自动补全功能：
          使用命令行工具测试：

          4. 单词查询测试

          使用 Python 客户端查询单词：
          使用命令行工具：

          5. Web API 测试

          启动 Web 服务：
          或者直接运行模块：
          服务启动后，可以通过浏览器访问以下端点：
          • API 文档：http://localhost:8000/docs
          • 查询单词：http://localhost:8000/api/v1/lookup/hello
          • 获取建议：http://localhost:8000/api/v1/suggest/?q=happ
           
          Enjoy 🤪
           
          MY FIRST BLOG新vps到手后我会做的几件事
          Loading...