Blog API Example (V2)

这是一个使用 API Forge V2 构建的完整博客 API 示例，展示了框架的核心功能和配置驱动架构。

🎉 已升级到 V2: 此项目已迁移到 API Forge V2 配置系统。查看 MIGRATION.md 了解迁移详情。

功能特性

• 📝 文章管理：创建、编辑、发布、归档文章
• 👤 用户系统：注册、登录、个人资料管理
• 💬 评论系统：文章评论、回复、点赞
• 🏷️ 标签分类：文章标签和分类管理
• 🔍 全文搜索：基于 PostgreSQL 的全文搜索
• 📊 统计分析：阅读量、点赞数等统计
• 🖼️ 图片上传：支持文章配图和用户头像
• ⚡ 高性能：Redis 缓存、队列处理
• 🔐 安全认证：JWT 认证、权限控制

快速开始

1. 安装依赖

cd examples/blog-api
bun install

2. 环境配置

复制示例环境变量文件：

cp .env.example .env

编辑 .env 文件，设置你的配置值。主要配置项：

• DATABASE_URL - PostgreSQL 连接字符串
• REDIS_URL - Redis 连接字符串
• JWT_SECRET - JWT 签名密钥
• STORAGE_PROVIDER - 存储方式（local 或 s3）

3. 数据库设置

# 创建数据库
createdb blog_api

# 运行迁移（自动创建）
bun run dev

4. 启动服务

# 开发模式
bun run dev

# 生产构建
bun run build
bun run start

服务将在 http://localhost:3001 启动

API 端点

认证相关

• POST /api/v1/auth/register - 用户注册
• POST /api/v1/auth/login - 用户登录
• POST /api/v1/auth/refresh - 刷新令牌
• POST /api/v1/auth/logout - 用户登出

用户相关

• GET /api/v1/users/:id - 获取用户信息
• PUT /api/v1/users/:id - 更新用户信息
• POST /api/v1/users/:id/avatar - 上传头像
• GET /api/v1/users/:id/posts - 获取用户文章

文章相关

• GET /api/v1/posts - 获取文章列表
• GET /api/v1/posts/:id - 获取文章详情
• POST /api/v1/posts - 创建文章
• PUT /api/v1/posts/:id - 更新文章
• DELETE /api/v1/posts/:id - 删除文章
• POST /api/v1/posts/:id/publish - 发布文章
• POST /api/v1/posts/:id/like - 点赞文章

评论相关

• GET /api/v1/posts/:id/comments - 获取文章评论
• POST /api/v1/posts/:id/comments - 发表评论
• PUT /api/v1/comments/:id - 更新评论
• DELETE /api/v1/comments/:id - 删除评论
• POST /api/v1/comments/:id/like - 点赞评论

标签和分类

• GET /api/v1/tags - 获取标签列表
• GET /api/v1/categories - 获取分类列表
• GET /api/v1/tags/:slug/posts - 获取标签下的文章

搜索和统计

• GET /api/v1/search - 全文搜索
• GET /api/v1/stats - 获取统计数据
• GET /api/v1/trending - 热门文章

项目结构

blog-api/
├── api/                    # API 配置文件
│   ├── auth.json          # 认证相关
│   ├── users.json         # 用户管理
│   ├── posts.json         # 文章管理
│   ├── comments.json      # 评论系统
│   ├── tags.json          # 标签管理
│   └── search.json        # 搜索功能
├── handlers/              # 自定义处理器
│   ├── auth.js           # 认证逻辑
│   ├── posts.js          # 文章逻辑
│   └── search.js         # 搜索实现
├── hooks/                 # 生命周期钩子
│   ├── validate-auth.js  # 认证验证
│   └── cache-invalidate.js # 缓存清理
├── scripts/              # 工具脚本
│   └── seed.ts          # 数据填充
├── sdk/                  # 自动生成的 SDK
└── uploads/              # 本地文件存储

使用生成的 SDK

import { BlogApiClient } from './sdk';

const client = new BlogApiClient({
  baseURL: 'http://localhost:3001'
});

// 用户注册
const { user, token } = await client.auth.register({
  username: 'johndoe',
  email: '[email protected]',
  password: 'secure-password'
});

// 设置认证
client.setAuthToken(token);

// 创建文章
const post = await client.posts.create({
  title: 'My First Post',
  content: 'Hello, world!',
  tags: ['hello', 'world'],
  categoryId: 1
});

// 搜索文章
const results = await client.search({
  query: 'API Forge',
  type: 'posts'
});

高级功能

缓存策略

文章列表和详情都使用了 Redis 缓存：

• 列表缓存 5 分钟
• 详情缓存 10 分钟
• 用户操作自动清理相关缓存

图片处理

上传的图片会自动：

• 生成缩略图（150x150）
• 转换为 WebP 格式
• 压缩优化

任务队列

使用队列处理耗时操作：

• 发送邮件通知
• 生成文章摘要
• 更新搜索索引

定时任务

• 每天凌晨清理过期会话
• 每小时更新热门文章
• 每周生成统计报告

性能优化

1. 数据库索引：自动为常用查询创建索引
2. 分页加载：使用游标分页避免深度分页
3. 懒加载：评论和相关文章按需加载
4. CDN 集成：静态资源通过 CDN 分发

部署指南

Docker 部署

FROM oven/bun:latest

WORKDIR /app

COPY package.json bun.lockb ./
RUN bun install --production

COPY . .
RUN bun run build

EXPOSE 3001
CMD ["bun", "run", "start"]

环境变量

生产环境必需的环境变量：

• NODE_ENV=production
• DATABASE_URL - PostgreSQL 连接字符串
• REDIS_URL - Redis 连接字符串
• JWT_SECRET - JWT 签名密钥
• S3_* - S3/R2 存储配置

扩展建议

1. 添加 OAuth：集成 GitHub、Google 登录
2. 订阅功能：用户订阅作者或标签
3. 草稿自动保存：使用 Redis 存储草稿
4. Markdown 编辑器：前端集成 MD 编辑器
5. RSS 订阅：生成 RSS feed
6. 评论审核：垃圾评论过滤
7. 多语言支持：i18n 国际化

常见问题

如何重置数据库？

# 删除并重建数据库
dropdb blog_api
createdb blog_api
bun run dev

如何填充测试数据？

bun run seed

如何查看 API 文档？

访问 http://localhost:3001/api-docs

许可证

MIT