本文档提供了RealWorld项目中与文章相关的API端点的详细技术文档。它涵盖了检索、创建、更新和删除文章的端点，以及收藏功能。有关文章评论的信息，请参阅评论和标签端点。
文章是RealWorld应用程序的核心实体。在探索端点之前，理解数据模型非常重要。
来源： apps/api/prisma/migrations/20241009081140_init/migration.sql1-95
文章实体包含
id)slug)title, description, body)createdAt, updatedAt)authorId)一篇文章可以有多个标签和评论，也可以被多个用户收藏。
API提供了多个用于处理文章的端点
这些端点检索文章列表，并支持可选过滤。
全局检索文章，支持可选过滤。
认证：可选
查询参数:
| 参数 | 类型 | 描述 |
|---|---|---|
| tag | 字符串 | 按标签名称过滤 |
| 作者 | 字符串 | 按作者用户名过滤 |
| favorited | 字符串 | 按收藏用户的用户名过滤 |
| limit | 整数 | 限制结果数量（默认：20） |
| offset | 整数 | 偏移/跳过结果数量 |
响应：返回文章对象数组和总计数。请注意，自2024年8月16日起，为提高性能，文章正文将不包含在列表响应中。
{
"articles": [...], // Array of article objects
"articlesCount": 123 // Total number of articles matching the query
}
来源： api/openapi.yml174-205 apps/documentation/src/content/docs/specifications/backend/api-response-format.md62-103
检索已关注用户的文章。
认证：必需
查询参数:
| 参数 | 类型 | 描述 |
|---|---|---|
| limit | 整数 | 限制结果数量（默认：20） |
| offset | 整数 | 偏移/跳过结果数量 |
响应：格式与GET /articles相同。
这些端点处理对单个文章的操作。
通过 slug 检索单个文章。
认证：不需要
路径参数:
| 参数 | 类型 | 描述 |
|---|---|---|
| slug | 字符串 | 要检索的文章的 slug |
响应：返回一个包含完整详情（包括正文内容）的单个文章对象。
来源： api/openapi.yml224-242 apps/documentation/src/content/docs/specifications/backend/api-response-format.md36-58
创建新文章。
认证：必需
请求体:
{
"article": {
"title": "How to train your dragon",
"description": "Ever wonder how?",
"body": "It takes a Jacobian",
"tagList": ["dragons", "training"]
}
}
响应：返回新创建的文章。
来源： api/openapi.yml206-223 api/openapi.yml535-551
更新现有文章。
认证：必需（必须是文章作者）
路径参数:
| 参数 | 类型 | 描述 |
|---|---|---|
| slug | 字符串 | 要更新的文章的 slug |
请求体:
{
"article": {
"title": "Updated title",
"description": "Updated description",
"body": "Updated body"
}
}
所有字段都是可选的。
响应：返回更新后的文章。
来源： api/openapi.yml243-267 api/openapi.yml552-560
删除文章。
认证：必需（必须是文章作者）
路径参数:
| 参数 | 类型 | 描述 |
|---|---|---|
| slug | 字符串 | 要删除的文章的 slug |
响应：返回一个空的响应，状态码为 200。
这些端点允许用户收藏和取消收藏文章。
将文章标记为当前用户已收藏。
认证：必需
路径参数:
| 参数 | 类型 | 描述 |
|---|---|---|
| slug | 字符串 | 要收藏的文章的 slug |
响应：返回文章，包含更新后的favorited状态和favoritesCount。
取消文章的收藏标记。
认证：必需
路径参数:
| 参数 | 类型 | 描述 |
|---|---|---|
| slug | 字符串 | 要取消收藏的文章的 slug |
响应：返回文章，包含更新后的favorited状态和favoritesCount。
下图说明了系统中文章的典型生命周期
当文章在 API 中返回时，它遵循此结构
| 字段 | 类型 | 描述 |
|---|---|---|
| slug | 字符串 | URL友好的标识符 |
| title | 字符串 | 文章标题 |
| description | 字符串 | 简短描述 |
| body | 字符串 | 完整的文章内容（不在列表响应中） |
| tagList | array | 标签字符串数组 |
| createdAt | 字符串 | ISO 8601 时间戳 |
| updatedAt | 字符串 | ISO 8601 时间戳 |
| favorited | 布尔值 | 当前用户是否已收藏 |
| favoritesCount | 整数 | 收藏总数 |
| 作者 | 对象 | 作者的 Profile 对象 |
来源： api/openapi.yml497-534 apps/documentation/src/content/docs/specifications/backend/api-response-format.md36-103
所有文章端点都可能返回以下错误响应
| 状态码 | 描述 |
|---|---|
| 401 | 未授权 - 需要身份验证 |
| 422 | Validation error - Request doesn't meet the requirements |
当没有有效 token 访问受保护的端点时，会发生身份验证错误。创建或更新无效数据时，可能会发生验证错误。
文章模型在数据库中实现，具有以下关系
来源： apps/api/prisma/migrations/20241009081140_init/migration.sql1-95
数据库模式强制执行级联删除，这意味着当删除一篇文章时，所有关联的评论、收藏和标签关联也会被删除。