GenGen 洛谷国际 —— API 文档

General00826 · 2026-02-21 21:55:50 · 个人记录

GenGen 洛谷国际 —— API 文档

欢迎访问 luogu.qzz.io/api/（以下简称"本 API"）。

本 API 是一个非官方的公开内容代理接口，主要用于获取与展示来自洛谷的公开页面内容（文章/云剪贴板）。

一、基本原则

本 API 遵循以下服务原则：

仅代理公开可访问的页面内容
优先返回缓存数据以降低源站压力
不提供用户认证、写操作或私有数据访问
接口设计保持简洁，便于前端直接调用

二、基础信息

1. 接口地址

https://luogu.qzz.io/api

2. 请求方式

仅支持 GET 请求
响应格式：application/json; charset=utf-8
默认启用 CORS：Access-Control-Allow-Origin: *

3. 路径规范

类型	路径格式	说明
文章	`/api/a/{id}`	获取洛谷文章 Markdown 内容
云剪贴板	`/api/p/{id}`	获取洛谷 Paste 代码/文本内容

参数说明：

{id}：洛谷原站的文章 ID 或 Paste ID，由大小写字母与数字组成

三、请求示例

1. 获取文章内容

GET /api/a/12345 HTTP/1.1
Host: luogu.qzz.io

2. 获取云剪贴板内容

GET /api/p/abcde HTTP/1.1
Host: luogu.qzz.io

3. 强制刷新缓存

GET /api/a/12345?update=1 HTTP/1.1
Host: luogu.qzz.io

添加 ?update=1 参数可跳过缓存，直接抓取源站最新内容并更新本地缓存。

四、响应格式

1. 成功响应（200）

{
  "success": true,
  "type": "article",
  "id": "12345",
  "content": "# 文章标题\n\n正文内容...",
  "title": "文章标题",
  "author": {
    "uid": 1351126,
    "name": "作者名称"
  },
  "original_url": "https://www.luogu.com/article/12345",
  "cached": true,
  "updated_at": 1715623400000
}

2. 字段说明

字段	类型	说明
`success`	boolean	请求是否成功
`type`	string	内容类型：`article` 或 `paste`
`id`	string	内容唯一标识
`content`	string	Markdown 格式的正文内容
`title`	string\|null	内容标题
`author`	object\|null	作者信息 `{uid, name}`
`original_url`	string	洛谷原站链接
`cached`	boolean	是否来自缓存
`updated_at`	number	时间戳（毫秒）

五、错误响应

1. 资源未找到（404）

{
  "error": "Not Found",
  "code": 404
}

2. 请求被拒绝（403）

{
  "error": "Forbidden",
  "code": 403
}

触发条件：请求头包含 cf-worker 字段时，存在概率性拦截。

3. 抓取或解析失败（502 / 500）

{
  "error": "lentille-context not found",
  "code": 502
}

{
  "error": "Parse error: Unexpected token",
  "code": 502
}

4. 错误码汇总

Code	含义	可能原因
403	Forbidden	触发反代理检测机制
404	Not Found	路径不匹配或 ID 无效
500	Internal Error	源站数据结构异常
502	Bad Gateway	代理失败或 JSON 解析错误

六、缓存机制

1. 缓存策略

数据存储于 Cloudflare D1 / SQLite 数据库 cache_v2 表
缓存键格式：{type}:{id}（如 article:12345）
读取时优先查询缓存，未命中则代理抓取并写入

2. 缓存更新

方式	说明
自动更新	缓存未命中时自动抓取并存储
手动刷新	添加 `?update=1` 参数强制重新抓取

3. 缓存数据结构（参考）

CREATE TABLE cache_v2 (
  key TEXT PRIMARY KEY,
  content TEXT,
  metadata TEXT,
  updated_at INTEGER
);

七、使用限制与注意事项

1. 频率建议

本 API 无硬性限流，但请避免高频请求
建议前端对相同 ID 内容做本地缓存

2. 请求头注意事项

:::::error[请勿使用 Cloudflare 进行反代]{open} 若检测到该字段，服务端将：

50% 概率直接返回 403 Forbidden
40% 概率返回污染数据（含干扰内容）

::::info[为什么抵制 Cloudflare 反代？]{open}

违背初心：我们是"内容保存站"，不是"免费代理层"。反代嵌套让我们沦为流量中转，偏离服务本质。
成本真实：境外流量与请求数均计费。反代调用产生的账单，无法由我们无限承担。
责任模糊：链路过长导致故障难定位，用户投诉最终指向我们，但问题可能出在调用方。 :::success[欢迎直连调用、注明来源] ::: :::error[抵制嵌套反代、二次分发、修改响应。] ::: 直连是合作，反代是转嫁。我们支持前者，无法接受后者。我们仅对含 cf-worker 头的反代请求随机返回提示，本意是提醒违规调用，非恶意抹黑。

我们抵制的是"未经协商的嵌套调用"，而非社区协作本身。互惠才是规范核心。

:::::

3. 源站依赖

内容抓取依赖其他的服务器代理中转
若代理服务不可用，仅缓存内容可正常返回

4. 内容解析依赖

文章：依赖洛谷页面 <script id="lentille-context"> 结构
Paste：依赖 window._feInjection 注入数据
若洛谷前端重构，可能导致解析失败

八、第三方服务说明

本 API 基础设施依赖于 Cloudflare 与其他中转服务。本 API 所代理内容来源于：

洛谷原站（https://www.luogu.com）

访问 original_url 时将跳转至第三方站点，其服务条款与隐私政策不受本 API 约束。

九、免责声明

本 API 为非官方第三方服务，与洛谷无任何隶属或合作关系。
不保证接口长期可用，可能因源站策略变更而随时调整或停止服务。
缓存内容可能存在延迟，不保证与源站实时一致。
使用者应自行评估合规性，避免用于高频爬取或商业用途。
因使用本 API 产生的任何数据误差或服务中断，本项目不承担法律责任。

十、内容删除与反馈

如果您认为某些缓存内容：

侵犯您的合法权益
涉及不应公开保存的个人信息
存在解析错误或安全风险

您可通过以下方式提交反馈：

访问 GenGen 队官网
通过站内联系方式提交删除请求

我们将在合理时间内：

核实请求内容与合法性
在技术可行范围内删除或更新相关缓存

十一、政策更新

我们可能根据技术演进或法律要求对本 API 文档进行更新。更新版本将发布于本页面，并注明最后更新日期。

最后更新：2026-02-21

开源社区说明

本 API 为一个非官方、非商业化的内容代理项目。

开发：GenGen 队

联系方式

如有 API 使用问题、内容反馈或合作意向，请联系 GenGen 队。