MyBlog API 接口文档

概述

MyBlog 提供一套 RESTful API，所有接口基于 /api 路径。GET 请求无需认证，写操作（POST/PUT/DELETE）需要在请求头中携带 JWT Token。

Base URL: https://blog.1752667613.xyz/api

认证

登录获取 Token

POST /api/auth/login

请求体:
{
  "password": "your-password"
}

成功响应 (200):
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "message": "登录成功"
}

失败响应 (401):
{
  "error": "密码错误"
}

认证方式

所有写操作需要在请求头中添加：

Authorization: Bearer <token>

Token 同时也会通过 HttpOnly Cookie 设置，有效期 7 天。

检查登录状态

GET /api/auth/check

成功响应: { "authenticated": true }
失败响应: { "authenticated": false }

文章接口

获取文章列表

GET /api/posts?page=1&limit=10&status=published&search=关键词&categoryId=xxx&tag=标签名

响应:
{
  "posts": [...],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3
  }
}

获取单篇文章

GET /api/posts/:id

支持通过 ID 或 slug 查询。
响应: 完整文章对象（含 category、tags）

创建文章

POST /api/posts
Authorization: Bearer <token>

请求体:
{
  "title": "文章标题",        // 必填
  "slug": "article-slug",    // 必填，URL 路径
  "content": "<p>HTML 内容</p>",  // 必填
  "summary": "文章摘要",
  "coverImage": "https://...",
  "status": "published",      // published | draft
  "categoryId": "分类ID",
  "tagNames": ["标签1", "标签2"]
}

成功响应 (201): 创建的文章对象

更新文章

PUT /api/posts/:id
Authorization: Bearer <token>

请求体: 同创建，所有字段均为可选（只传需要更新的）
成功响应 (200): 更新后的文章对象

删除文章

DELETE /api/posts/:id
Authorization: Bearer <token>

成功响应: { "message": "删除成功" }

笔记接口

获取笔记列表

GET /api/notes?page=1&limit=10&status=published&isPublic=true&search=关键词

响应:
{
  "notes": [...],
  "pagination": { ... }
}

获取单条笔记

GET /api/notes/:id

创建笔记

POST /api/notes
Authorization: Bearer <token>

请求体:
{
  "title": "笔记标题",        // 必填
  "content": "<p>内容</p>",   // 必填
  "summary": "笔记摘要",
  "status": "published",
  "isPublic": true,           // 是否公开
  "categoryId": "分类ID",
  "tagNames": ["标签1"]
}

更新笔记

PUT /api/notes/:id
Authorization: Bearer <token>

请求体: 同创建，所有字段可选

删除笔记

DELETE /api/notes/:id
Authorization: Bearer <token>

分类接口

获取分类列表

GET /api/categories?type=post

type 参数可选: post | note
响应: 分类数组，含 _count 统计

创建分类

POST /api/categories
Authorization: Bearer <token>

{ "name": "分类名", "type": "post" }

更新分类

PUT /api/categories/:id
Authorization: Bearer <token>

{ "name": "新名称" }

删除分类

DELETE /api/categories/:id
Authorization: Bearer <token>

标签接口

获取标签列表

GET /api/tags

响应: 标签数组，含关联文章/笔记数量

创建 / 更新 / 删除标签

POST /api/tags         { "name": "标签名" }
PUT /api/tags/:id      { "name": "新名称" }
DELETE /api/tags/:id

图片接口

上传图片

POST /api/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

FormData:
  file: (二进制文件)

成功响应:
{
  "url": "https://xxx.public.blob.vercel-storage.com/...",
  "name": "filename.jpg",
  "size": 123456
}

获取图片列表

GET /api/images?limit=100

响应: { "images": [...], "pagination": {...} }

删除图片

DELETE /api/images/:id
Authorization: Bearer <token>

同时删除 Vercel Blob 存储和数据库记录

缓存刷新

POST /api/revalidate?secret=YOUR_SECRET

手动刷新全站 ISR 缓存。需要在 Vercel 环境变量中设置 REVALIDATE_SECRET。
成功响应: { "revalidated": true, "now": 1710000000000 }

错误格式

所有错误响应遵循统一格式：

{
  "error": "错误描述信息"
}

常见状态码：400（参数错误）、401（未授权）、404（不存在）、500（服务端错误）

概述