前言

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/*searchService5
kb-statistics/statistics/*statisticsService, dashboardService9
kb-graph/graph/*, /kag/*graphService, kagService11
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 重写
timeout120000文档导入、文件转换等操作可能耗时 30s+,保守设为 2 分钟
withCredentialsfalse不依赖 Cookie 自动携带,通过 Authorization Header 主动注入,避免 CORS 复杂化
Content-Typeapplication/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: XMLHttpRequest

X-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 MethodresponseType特殊处理
getGETjson-
postPOSTjson-
putPUTjson-
deleteDELETEjson-
patchPATCHjson-
postFormPOSTjsonContent-Type 去掉,让浏览器自动设置 multipart/form-data + boundary
downloadGETblob_download: true → 返回完整响应 → 解析 Content-Disposition
downloadPostPOSTblob_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/rebuild

KAG 服务:

kagService.searchGraph(query: string)
kagService.kagChat(content: string, conversationId?: string)

7.3 前端 API 端点完整清单

后端路径前缀Service 模块接口数量
/auth/auth/*authService8
/auth/users/*userService, authService18
/auth/teams/*teamService8
/auth/roles/*roleService8
/auth/permissionsroleService1
/document/documents/*documentService, versionService, graphService~28
/document/categories/*categoryService12
/document/comments/*commentService6
/document/favorite/*favoriteService6
/document/review/*reviewService8
/document/access/*accessService4
/document/share/*documentService3 (公开, skipAuth)
/document/files/*fileService2
/document/file-management/*fileManagementService15
/file/files/*fileService4
/files/*fileService8
/notifications/*notificationService, foundationService10
/config/*foundationService, settingsService12
/logs/*foundationService4
/dicts/*foundationService10
/search/*searchService5
/statistics/*statisticsService, dashboardService9
/graph/*graphService5
/kag/*kagService2
/ai/*aiService~18
/ws/notificationwebSocketService1 (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→size
  • documentService.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 工具对象调用,避免重复配置
2Token 刷新队列isRefreshing + requests[] 队列模式,将并发 401 请求的 N 次刷新收敛为 1 次
3响应脱壳响应拦截器 data.code === 200 → return data.data,上层代码直接拿到业务对象
4skipAuth 精准控制CustomAxiosRequestConfig.skipAuth 让公开接口、Token 刷新接口不注入 Token,逻辑清晰
5文件下载双格式兼容Content-Disposition 解析优先 RFC 5987,回退标准格式,中文文件名不乱码
6Service 层数据转换分页格式、审核状态、通知链接的转换全部在 Service 层完成,上层组件不含转换逻辑
7Permission 函数式 APIhasPermission(user, perm) / hasAnyPermission / hasAllPermissions 语义明确,超级管理员自动全开放
8Vite 代理请求日志proxyReq / proxyRes / error 三个事件全覆盖,定位代理层面问题时日志一目了然
9WebSocket 代理的 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 能力。

最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏