前言
API 层是前端与后端之间唯一的通信通道。它的设计质量直接决定了"一个后端接口变更需要改多少前端代码"、"一个 401 错误会不会触发 10 个同时刷新的请求"、"文件下载时文件名乱码该在哪一层解决"。
这些问题不是业务逻辑的问题,是 API 层工程化的问题。
企业智能知识库前端的 API 层以 单一 Axios 实例为核心,向上通过 30 组 Service 函数 暴露类型安全的接口调用,向下通过 Vite 开发代理 转发到后端微服务集群。请求链路中集成了 自动 Token 注入、CSRF 防护、请求追踪、响应脱壳、并发安全的 Token 刷新队列、文件上传/下载处理、SSE 流式解析 七个横切关注点。
1. 从一个文档列表请求看 API 调用全链路
以用户在文档列表页点击"已发布"Tab为例,完整追踪一次 API 调用经过的所有层次:
DocumentsPage 组件 Tab 切换 → handleTabChange('published')
│
▼
useDocumentStore.setFilter({ status: 'published' })
→ filter 变化触发 React useEffect
│
▼
useDocumentStore.fetchDocuments({ status: 'published' })
│
├── 1. Store 防并发:if (isLoading) return ← 阻止重复请求
│
▼
documentService.getDocuments({ keyword, categoryId, teamId, status: 'published', page: 1, pageSize: 12 })
│
├── 2. 参数转换层:{ page:1, pageSize:12 } → { current:1, size:12 }
│ filter.categoryId? → params.categoryId
│ filter.status !== undefined? → params.status
│
▼
http.get('/document/documents/page', { params: { current:1, size:12, status:2 } })
│
├── 3. Axios 请求拦截器:
│ ├── skipAuth? → 否
│ ├── config.headers.Authorization = 'Bearer eyJ...' ← 从 tokenStorage 取
│ ├── config.headers['X-CSRF-TOKEN'] = '...' ← 从 meta 标签取
│ ├── config.headers['X-Request-ID'] = '1719123456-abc123' ← 自动生成
│ └── config.headers['X-Requested-With'] = 'XMLHttpRequest'
│
▼
GET /api/document/documents/page?current=1&size=12&status=2
│
├── 4. Vite 开发代理(仅 dev 模式):
│ ├── 匹配 '/api' → target: 'http://localhost:8080'
│ ├── 重写 Origin → 'http://localhost:8080'
│ ├── proxyReq 事件日志
│ └── proxyRes 注入 CORS 头
│
▼
http://localhost:8080/document/documents/page?current=1&size=12&status=2
│
├── 5. Spring Gateway(生产环境)→ 路由到 kb-document 服务
│ └── DocumentController.page(PageDTO, DocumentFilter)
│
▼
HTTP 200 { code: 200, message: "操作成功", data: { records: [...], total: 150,
current: 1, size: 12 }, timestamp: "..." }
│
├── 6. Axios 响应拦截器:
│ ├── 检测到 data.code === 200
│ └── return data.data ← 脱壳:只返回 { records, total, current, size }
│
├── 7. Service 层 .then() 二次转换:
│ └── { records, total, current, size }
│ → { list: records, total, page: current, pageSize: size }
│
▼
useDocumentStore.set({
documents: response.list, ← 150 条
total: response.total,
currentPage: response.page,
isLoading: false
})
│
├── 8. React 自动 re-render
│ └── DocumentsPage 重新渲染,列表刷新
│
└── DocumentsPage 总数展示:
{ total } 条文档 ← 显示 "150 条文档"一次文档列表请求经过了 8 个处理层:防并发锁 → 参数映射 → Token 注入 → 开发代理 → 网关路由 → 响应脱壳 → 格式转换 → Store 更新。每一层只做一件事,但合在一起构成了完整的请求生命周期。
2. API 层架构全景图
2.1 分层架构
┌─────────────────────────────────────────────────────────────────────┐
│ React 组件 / Zustand Store 层 │
│ │
│ useAuthStore.login() useDocumentStore.fetchDocuments() │
│ useAIStore.sendMessage() useNotificationStore.fetchNotifications()│
└────────────────────────────────┬────────────────────────────────────┘
│ 调用
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Service 模块层 (26 组服务函数) │
│ │
│ authService documentService aiService notificationService │
│ userService teamService reviewService categoryService │
│ searchService statisticsService versionService graphService │
│ fileService fileManagementService roleService settingsService │
│ foundationService favoriteService kagService accessService │
│ commentService webSocketService dashboardService │
│ │
│ 职责:类型安全的函数签名 + 参数转换 + 响应格式转换 │
└────────────────────────────────┬────────────────────────────────────┘
│ 调用 http.get/post/put/delete
▼
┌─────────────────────────────────────────────────────────────────────┐
│ HTTP 客户端层 (request.ts) │
│ │
│ Axios Instance (baseURL='/api', timeout=120s, withCredentials=false) │
│ │
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ 请求拦截器 │ 响应拦截器 │ │
│ │ • Token 注入 │ • 响应脱壳 (code===200 → data.data) │ │
│ │ • CSRF Token │ • 401 → Token 刷新队列 │ │
│ │ • X-Request-ID │ • 403/404/500 → 友好提示 + reject │ │
│ │ • 调试日志(DEV) │ • _download → 返回完整响应 │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │
│ http 工具对象: get / post / put / delete / patch / │
│ postForm / download / downloadPost │
└────────────────────────────────┬────────────────────────────────────┘
│ /api/* (开发环境)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ Vite 开发代理 (vite.config.ts) │
│ │
│ /api → http://localhost:8080 (CORS 头注入, Origin 重写, 日志) │
│ /ws → http://localhost:8080 (WebSocket 升级, Token 转发) │
└────────────────────────────────┬────────────────────────────────────┘
│ /document/* /auth/* /ai/* ...
▼
┌─────────────────────────────────────────────────────────────────────┐
│ 后端微服务集群 (Spring Cloud + Gateway) │
│ │
│ kb-gateway(:8080) → kb-document kb-user-auth kb-ai kb-search │
│ kb-graph kb-file kb-foundation │
│ kb-statistics kb-notification │
└─────────────────────────────────────────────────────────────────────┘2.2 后端子系统的前端路由映射
| 后端微服务 | 前端 API 前缀 | Service 模块 | 接口数量 |
|---|---|---|---|
| kb-user-auth | /auth/* | authService, userService, teamService, roleService | ~35 |
| kb-document | /document/* | documentService, categoryService, versionService, reviewService, favoriteService | ~40 |
| kb-ai | /ai/* | aiService | ~18 |
| kb-foundation | /notifications/*, /config/*, /logs/*, /dicts/* | foundationService, notificationService, settingsService | ~35 |
| kb-search | /search/* | searchService | 5 |
| kb-statistics | /statistics/* | statisticsService, dashboardService | 9 |
| kb-graph | /graph/*, /kag/* | graphService, kagService | 11 |
| kb-file | /file/*, /files/* | fileService, fileManagementService | ~20 |
3. Axios 核心客户端:拦截器链与响应脱壳
3.1 Axios 实例配置
// src/services/request.ts
const request: AxiosInstance = axios.create({
baseURL: '/api', // Vite 代理转发路径
timeout: 120000, // 2 分钟 — 支持文档导入等长耗时操作
headers: {
'Content-Type': 'application/json;charset=UTF-8',
'Accept': 'application/json;charset=UTF-8',
},
withCredentials: false, // 手动管理 Authorization Header
});| 配置项 | 值 | 设计理由 |
|---|---|---|
baseURL | /api | 便于 Vite 代理按前缀匹配,生产环境由 Nginx 重写 |
timeout | 120000 | 文档导入、文件转换等操作可能耗时 30s+,保守设为 2 分钟 |
withCredentials | false | 不依赖 Cookie 自动携带,通过 Authorization Header 主动注入,避免 CORS 复杂化 |
Content-Type | application/json | 默认 JSON,文件上传时由 postForm 方法动态切换为 multipart/form-data |
3.2 自定义请求配置扩展
// src/services/request.ts
interface CustomAxiosRequestConfig extends AxiosRequestConfig {
skipAuth?: boolean; // 跳过 Token 注入(登录、刷新、公开分享接口)
skipErrorToast?: boolean; // 静默错误(后台轮询、非关键接口)
showLoading?: boolean; // 显示全局 Loading(批量操作)
_download?: boolean; // 返回完整 AxiosResponse(文件下载需读响应头)
}skipAuth是最常用的扩展字段。Token 刷新接口本身不能携带旧 Token(会导致无限循环),公开分享查询无需登录。使用as any类型断言的原因是 Axios 的类型系统不承认自定义字段,但这优于创建一个全局类型包装器。
3.3 请求拦截器
请求拦截器执行顺序:
│
├── 1. skipAuth === false?
│ └── Y: tokenStorage.getAuthorizationHeader() → Authorization: Bearer xxx
│ └── 为空?→ 开发环境 console.warn(生产静默)
│
├── 2. meta[name="csrf-token"] 存在?
│ └── Y: X-CSRF-TOKEN: {content}
│
├── 3. X-Request-ID: {Date.now()}-{Math.random().toString(36).slice(2, 9)}
│ └── 例: 1719123456-a1b2c3d
│
└── 4. X-Requested-With: XMLHttpRequestX-Request-ID 由以下函数生成:
function generateRequestId(): string {
return `${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
}这个 ID 会被 Spring Gateway 记录到日志中,在排查跨服务调用问题时可以通过同一个 ID 串联起前端请求 → Gateway → Document Service → AI Service 的完整链路。
3.4 响应拦截器 —— 脱壳逻辑
后端所有接口统一返回 { code: number, message: string, data: T, timestamp: number }。响应拦截器的核心职责就是"脱壳"——让上层 Service 和 Store 直接拿到 data 字段:
// src/services/request.ts
request.interceptors.response.use(
(response: AxiosResponse) => {
const { data, config } = response;
const customConfig = config as CustomAxiosRequestConfig;
// 下载请求:返回完整响应,用于读取 Content-Disposition 等头
if (customConfig._download) {
return response;
}
// 标准响应:脱壳
if (data && typeof data === 'object' && 'code' in data) {
if (data.code === 200) {
return data.data; // ← 脱壳点:只返回 data 字段
}
if (data.code === 401) {
if (!customConfig.skipAuth) {
handleUnauthorized(); // 清除 Token + 跳转登录
}
return Promise.reject(new Error(data.message));
}
// 其他业务错误:toast 提示 + reject
if (!customConfig.skipErrorToast) {
message.error(data.message || '请求失败');
}
return Promise.reject(new Error(data.message));
}
// 非标准格式,透传
return data;
},
(error: AxiosError) => {
// HTTP 状态码错误处理(见第 4 章)
}
);脱壳效果对比:
脱壳前(后端返回):
{
code: 200,
message: "操作成功",
data: { id: 12345, title: "Spring Boot 实战", ... },
timestamp: 1719123456789
}
脱壳后(Service 层拿到):
{ id: 12345, title: "Spring Boot 实战", ... }3.5 HTTP 工具方法
// src/services/request.ts
export const http = {
get: <T>(url, config?) => request.get(url, config),
post: <T>(url, data?, config?) => request.post(url, data, config),
put: <T>(url, data?, config?) => request.put(url, data, config),
delete: <T>(url, config?) => request.delete(url, config),
patch: <T>(url, data?, config?) => request.patch(url, data, config),
postForm: <T>(url, data: FormData) =>
request.post(url, data, { headers: { 'Content-Type': undefined } }),
download: (url, filename?) => { /* GET blob + a 标签下载 */ },
downloadPost: (url, data, filename?) => { /* POST blob + a 标签下载 */ },
};| 方法 | HTTP Method | responseType | 特殊处理 |
|---|---|---|---|
get | GET | json | - |
post | POST | json | - |
put | PUT | json | - |
delete | DELETE | json | - |
patch | PATCH | json | - |
postForm | POST | json | Content-Type 去掉,让浏览器自动设置 multipart/form-data + boundary |
download | GET | blob | _download: true → 返回完整响应 → 解析 Content-Disposition |
downloadPost | POST | blob | _download: true → 同上(用于批量导出) |
4. Token 刷新队列:并发安全的无感刷新
4.1 问题场景
当 Token 过期时,前端的多个并发请求会同时收到 401。如果每个请求都独立尝试刷新 Token,会触发 N 次 /auth/auth/refresh 请求,只有第一个成功,其余全部失败 —— 这就是"刷新风暴"。
4.2 队列方案
// src/services/request.ts
let isRefreshing = false; // 刷新锁
let requests: Array<(token: string) => void> = []; // 等待队列
function handleTokenExpired(error: AxiosError): Promise<any> {
// 情况 1:正在刷新 → 入队等待
if (isRefreshing) {
return new Promise((resolve) => {
requests.push((token: string) => {
error.config!.headers!.Authorization = `Bearer ${token}`;
resolve(request(error.config!)); // 用新 Token 重新发起
});
});
}
// 情况 2:开始刷新
isRefreshing = true;
const refreshToken = tokenStorage.getRefreshToken();
if (!refreshToken) {
isRefreshing = false;
handleUnauthorized();
return Promise.reject(new Error('未授权'));
}
return request
.post<LoginResponse>('/auth/auth/refresh', null, {
params: { refreshToken },
skipAuth: true, // 关键:刷新请求不注入旧 Token
})
.then((newTokenInfo) => {
tokenStorage.saveToken(newTokenInfo);
// 关键:重放等待队列中的所有请求
requests.forEach(callback => callback(newTokenInfo.accessToken));
requests = [];
// 重试当前请求
error.config!.headers!.Authorization = `Bearer ${newTokenInfo.accessToken}`;
return request(error.config!);
})
.catch(() => {
tokenStorage.clearToken();
handleUnauthorized();
})
.finally(() => {
isRefreshing = false;
});
}队列机制时序图:
时间轴 →
请求 A ─── 发送 ─── 收到 401 ─── 开始刷新 ─────────── 刷新成功 ─── 重试请求 A
请求 B ─── 发送 ─── 收到 401 ─── 入队等待 ─────────── 获取新Token ─── 重试请求 B
请求 C ─── 发送 ─── 收到 401 ─── 入队等待 ─────────── 获取新Token ─── 重试请求 C
↑
POST /auth/auth/refresh (只调用一次)关键设计:refreshToken请求设置了skipAuth: true。如果不用skipAuth,请求拦截器会注入过期的accessToken→ 后端返回 401 → 又进入handleTokenExpired()→isRefreshing = true→ 死循环。
4.3 未授权处理
function handleUnauthorized(): void {
tokenStorage.clearToken(); // 清除 Cookie + localStorage 双存储
localStorage.removeItem('user'); // 清除旧版用户信息
localStorage.removeItem('auth-storage'); // 清除 Zustand persist
message.warning('登录已过期,请重新登录');
setTimeout(() => {
window.location.href = '/login'; // 延迟跳转,避免阻塞 UI
}, 1000);
}4.4 HTTP 状态码映射
function handleRequestError(error: AxiosError, customConfig): Promise<any> {
let errorMessage = '请求失败';
const { status } = error.response;
switch (status) {
case 400: errorMessage = '请求参数错误'; break;
case 403:
errorMessage = '权限不足,无法访问'; // 不改 Token,不跳转登录
handleForbidden(); // 只弹提示
break;
case 404: errorMessage = '请求资源不存在'; break;
case 500: errorMessage = '服务器错误,请稍后重试'; break;
case 502: errorMessage = '网关错误,请稍后重试'; break;
case 503: errorMessage = '服务暂时不可用,请稍后重试'; break;
}
if (!customConfig?.skipErrorToast) {
message.error(errorMessage);
}
return Promise.reject(new Error(errorMessage));
}403 与 401 的区别:403 表示"已登录但权限不足",不清除 Token,不跳转登录页。用户只是没有该操作的权限,不是登录过期。
5. 文件上传与下载:FormData、Blob 与 Content-Disposition
5.1 文件上传
// src/services/request.ts
postForm: <T = any>(url: string, data: FormData): Promise<T> => {
return request.post(url, data, {
headers: {
'Content-Type': undefined, // 让浏览器自动设置包含 boundary 的 Content-Type
},
});
}使用示例 —— 文档文件上传:
// src/services/document.service.ts
uploadDocumentFile: (file: File) => {
const formData = new FormData();
formData.append('file', file);
return http.postForm('/document/documents/upload', formData);
}带进度回调的文件上传:
// src/services/file.service.ts
upload: (file: File, options?: { onProgress?: (p: UploadProgress) => void }) => {
const formData = new FormData();
formData.append('file', file);
return http.postForm('/file/files/upload', formData, {
onUploadProgress: (progressEvent) => {
if (options?.onProgress) {
options.onProgress({
loaded: progressEvent.loaded,
total: progressEvent.total!,
percent: Math.round((progressEvent.loaded * 100) / progressEvent.total!),
});
}
},
} as any);
}5.2 文件下载
GET 下载 —— http.download():
// src/services/request.ts
download: (url: string, filename?: string): Promise<void> => {
return request.get(url, {
responseType: 'blob',
_download: true, // 不脱壳,返回完整 AxiosResponse
} as any).then((response: AxiosResponse) => {
// 解析文件名
let finalFilename = filename || 'download.pdf';
const contentDisposition = response.headers?.['content-disposition'];
if (contentDisposition) {
// 优先 RFC 5987 格式:filename*=UTF-8''%E6%96%87%E6%A1%A3.pdf
const rfc5987Match = contentDisposition.match(/filename\*=UTF-8''([^"';]+)/);
if (rfc5987Match) {
try {
finalFilename = decodeURIComponent(rfc5987Match[1]);
} catch { finalFilename = rfc5987Match[1]; }
} else {
// 回退标准格式:filename="文档.pdf"
const standardMatch = contentDisposition.match(/filename="([^"]+)"/);
if (standardMatch) { finalFilename = standardMatch[1]; }
}
}
// Blob → ObjectURL → 模拟点击下载
const blob = new Blob([response.data], { type: 'application/pdf' });
const link = document.createElement('a');
link.href = URL.createObjectURL(blob);
link.download = finalFilename;
document.body.appendChild(link);
link.click();
document.body.removeChild(link);
URL.revokeObjectURL(link.href);
});
}POST 下载 —— 批量导出时的错误处理:
// src/services/document.service.ts
batchExportDocuments: async (ids: string[], format: 'pdf' | 'markdown') => {
const response: any = await request.post('/document/documents/batch-export',
{ documentIds: ids, format },
{ responseType: 'blob', _download: true } as any);
// 关键:批量导出失败时后端可能返回 JSON 错误而非 ZIP
const contentType = response.headers?.['content-type'] || '';
if (contentType.includes('application/json')) {
const text = await response.data.text();
const errorData = JSON.parse(text);
throw new Error(errorData.message || '导出失败');
}
// ... 正常 ZIP 下载
}文件名的国际化处理:采用 RFC 5987 优先的策略。filename*=UTF-8''%E6%96%87%E6%A1%A3.pdf是标准 UTF-8 编码,能正确显示中文文件名;filename="???.pdf"在非拉丁语系可能产生乱码,仅作为 fallback。
6. Vite 开发代理:跨域、WebSocket 与请求日志
6.1 代理配置
// vite.config.ts
export default defineConfig({
server: {
port: 3002, // 前端开发端口
host: true, // 允许局域网访问
proxy: {
'/api': {
target: 'http://localhost:8080',
changeOrigin: true, // 修改 Origin 头,避免后端 CORS 拒绝
configure: (proxy, options) => {
// 请求转发前日志
proxy.on('proxyReq', (proxyReq, req) => {
console.log('Proxying:', req.method, req.url);
proxyReq.setHeader('Origin', 'http://localhost:8080');
proxyReq.setHeader('Referer', 'http://localhost:8080/');
});
// 响应返回时注入 CORS 头
proxy.on('proxyRes', (proxyRes, req) => {
proxyRes.headers['Access-Control-Allow-Origin'] = '*';
proxyRes.headers['Access-Control-Allow-Methods'] = 'GET,POST,PUT,DELETE,OPTIONS';
proxyRes.headers['Access-Control-Allow-Headers'] = 'Content-Type,Authorization,...';
});
proxy.on('error', (err) => {
console.error('Proxy error:', err.message);
});
},
},
'/ws': {
target: 'http://localhost:8080',
ws: true, // WebSocket 支持
changeOrigin: true,
configure: (proxy) => {
proxy.on('proxyReq', (proxyReq, req) => {
// 关键:手工转发 Authorization 头,保证 WebSocket 认证
const authHeader = req.headers['authorization'];
if (authHeader) {
proxyReq.setHeader('Authorization', authHeader);
}
});
},
},
},
},
});6.2 请求转发流程
浏览器 Vite Dev Server 后端 Gateway
────── ────────────── ─────────────
GET /api/document/documents/page ↓
─────────────────────────────→ 匹配 '/api' 代理规则
│
├── proxyReq 事件:
│ • 设置 Origin → localhost:8080
│ • 设置 Referer → localhost:8080
│
├── GET http://localhost:8080/document/... ──→
│ ←── 200 OK
│
├── proxyRes 事件:
│ • 注入 CORS 头部
│ • 日志输出
│
←───────────────────────────── 返回给浏览器生产环境:Vite 代理仅在开发环境生效。生产部署时由 Nginx 反向代理 承担同样的职责,配置在后端部署文档中描述。
7. Service 模块全景:26 组服务与后端子系统的映射
7.1 桶文件导出
// src/services/index.ts — 所有服务的统一入口
export { default as authService } from './auth.service';
export { default as documentService } from './document.service';
export { default as aiService } from './ai.service';
export { default as dashboardService } from './dashboard.service';
export { searchService } from './search.service';
export { default as versionService } from './version.service';
export { default as notificationService } from './notification.service';
export { default as reviewService } from './review.service';
export { default as statisticsService } from './statistics.service';
export { default as roleService } from './role.service';
export { default as teamService } from './team.service';
export { default as fileService } from './file.service';
export { fileManagementService } from './file-management.service';
export { default as userService } from './user.service';
export { default as categoryService } from './category.service';
export { commentService } from './comment.service';
export { settingsService } from './settings.service';
export { graphService } from './graph.service';
export { kagService } from './kag.service';
export { foundationService } from './foundation.service';
export { favoriteService } from './favorite.service';
export { accessService } from './access.service';
export { webSocketService } from './websocket.service';
export { http } from './request'; // 裸 HTTP 客户端7.2 核心 Service 详解
7.2.1 认证服务(authService)
前端 Service 后端接口 skipAuth?
────────────────────── ────────────────────────── ──────────
login(data) POST /auth/auth/login 否
logout() POST /auth/auth/logout 否
getCurrentUser() GET /auth/auth/me 否
refreshToken(refresh) POST /auth/auth/refresh 是 ← 关键
changePassword(data) PUT /auth/users/password/change 否
updateProfile(data) PUT /auth/users 否
uploadAvatar(file) POST /auth/avatar 否
register(data) POST /auth/auth/register 否
verifyEmail(token) GET /auth/auth/verify-email 否
sendResetCode(email) POST /auth/auth/password/reset/send-code 否
verifyResetCode(email,code) POST /auth/auth/password/reset/verify-code 否
resetPassword(data) POST /auth/auth/password/reset 否7.2.2 文档服务(documentService)—— 最大的 Service
// src/services/document.service.ts — 核心方法签名
export const documentService = {
// ====== CRUD ======
getDocuments(filter: DocumentFilter): Promise<DocumentListResponse>
getDocument(id: string): Promise<Document>
getDocumentNeighbors(id: string): Promise<{ prevId, prevTitle, nextId, nextTitle }>
createDocument(data): Promise<{ id: string }>
updateDocument(id: string, data: Partial<Document>): Promise<Document>
deleteDocument(id: string): Promise<void>
// ====== 自动保存 ======
autoSaveDocument(data: { id?, title?, content?, summary?, ... }): Promise<{ id: string }>
updateSummary(id: string, summary: string): Promise<boolean>
// ====== 状态流转 ======
publishDocument(id: string): Promise<Document>
archiveDocument(id: string): Promise<Document>
// ====== 互动 ======
likeDocument(id: string): Promise<void>
unlikeDocument(id: string): Promise<void>
favoriteDocument(id: string): Promise<void>
viewDocument(id: string): Promise<Document>
// ====== 文件上传 ======
uploadDocumentFile(file: File): Promise<string>
uploadAndParseDocument(file: File): Promise<ParsedDocument>
// ====== 导入导出 ======
exportDocumentToPdf(id: string): Promise<string> // 返回下载链接
downloadDocumentPdf(id: string): Promise<void> // 直接下载
batchExportDocuments(ids: string[], format): Promise<void>
// ====== 分享 ======
createShare(data): Promise<ShareVO>
getShareInfo(shareId: string): Promise<ShareVO>
getDocumentShares(docId: string): Promise<ShareVO[]>
deleteShare(shareId: string): Promise<void>
// ====== 公开分享 (skipAuth) ======
getPublicShareInfo(shareId: string): Promise<ShareVO>
verifyPublicShare(shareId: string, password?): Promise<boolean>
accessPublicShare(shareId: string, password?): Promise<Document>
// ====== 自动保存历史 ======
getAutoSaveHistory(docId: string, page, pageSize): Promise<PageResponse>
getAutoSaveSnapshot(docId: string, snapId: string): Promise<Snapshot>
dismissAutoSaveDrafts(): Promise<boolean>
};documentService 的updateDocument()接口设计值得注意:id不在 URL path 中,而是放在请求体中{ ...data, id }。这与 RESTful 惯例(PUT/document/documents/:id)有差异,调用方需要注意。
7.2.3 AI 服务(aiService)—— 双传输模式
// src/services/ai.service.ts
export const aiService = {
// ====== 普通 HTTP (Axios) ======
getModels(): Promise<AIModelOption[]>
ask(data: AIRequest): Promise<ChatResponse> // 非流式
getConversations(): Promise<AIConversation[]>
getConversation(id: string): Promise<AIConversation>
createConversation(title: string): Promise<AIConversation>
deleteConversation(id: string): Promise<void>
clearConversation(id: string): Promise<void>
getSuggestions(docId?: string): Promise<string[]>
submitFeedback(data): Promise<void>
getQuickQuestions(): Promise<AIQuickQuestion[]>
// ====== 流式 SSE (原生 fetch) ======
askStream(data, onMessage, onDone?, onError?): Promise<void>
generateWritingStream(data, onChunk, onDone?, onError?): Promise<void>
generateDocSummaryStream(params, onChunk, onDone?, onError?): Promise<void>
};SSE 流的实现(已在《前端状态管理》文档第 8 章详述),核心差异点:
| 维度 | Axios (普通接口) | fetch (SSE 流) |
|---|---|---|
| Token 注入 | 请求拦截器自动 | 手工 headers.Authorization |
| 响应处理 | 响应拦截器脱壳 data.data | 手动解析 ReadableStream + SSE 事件 |
| 适用场景 | 查询、命令 | AI 问答、写作流、摘要流 |
| 选择原因 | 复用拦截器链 | Axios 响应拦截器无法处理未完成的流 |
7.2.4 Foundation Service —— 组合服务
// src/services/foundation.service.ts
// 将 5 个子服务整合到一个命名空间中
export const foundationService = {
notification: {
list(params?), detail(id), send(data), markAsRead(id),
markAllAsRead(userId), delete(id), unreadCount(userId),
},
config: {
list(params?), get(key), create(data), update(key, data),
delete(key), getByCategory(category), getPublic(),
},
log: {
list(params?), detail(id), statistics(params?), deleteBeforeDate(date),
},
notificationTemplate: {
list(params?), listActive(), detail(id), create(data),
update(id, data), delete(id), test(id, target),
},
dict: {
list(params?), getByCode(code), create(data), update(code, data),
delete(code), getData(code), addData(code, data),
updateData(code, data), deleteData(code, id),
},
};foundationService.config.getPublic()方法处理了后端两种可能的返回格式(数组[{key, value}]或 Map{key: value}),通过Array.isArray()运行时类型检查兼容两种格式 —— 这是灰度发布中常见的前端兼容手段。
7.2.5 审核服务(reviewService)—— 状态枚举映射
reviewService 封装了后端 BackendReviewRecord(数字状态码)到前端 ReviewTask(字符串状态)的映射:
// src/services/review.service.ts
interface BackendReviewRecord {
reviewResult: number | null; // null=待审核, 1=通过, 2=驳回
}
// 映射函数
function mapToReviewTask(record: BackendReviewRecord): ReviewTask {
let status: ReviewTask['status'] = 'pending';
if (record.reviewResult === 1) status = 'approved';
else if (record.reviewResult === 2) status = 'rejected';
return { ...record, status, documentAuthor: constructUser(record) };
}这种"API 层做数据转换"的模式确保了 ReviewTask 类型在所有上层代码中始终是语义化的字符串状态,而不需要每个组件都写 reviewResult === 1 ? '已通过' : '已驳回'。7.2.6 其他 Service 接口速览
搜索服务:
searchService.search(params: SearchParams): Promise<SearchResponse>
searchService.suggestions(keyword: string): Promise<string[]>
searchService.hotSearch(): Promise<string[]>
searchService.history(): Promise<string[]>
searchService.clearHistory(): Promise<void>统计服务:
statisticsService.getSystemStatistics(params?)
statisticsService.getDashboardStats()
statisticsService.getDocumentTrend(params) // date range → { startDate, endDate }
statisticsService.getCategoryDistribution()
statisticsService.getPopularDocuments(params?)
statisticsService.getActiveUsers(params?)团队服务:
teamService.getTeams(params?) // POST /auth/teams/page(分页用 POST)
teamService.getTeamTree(rootOnly?) // GET /auth/teams/tree (skipAuth: true)
teamService.addMembers(teamId, userIds)
teamService.removeMembers(teamId, userIds)知识图谱服务:
graphService.getGraphData()
graphService.searchNodes(keyword)
graphService.getNodeNeighbors(nodeId, depth=1)
graphService.findPath(startId, endId)
graphService.rebuildGraph() // POST /document/documents/graph/rebuildKAG 服务:
kagService.searchGraph(query: string)
kagService.kagChat(content: string, conversationId?: string)7.3 前端 API 端点完整清单
| 后端路径前缀 | Service 模块 | 接口数量 |
|---|---|---|
/auth/auth/* | authService | 8 |
/auth/users/* | userService, authService | 18 |
/auth/teams/* | teamService | 8 |
/auth/roles/* | roleService | 8 |
/auth/permissions | roleService | 1 |
/document/documents/* | documentService, versionService, graphService | ~28 |
/document/categories/* | categoryService | 12 |
/document/comments/* | commentService | 6 |
/document/favorite/* | favoriteService | 6 |
/document/review/* | reviewService | 8 |
/document/access/* | accessService | 4 |
/document/share/* | documentService | 3 (公开, skipAuth) |
/document/files/* | fileService | 2 |
/document/file-management/* | fileManagementService | 15 |
/file/files/* | fileService | 4 |
/files/* | fileService | 8 |
/notifications/* | notificationService, foundationService | 10 |
/config/* | foundationService, settingsService | 12 |
/logs/* | foundationService | 4 |
/dicts/* | foundationService | 10 |
/search/* | searchService | 5 |
/statistics/* | statisticsService, dashboardService | 9 |
/graph/* | graphService | 5 |
/kag/* | kagService | 2 |
/ai/* | aiService | ~18 |
/ws/notification | webSocketService | 1 (STOMP) |
总计:~220 个 API 端点,分布在 26 个 Service 模块 中,对应 9 个后端微服务。
8. 数据转换层:分页格式、状态枚举与链接解析
8.1 分页参数转换
后端 MyBatis-Plus 使用 IPage<T> 格式:{ records, total, current, size }。
前端约定使用:{ list, total, page, pageSize }。
转换发生在 Service 层:
// src/services/document.service.ts
getDocuments: (filter: DocumentFilter) => {
const params = {
current: filter.page || 1, // page → current
size: filter.pageSize || 10, // pageSize → size
...filter
};
return http.get<any>('/document/documents/page', { params }).then((data) => ({
list: data.records || [], // records → list
total: data.total || 0,
page: data.current || 1, // current → page
pageSize: data.size || 10, // size → pageSize
}));
}同样的转换模式应用于:
userService.getUsers()——page→current, pageSize→sizedocumentService.getAutoSaveHistory()—— 同上notificationService.getNotifications()—— 同上
8.2 通知链接解析
// src/utils/notification-link.ts
export const buildReviewPageLink = (documentId) => `/review/documents/${documentId}`;
export const extractDocumentIdFromLink = (link) => {
const matched = link?.match(/\/documents\/([^/?#]+)/);
return matched?.[1];
};
export const resolveNotificationTarget = (notification) => {
// 审核通知 → 审核页(新标签页)
if (isReviewPageLink(notification.link)) {
return { url: notification.link, openInNewTab: true };
}
// 评论通知 → 文档页(当前标签页)
if (notification.documentId) {
return { url: `/documents/${notification.documentId}`, openInNewTab: false };
}
return { url: notification.link, openInNewTab: false };
};8.3 状态枚举同步
前端维护了与后端同步的常量映射表(src/constants/index.ts):
// 文档状态
DOCUMENT_STATUS = { DRAFT: 'draft', PENDING_REVIEW: 'pending_review', PUBLISHED: 'published', ARCHIVED: 'archived' }
DOCUMENT_STATUS_TEXT = { draft: '草稿', pending_review: '待审核', published: '已发布', archived: '已归档' }
DOCUMENT_STATUS_COLORS = { draft: 'default', pending_review: 'processing', published: 'success', archived: 'warning' }
// 审核状态
REVIEW_STATUS = { PENDING: 'pending', APPROVED: 'approved', REJECTED: 'rejected' }
REVIEW_STATUS_TEXT = { pending: '待审核', approved: '已通过', rejected: '已拒绝' }
REVIEW_STATUS_COLORS = { pending: 'processing', approved: 'success', rejected: 'error' }
// 通知类型
NOTIFICATION_TYPES = { SYSTEM: 'system', COMMENT: 'comment', MENTION: 'mention', REVIEW: 'review', LIKE: 'like' }9. 权限控制集成:权限码常量与路由守卫
9.1 权限码常量
// src/utils/permission.ts
export const PERMISSIONS = {
documentList: 'document:list', // 文档列表查看
documentCreate: 'document:create', // 文档创建
documentEdit: 'document:edit', // 文档编辑
documentDelete: 'document:delete', // 文档删除
documentReview: 'document:review', // 文档审核
documentCategory:'document:category', // 分类管理
systemUser: 'system:user', // 用户管理
systemRole: 'system:role', // 角色管理
systemPermission:'system:permission', // 权限管理
systemTeam: 'system:team', // 团队管理
systemStatistics:'system:statistics', // 统计查看
systemSettings: 'system:settings', // 系统设置
} as const;9.2 权限判断函数
export function isSuperAdmin(user?: User | null): boolean {
return getUserRoles(user).some(role =>
new Set(['ROLE_SUPER_ADMIN', 'SUPER_ADMIN']).has(role)
);
}
export function hasPermission(user: User | null | undefined, permission?: string): boolean {
if (!permission) return true; // 无权限要求 → 放行
if (isSuperAdmin(user)) return true; // 超级管理员 → 放行
return getUserPermissions(user).includes(permission);
}
export function hasAnyPermission(user, permissions: string[]): boolean {
if (!permissions.length || isSuperAdmin(user)) return true;
return permissions.some(p => new Set(getUserPermissions(user)).has(p));
}
export function hasAllPermissions(user, permissions: string[]): boolean {
if (!permissions.length || isSuperAdmin(user)) return true;
return permissions.every(p => new Set(getUserPermissions(user)).has(p));
}9.3 在路由守卫中使用
前端通过 User.permissions 字段(字符串数组)携带权限信息,在路由配置中为每个路由声明 requiresAuth 和对应的 permission。MainLayout 和路由守卫组件在渲染时调用 hasPermission(user, permission) 做可见性控制。
超级管理员的特权实现:isSuperAdmin(user)在所有hasPermission/hasAnyPermission/hasAllPermissions的开头被检查,返回true意味着超级管理员拥有所有权限,无需在数据库中为每个管理员用户显式授予几百个权限项。
10. 总结
| # | 亮点 | 说明 |
|---|---|---|
| 1 | 单一 Axios 实例 | 全局一个 request 实例,所有 Service 通过 http 工具对象调用,避免重复配置 |
| 2 | Token 刷新队列 | isRefreshing + requests[] 队列模式,将并发 401 请求的 N 次刷新收敛为 1 次 |
| 3 | 响应脱壳 | 响应拦截器 data.code === 200 → return data.data,上层代码直接拿到业务对象 |
| 4 | skipAuth 精准控制 | CustomAxiosRequestConfig.skipAuth 让公开接口、Token 刷新接口不注入 Token,逻辑清晰 |
| 5 | 文件下载双格式兼容 | Content-Disposition 解析优先 RFC 5987,回退标准格式,中文文件名不乱码 |
| 6 | Service 层数据转换 | 分页格式、审核状态、通知链接的转换全部在 Service 层完成,上层组件不含转换逻辑 |
| 7 | Permission 函数式 API | hasPermission(user, perm) / hasAnyPermission / hasAllPermissions 语义明确,超级管理员自动全开放 |
| 8 | Vite 代理请求日志 | proxyReq / proxyRes / error 三个事件全覆盖,定位代理层面问题时日志一目了然 |
| 9 | WebSocket 代理的 Token 转发 | proxyReq 中手动读取 Authorization 头并设置到代理请求中,保证 STOMP 握手能通过认证 |
| 10 | 批量导出错误处理 | batchExportDocuments 检查 content-type 区分 JSON 错误与 ZIP 下载,避免将错误信息当作 ZIP 文件下载 |
前端 API 层以 "一个 Axios 实例 + 两层拦截器 + 26 组 Service 函数" 的简洁架构,覆盖了 9 个后端微服务的 ~220 个 API 端点。
关键设计决策 —— 响应脱壳、Token 刷新队列、文件下载 RFC 5987 优先、skipAuth 精准控制、Service 层数据转换 —— 都是针对失败场景和边界条件的工程化应对。
这套 API 层没有过度抽象(没有 BaseService 基类、没有装饰器、没有代码生成),每个 Service 文件的函数签名就是 API 文档,新成员加入团队可以直接阅读 document.service.ts 理解文档模块的所有 API 能力。