文章接口文档.

接入概览

文章目录接口

返回分页文章数组。每一条文章记录都已经包含完整正文、图片、音视频 HTML，不必再逐条请求详情接口。

查询参数

直接调用

curl -sS 'https://linuxword.com/wp-json/linuxword/v1/articles?page=1&per_page=20'

成功响应结构

以下为字段结构示例，示例正文和数字仅用于说明；实际接口返回文章完整内容和当前数据。

{
    "success": true,
    "pagination": {
        "page": 1,
        "per_page": 1,
        "total": 3533,
        "total_pages": 3533,
        "has_more": true
    },
    "articles": [
        {
            "id": 57054,
            "title": "示例文章",
            "published_at": "2026-10-22T18:07:58+08:00",
            "published_at_gmt": "2026-10-22T10:07:58Z",
            "updated_at": "2026-10-22T18:07:58+08:00",
            "views": 87,
            "url": "https://linuxword.com/articles/57054/",
            "detail_url": "https://linuxword.com/articles/57054/",
            "api_url": "https://linuxword.com/wp-json/linuxword/v1/articles/57054",
            "content_html": "<p>这里是这篇示例文章的完整正文。</p><img src=\"https://linuxword.com/wp-content/uploads/2026/10/afsfsdfsfds.jpg\" alt=\"文章配图\">",
            "content_text": "这里是这篇示例文章的完整正文。",
            "cover_url": "https://linuxword.com/wp-content/uploads/2026/10/afsfsdfsfds.jpg",
            "cover_image": {
                "url": "https://linuxword.com/wp-content/uploads/2026/10/afsfsdfsfds.jpg",
                "source": "content_image",
                "attachment_id": null,
                "width": null,
                "height": null,
                "alt": "文章配图",
                "updated_at": "2026-10-22T18:07:58+08:00"
            },
            "categories": [
                {
                    "id": 19,
                    "name": "Linux技术",
                    "slug": "linux"
                }
            ],
            "tags": []
        }
    ]
}

分页字段

目录响应头同时提供 X-WP-Total 和 X-WP-TotalPages。接入程序也可直接使用 JSON 中的分页字段。

文章详情接口

将 {id} 替换为文章 ID，例如 57054。ID 从目录响应的 articles[].id 获取。详情返回的文章对象与目录中的完整文章对象字段一致。

curl -sS 'https://linuxword.com/wp-json/linuxword/v1/articles/57054'

{
    "success": true,
    "article": {
        "id": 57054,
        "title": "示例文章",
        "published_at": "2026-10-22T18:07:58+08:00",
        "published_at_gmt": "2026-10-22T10:07:58Z",
        "updated_at": "2026-10-22T18:07:58+08:00",
        "views": 87,
        "url": "https://linuxword.com/articles/57054/",
        "detail_url": "https://linuxword.com/articles/57054/",
        "api_url": "https://linuxword.com/wp-json/linuxword/v1/articles/57054",
        "content_html": "<p>这里是这篇示例文章的完整正文。</p><img src=\"https://linuxword.com/wp-content/uploads/2026/10/afsfsdfsfds.jpg\" alt=\"文章配图\">",
        "content_text": "这里是这篇示例文章的完整正文。",
        "cover_url": "https://linuxword.com/wp-content/uploads/2026/10/afsfsdfsfds.jpg",
        "cover_image": {
            "url": "https://linuxword.com/wp-content/uploads/2026/10/afsfsdfsfds.jpg",
            "source": "content_image",
            "attachment_id": null,
            "width": null,
            "height": null,
            "alt": "文章配图",
            "updated_at": "2026-10-22T18:07:58+08:00"
        },
        "categories": [
            {
                "id": 19,
                "name": "Linux技术",
                "slug": "linux"
            }
        ],
        "tags": []
    }
}

读取 article.content_html 即可取得全部图文、音视频正文，没有“阅读全文”或原文跳转步骤。

完整文章字段

以下字段同时出现在 articles[] 和 article 中。

文章封面与更新同步

cover_url 可直接作为图片地址使用，与 cover_image.url 一致。封面优先使用 WordPress 特色图；未设置时提取正文第一张有效图片，跳过表情和微型跟踪图片；正文也没有图片时，尝试视频的 poster 海报。完全没有图片时两个字段均返回 null。

更换、移除特色图或更新关联媒体元数据后，接口会清除内部缓存并更新文章的 updated_at，因此可继续使用 modified_after 增量获取封面变更。正文首图发生变化时，保存文章同样会触发更新。已变更的本站封面地址附带 lw_cover 版本参数，接入方应原样使用返回地址；第三方图片地址不追加参数。

API 的浏览器缓存有效期为 30 秒，共享缓存有效期为 60 秒；已缓存的响应可能在此期间仍显示上一版。站外图片文件的变化需要对应文章或关联媒体在本站保存更新后才能被同步识别。

接口不返回 source_url 原文跳转字段，也不要求调用额外的正文加载接口。

调用示例

JavaScript：一次获取完整目录内容

// 目录每条记录已经有全文，不需要循环请求详情接口。
const response = await fetch(
  'https://linuxword.com/wp-json/linuxword/v1/articles?per_page=20&page=1',
  { headers: { Accept: 'application/json' } }
);
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data = await response.json();
for (const article of data.articles) {
  console.log(article.id, article.title, article.published_at, article.views);
  console.log(article.cover_url, article.cover_image); // 封面地址与元数据
  console.log(article.content_html); // 完整图文、音视频 HTML
}

// 已知文章 ID 时，直接获取该文章全部内容。
const detail = await fetch(
  'https://linuxword.com/wp-json/linuxword/v1/articles/57054'
).then(response => response.json());
console.log(detail.article.content_html);

Python：按页保存全部完整文章

使用 Python 标准库即可运行，无需安装第三方依赖。文章按 ID 保存，文件中包含完整 content_html。

import json
import time
import urllib.error
import urllib.parse
import urllib.request
from pathlib import Path

endpoint = 'https://linuxword.com/wp-json/linuxword/v1/articles'
output = Path('linuxword-articles')
output.mkdir(exist_ok=True)
page = 1

while True:
    params = urllib.parse.urlencode({
        'page': page, 'per_page': 100, 'order': 'asc'
    })
    request = urllib.request.Request(
        endpoint + '?' + params,
        headers={'Accept': 'application/json', 'User-Agent': 'MyArticleSync/1.0'}
    )
    for attempt in range(5):
        try:
            with urllib.request.urlopen(request, timeout=60) as response:
                data = json.load(response)
            break
        except urllib.error.HTTPError as error:
            if error.code not in (429, 502, 503, 504) or attempt == 4:
                raise
            time.sleep(2 ** attempt)

    for article in data['articles']:
        # 每份 JSON 已有完整正文及媒体 HTML，不需要再请求详情。
        (output / f"{article['id']}.json").write_text(
            json.dumps(article, ensure_ascii=False, indent=2),
            encoding='utf-8'
        )
    if not data['pagination']['has_more']:
        break
    page += 1
    time.sleep(0.3)

全量与增量同步

1. 全量同步从 page=1 开始，推荐 per_page=100&order=asc，按 has_more 继续读取下一页。
2. 以 id 为主键保存或更新文章；目录中已经包含全文，无需再逐篇读取详情。
3. 后续用 modified_after、orderby=modified、order=asc 获取修改后的文章，同样按页读取。
4. 建议保留 1–2 分钟的时间重叠窗口，并按 id、updated_at 去重更新，避免同秒修改或缓存延迟造成遗漏。

https://linuxword.com/wp-json/linuxword/v1/articles?modified_after=2026-10-01T00%3A00%3A00Z&orderby=modified&order=asc&per_page=100&page=1

时间过滤条件为“修改时间晚于指定时间”。接口不提供删除事件；文章下线后详情返回 404，需要定期全量核对已保存的文章。

缓存与请求频率

GET 响应允许浏览器缓存 30 秒、共享缓存 60 秒，正文服务端缓存 300 秒，保存文章后会失效重建。建议顺序请求；源站当前每 IP 约 5 次/秒、短时突发队列 20 次，超限会返回 429。发生限流或临时网关错误时，按 1、2、4、8 秒退避后重试。

状态码与错误响应

文章不存在时的 JSON 示例

{
    "code": "article_not_found",
    "message": "文章不存在或尚未公开。",
    "data": {
        "status": 404
    }
}

错误响应使用 code、message、data.status，不使用成功响应的文章包装结构。参数校验错误还可能包含具体字段说明。

正文与音视频展示

将 content_html 交给支持 HTML 的页面、WebView 或富文本组件即可展示完整文章。图片、音频、视频和嵌入内容已经保留在 HTML 中，媒体文件由其中的地址直接加载；它们不是 Base64 文件数据。

音视频带播放控件，默认不自动播放，只预加载媒体信息。正文中的可识别本站文章链接已指向新全文阅读页；不需要返回旧主题或点击“查看原文”。content_text 适合搜索和文本存档，不能替代图文播放器展示。