forked from carrydela/Rs_blog_front
first commit
This commit is contained in:
dela
243
docs/apidev.md
Normal file
243
docs/apidev.md
Normal file
@@ -0,0 +1,243 @@
|
||||
太棒了。既然前端视觉风格（极简 + Inter + 锐利图片）已经确认，接下来我们进入 **逻辑层**。
|
||||
|
||||
这是第二份文档：**《Rust Backend API 集成指南 (Backend Integration Spec)》**。
|
||||
|
||||
这份文档将指导你如何将那个“冷峻”的界面与 Rust 后端进行优雅对接。我们不仅关注数据获取，更关注**数据如何驱动极简交互**（例如：如何用数据加载状态代替复杂的 Loading 动画）。
|
||||
|
||||
---
|
||||
|
||||
# 🔌 后端对接集成文档 (API Integration Spec)
|
||||
|
||||
**后端服务**: Rust Blog Backend
|
||||
**Base URL**: `http://127.0.0.1:8765`
|
||||
**协议**: REST / JSON
|
||||
**认证**: Bearer Token
|
||||
|
||||
---
|
||||
|
||||
## 1. 数据模型定义 (TypeScript Interfaces)
|
||||
|
||||
为了确保前端代码的健壮性，我们需要根据 OpenAPI 文档定义严格的 TypeScript 接口。建议存放在 `src/types/api.ts`。
|
||||
|
||||
```typescript
|
||||
// 基础响应包装（根据 Rust 后端习惯，通常可能直接返回数据或包裹在 data 字段）
|
||||
// 针对此 API 文档的直接映射：
|
||||
export interface ApiResponse<T> {
|
||||
[key: string]: any;
|
||||
// 注意：实际调试时请确认后端是否包裹了 { data: ... } 结构
|
||||
}
|
||||
|
||||
// 1. 认证模型 (Auth)
|
||||
export interface LoginRequest {
|
||||
email: string;
|
||||
password: string;
|
||||
}
|
||||
|
||||
export interface AuthResponse {
|
||||
token: string; // 假设后端返回 JWT 字段
|
||||
user: {
|
||||
id: string;
|
||||
email: string;
|
||||
};
|
||||
}
|
||||
|
||||
// 2. 文章模型 (Post)
|
||||
export interface Post {
|
||||
id: string; // 对应 Rust 的 UUID
|
||||
title: string; // 对应 OpenAPI schema
|
||||
content: string; // Markdown 原始内容
|
||||
published: boolean;
|
||||
created_at?: string; // ISO 8601 Date String
|
||||
cover_image?: string; // 文章封面图 URL (可选)
|
||||
}
|
||||
|
||||
// 3. 分页参数 (Pagination)
|
||||
export interface PageParams {
|
||||
page: number; // e.g. 1
|
||||
limit: number; // e.g. 10
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. API 客户端封装 (Service Layer)
|
||||
|
||||
为了保持组件的“极简”，不要在组件内部直接写 `fetch`。建议封装一个 `apiClient`。
|
||||
|
||||
**文件**: `src/lib/api.ts`
|
||||
|
||||
```typescript
|
||||
const BASE_URL = 'http://127.0.0.1:8765/api';
|
||||
|
||||
// 极简的 Fetch 封装，自动处理 Token 和 错误
|
||||
async function request<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
|
||||
const token = localStorage.getItem('auth_token');
|
||||
|
||||
const headers = {
|
||||
'Content-Type': 'application/json',
|
||||
...(token && { 'Authorization': `Bearer ${token}` }),
|
||||
...options.headers,
|
||||
};
|
||||
|
||||
const response = await fetch(`${BASE_URL}${endpoint}`, {
|
||||
...options,
|
||||
headers,
|
||||
});
|
||||
|
||||
// 极简错误处理：直接抛出状态码，由 UI 层决定是变红框还是显示线条
|
||||
if (!response.ok) {
|
||||
throw { status: response.status, message: response.statusText };
|
||||
}
|
||||
|
||||
// 处理 204 No Content
|
||||
if (response.status === 204) return {} as T;
|
||||
|
||||
return response.json();
|
||||
}
|
||||
|
||||
// 核心服务导出
|
||||
export const api = {
|
||||
// Auth
|
||||
login: (data: LoginRequest) => request<AuthResponse>('/auth/login', {
|
||||
method: 'POST',
|
||||
body: JSON.stringify(data),
|
||||
}),
|
||||
|
||||
// Posts
|
||||
getPosts: (params: PageParams) => {
|
||||
const query = new URLSearchParams({
|
||||
page: params.page.toString(),
|
||||
limit: params.limit.toString()
|
||||
});
|
||||
return request<Post[]>(`/posts?${query}`);
|
||||
},
|
||||
|
||||
getPostById: (id: string) => request<Post>(`/posts/${id}`),
|
||||
|
||||
createPost: (data: Partial<Post>) => request<Post>('/posts', {
|
||||
method: 'POST',
|
||||
body: JSON.stringify(data),
|
||||
}),
|
||||
|
||||
// Upload (特殊处理 Multipart)
|
||||
uploadImage: async (file: File) => {
|
||||
const token = localStorage.getItem('auth_token');
|
||||
const formData = new FormData();
|
||||
formData.append('file', file);
|
||||
|
||||
const response = await fetch(`${BASE_URL}/upload`, {
|
||||
method: 'POST',
|
||||
headers: { 'Authorization': `Bearer ${token}` }, // 不设置 Content-Type，让浏览器自动设置 boundary
|
||||
body: formData
|
||||
});
|
||||
|
||||
if (!response.ok) throw new Error('Upload failed');
|
||||
return response.json(); // 返回 { url: "..." }
|
||||
}
|
||||
};
|
||||
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 功能模块集成策略
|
||||
|
||||
### 3.1 首页文章列表 (Infinite Scroll / Pagination)
|
||||
|
||||
**极简主义的数据加载不应有“旋转的菊花”**。
|
||||
|
||||
* **加载状态 (Loading)**: 使用**骨架屏 (Skeleton)**。
|
||||
* 在数据回来之前，渲染 3 个灰色的方块 (`bg-neutral-100`)，位置与图片和标题完全重合。这能保持页面的“稳定感”，不会因为数据加载而发生布局跳动。
|
||||
|
||||
|
||||
* **API**: `GET /api/posts?page=1&limit=5`
|
||||
* **错误状态**: 如果 API 挂了，不要弹窗。在列表顶部显示一行极小的灰色文字：*"Could not retrieve latest transmission."*
|
||||
|
||||
### 3.2 文章详情与 Markdown 渲染
|
||||
|
||||
技术博客的核心是代码阅读体验。
|
||||
|
||||
* **API**: `GET /api/posts/{id}`
|
||||
* **Markdown 解析**: 推荐使用 `react-markdown`。
|
||||
* **代码高亮**: 使用 `rehype-highlight` 或 `prismjs`。
|
||||
* **样式定制**:
|
||||
* 为了符合极简风格，必须重写 `<pre>` 和 `<code>` 的样式。
|
||||
* **代码块背景**: `#fafafa` (极淡灰)。
|
||||
* **字体**: `JetBrains Mono`。
|
||||
* **边框**: 无边框，直角。
|
||||
|
||||
|
||||
|
||||
```typescript
|
||||
// Markdown 组件配置示例
|
||||
<ReactMarkdown
|
||||
rehypePlugins={[rehypeHighlight]}
|
||||
components={{
|
||||
// 覆盖默认图片样式，确保圆角为 0
|
||||
img: ({node, ...props}) => (
|
||||
<img {...props} className="w-full h-auto aspect-video object-cover my-8 border border-neutral-100" />
|
||||
),
|
||||
// 覆盖代码块
|
||||
code: ({node, inline, className, children, ...props}) => {
|
||||
return !inline ? (
|
||||
<pre className="bg-neutral-50 p-6 overflow-x-auto text-sm my-8">
|
||||
<code className={className} {...props}>{children}</code>
|
||||
</pre>
|
||||
) : (
|
||||
<code className="bg-neutral-100 px-1 py-0.5 text-sm font-mono text-red-600" {...props}>{children}</code>
|
||||
)
|
||||
}
|
||||
}}
|
||||
>
|
||||
{post.content}
|
||||
</ReactMarkdown>
|
||||
|
||||
```
|
||||
|
||||
### 3.3 管理员发布文章 (Writer Mode)
|
||||
|
||||
这是一个关键的交互点。我们需要一个**所见即所得 (WYSIWYG) 但又极简**的编辑器。
|
||||
|
||||
* **布局**: 左侧 Markdown 输入框 (Monospace)，右侧实时预览。
|
||||
* **图片上传集成**:
|
||||
1. 用户将截图直接拖入 Markdown 输入框。
|
||||
2. 触发 `onDrop` 事件 -> 调用 `api.uploadImage(file)`。
|
||||
3. 上传中：光标处显示 `![Uploading...]` (灰色)。
|
||||
4. 上传完成：替换为 ``。
|
||||
|
||||
|
||||
* **API 调用**:
|
||||
* 点击 "Publish" -> `POST /api/posts` -> 成功后跳转至详情页。
|
||||
* 验证错误 (400 Empty Title) -> 标题输入框下方的黑线变红 (`border-red-600`)，不显示文字提示，或者仅显示极小的 "Required"。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 4. 状态反馈映射表 (UI Feedback)
|
||||
|
||||
在极简设计中，我们利用**微交互**来反馈后端状态，而非模态框。
|
||||
|
||||
| 后端状态 (Status) | 场景 (Context) | 前端极简反馈 (Visual Feedback) |
|
||||
| --- | --- | --- |
|
||||
| **200 OK** | 登录成功 | 按钮文字从 "Enter" 变为 "Welcome"，淡出并跳转。 |
|
||||
| **200 OK** | 文章发布成功 | 页面右上角显示 "Saved." (纯文本，3秒消失)。 |
|
||||
| **401 Unauthorized** | Token 过期 | 自动静默跳转至 `/login`，无提示。 |
|
||||
| **400 Bad Request** | 密码太短 | 密码框下边框变红，同时有一个极轻微的左右震动动画 (Shake)。 |
|
||||
| **404 Not Found** | 文章 ID 错误 | 页面中心显示巨大的 "404"，配文 "Signal Lost"。 |
|
||||
| **500 Server Error** | 服务器崩溃 | 页面顶部出现 2px 高的红色静止线条。 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 开发路线图 (Roadmap)
|
||||
|
||||
建议按以下顺序开发，以最快速度跑通 MVP：
|
||||
|
||||
1. **Step 1: API Client**: 搭建 `api.ts`，跑通 `fetch` 封装。
|
||||
2. **Step 2: Read-Only**: 完成首页列表 (`GET /posts`) 和详情页 (`GET /posts/:id`)。此时数据可以是 Mock 的。
|
||||
3. **Step 3: Markdown**: 调优 `react-markdown` 样式，确保代码块和图片符合极简规范。
|
||||
4. **Step 4: Auth**: 完成极简登录页 (`POST /login`)。
|
||||
5. **Step 5: Editor**: 完成发布功能和图片上传 (`POST /upload` + Drag & Drop)。
|
||||
|
||||
准备好开始编码了吗？建议从配置 `api.ts` 和 `tailwind.config.js` 开始。
|
||||
Reference in New Issue
Block a user