Skip to main content

快速开始（第三方应用集成）

本指南面向第三方应用开发者，目标是在 15 分钟内跑通一次「用户授权 → 调用 API」的完整链路。

约定​

  • BASE_URL：你的 vocnet 实例地址（例如 https://vocnet.apps.tftt.cc 或 http://localhost:8080）

前置条件​

开始集成前，你需要：

  • Vocnet 实例：官方托管或你自建的 vocnet 服务
  • OAuth2 凭证：client_id 与 client_secret
  • 任意后端运行环境（示例使用 curl / Go / TypeScript）
获取开发者凭证

如果你使用官方托管实例，通常需要通过 GitHub Issue 申请开发者应用（人工审核）。

提交申请：https://github.com/eslsoft/vocnet/issues/new

第一步：注册开发者应用​

创建应用​

  1. 登录 Vocnet 开发者控制台
  2. 点击「创建应用」
  3. 填写应用信息：
    • 应用名称 - 例如「MyReadingApp」
    • 应用描述 - 简短介绍你的应用
    • 回调 URL - OAuth2 授权回调地址（例如：https://yourapp.com/oauth/callback）
    • 权限范围 - 选择需要的 API 权限
  4. 提交后获得：
    • Client ID - 应用唯一标识
    • Client Secret - 应用密钥（请妥善保管）

权限范围​

根据你的应用需求，申请相应的权限：

权限说明
words:read读取用户的词汇数据
words:write添加/更新用户的词汇
review:read查看复习计划和记录
review:write提交复习结果
wordbooks:read读取词本信息
wordbooks:write创建/管理词本
最小权限原则

只申请你的应用实际需要的权限，避免过度授权。

第二步：实现 OAuth2 授权流程​

Vocnet 使用标准的 OAuth 2.0 授权码模式。

2.1 引导用户授权​

在你的应用中添加「连接 Vocnet」按钮，跳转到授权页面：

{BASE_URL}/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/oauth/callback&
  response_type=code&
  scope=words:read words:write&
  state=RANDOM_STATE_STRING

参数说明：

  • client_id - 你的应用 Client ID
  • redirect_uri - 授权后的回调地址（需与注册时一致）
  • response_type - 固定为 code
  • scope - 请求的权限，空格分隔
  • state - 随机字符串，用于防止 CSRF 攻击

2.2 处理回调​

用户同意授权后，Vocnet 会重定向到你的回调地址，并携带授权码：

https://yourapp.com/oauth/callback?code=AUTHORIZATION_CODE&state=RANDOM_STATE_STRING

验证 state 参数，确保与发起请求时一致。

2.3 交换 Access Token​

使用授权码换取 Access Token：

curl -X POST {BASE_URL}/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code' \
  -d 'code=AUTHORIZATION_CODE' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET' \
  -d 'redirect_uri=https://yourapp.com/oauth/callback'

响应示例：

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "def50200...",
  "scope": "words:read words:write"
}
Token 管理
  • Access Token 用于调用 API，有效期通常为 1 小时
  • Refresh Token 用于刷新 Access Token，有效期较长 - 记得处理 Token 过期和刷新逻辑

更完整的说明见：OAuth2 授权

第三步：调用 API​

拿到 Access Token 后，就可以调用 Vocnet API 了。

3.1 收藏单词​

为用户添加新词汇到 Vocnet：

curl -X POST {BASE_URL}/api/v1/learning/collect-word \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -d '{
    "spec": {
      "term": "apple",
      "language": "LANGUAGE_ENGLISH",
      "mastery_level": 0,
      "tags": ["fruit", "food"],
      "notes": ["常见水果", "red or green"]
    }
  }'

响应示例：

{
  "learned_word": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "term": "apple",
    "language": "LANGUAGE_ENGLISH",
    "mastery_level": 0,
    "created_at": "2024-12-13T10:00:00Z"
  }
}

3.2 查询已学词汇​

获取用户的词汇列表：

curl {BASE_URL}/api/v1/learning/learned-words \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -G \
  --data-urlencode 'page_size=20' \
  --data-urlencode 'page_token=' \
  --data-urlencode 'filter=language == "LANGUAGE_ENGLISH"'

响应示例：

{
  "learned_words": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "term": "apple",
      "mastery_level": 2,
      "last_reviewed_at": "2024-12-12T15:30:00Z"
    },
    {
      "id": "223e4567-e89b-12d3-a456-426614174001",
      "term": "banana",
      "mastery_level": 3,
      "last_reviewed_at": "2024-12-11T09:20:00Z"
    }
  ],
  "next_page_token": "eyJvZmZzZXQiOjIwfQ=="
}

3.3 获取复习卡片​

为用户生成今日复习任务：

curl -X POST {BASE_URL}/api/v1/review-plans/{plan_id}/flashcards \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "limit": 20
  }'

响应包含复习卡片列表，包括题目类型、选项、正确答案等。

3.4 提交复习结果​

用户完成复习后，提交结果以更新掌握度：

curl -X POST {BASE_URL}/api/v1/review-plans/{plan_id}/submit-answer \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "flashcard_id": "flashcard-id-here",
    "user_answer": "apple",
    "is_correct": true,
    "time_spent_ms": 5000
  }'

Vocnet 会根据答题情况自动调整下次复习时间。

第四步：使用 SDK（推荐）​

手动构造 HTTP 请求比较繁琐，推荐使用官方 SDK。

Go SDK​

import (
    "context"
    "github.com/eslsoft/vocnet-go-sdk/client"
)

// 初始化客户端
vocnetClient := client.New(
    client.WithBaseURL("https://vocnet.apps.tftt.cc"),
    client.WithAccessToken(accessToken),
)

// 收藏单词
resp, err := vocnetClient.Learning.CollectWord(context.Background(), &learning.CollectWordRequest{
    Spec: &learning.LearnedWordSpec{
        Term:         "apple",
        Language:     learning.Language_LANGUAGE_ENGLISH,
        MasteryLevel: 0,
        Tags:         []string{"fruit"},
    },
})

TypeScript SDK​

import { VocnetClient } from "@vocnet/sdk";

const client = new VocnetClient({
  baseURL: "https://vocnet.apps.tftt.cc",
  accessToken: accessToken,
});

// 收藏单词
const response = await client.learning.collectWord({
  spec: {
    term: "apple",
    language: "LANGUAGE_ENGLISH",
    masteryLevel: 0,
    tags: ["fruit"],
  },
});
SDK 文档

SDK 相关说明见：SDK

常见问题​

如何测试 API？​

你可以在本地运行 Vocnet 实例进行开发测试：

git clone https://github.com/eslsoft/vocnet.git
cd vocnet
make setup
make run

服务会启动在 localhost:8080。详见：自建部署指南

Token 过期了怎么办？​

使用 Refresh Token 刷新 Access Token：

curl -X POST {BASE_URL}/oauth/token \
  -d 'grant_type=refresh_token' \
  -d 'refresh_token=YOUR_REFRESH_TOKEN' \
  -d 'client_id=YOUR_CLIENT_ID' \
  -d 'client_secret=YOUR_CLIENT_SECRET'

如何处理 API 错误？​

Vocnet API 使用标准的 HTTP 状态码：

  • 200 - 成功
  • 400 - 请求参数错误
  • 401 - 未授权（Token 无效或过期）
  • 403 - 禁止访问（权限不足）
  • 404 - 资源不存在
  • 429 - 请求过于频繁
  • 500 - 服务器错误

错误响应示例：

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Invalid language code",
    "details": []
  }
}

有 API 调用限制吗？​

是的，为保证服务质量，Vocnet 对 API 调用有频率限制：

  • 默认：1000 请求/小时
  • 超出后返回 429 Too Many Requests
  • 响应头会包含限流信息：X-RateLimit-Limit, X-RateLimit-Remaining

如需更高额度，请联系我们。

下一步​

恭喜你已经完成了基本的 API 集成！接下来你可以：

深入学习
技术资源
需要帮助？

祝你集成顺利！