中后台系统开发指南：Admin项目API分层标准化实践方案-Vue与React通用实现

在中后台系统开发中，API层作为业务功能的核心支撑，其标准化程度直接影响开发效率和代码质量。本文将详细介绍一套适用于Vue/React的API分层开发方案。

统一范式：中后台Admin项目标准化API分层开发方案（Vue/React通用）

前言

传统开发模式存在接口调用混乱、缓存方案不统一等问题，导致开发效率低下。针对这些痛点，我们设计了一套基于Axios和TanStack Query的三层API架构。

一、技术选型底层逻辑

本方案基于三大核心技术，专为中后台业务场景优化：

1.1 TanStack Query

作为异步状态管理工具，它原生支持自动缓存、窗口聚焦刷新等后台常用功能，避免了手动编写冗余逻辑。其跨框架特性使其成为中后台项目的理想选择。

1.2 TypeScript

实现全层级类型约束，从接口参数到响应数据都进行严格校验，显著提升代码可维护性，特别适合大型Admin系统开发。

1.3 gRPC+Protobuf

通过自动生成前端TS类型和请求客户端，彻底解决了前后端类型不同步的问题，实现接口文档与代码的实时同步。

二、整体架构设计：三层分层架构

采用业务Hook层、Service服务层、自动生成层的三层结构，遵循单向依赖、职责分离等核心原则，确保架构清晰。

2.1 架构总览

UI层（Vue组件/React组件）
        ↓ 依赖
Hook层（Composables/Hooks）→ 封装TanStack Query，面向业务，提供两种调用模式
        ↓ 依赖
Service服务层 → 纯异步函数，封装接口客户端，处理参数适配
        ↓ 依赖
Generated自动生成层 → Protobuf自动生成类型+客户端，禁止手动修改

2.2 核心设计原则

1. 单向依赖：严格遵循UI→Hook→Service→Generated的调用顺序
2. 职责单一：各层专注于自身核心功能，避免逻辑耦合
3. 环境隔离：区分组件和非组件环境，提供差异化调用方案
4. 双栈统一：Vue/React保持一致的目录结构和开发规范

三、分层详解（核心）

3.1 第一层：Generated 自动生成层（底层）

3.1.1 定位

作为架构的数据基础，由Protobuf文件自动生成，开发者禁止手动修改，确保前后端类型严格同步。

3.1.2 核心能力

1. 全量接口TS类型定义
2. Service客户端工厂函数
3. 统一的命名规范体系

3.2 第二层：Service 服务层（中间层）

3.2.1 定位

作为适配层，封装自动生成的客户端，输出纯异步函数，无框架依赖，可在任意环境运行。

3.2.2 核心职责

1. 管理客户端单例
2. 统一参数格式
3. 封装基础接口
4. 异常透传处理

3.3 第三层：Hook/Composables 业务层（顶层）

3.3.1 定位

面向开发者的主要调用入口，基于TanStack Query封装，适配Vue/React双技术栈。

3.3.2 双调用模式

1. useXxx：组件内部专用，自动管理状态
2. fetchXxx：非组件环境使用，无框架依赖

四、目录结构规范（Vue/React对齐）

采用统一的目录结构，仅顶层函数目录区分Vue的composables和React的hooks：

src/api/
├── index.ts                        
├── generated/                      
│   └── admin/service/v1/
│       └── index.ts                
├── service/                        
│   ├── auth.ts / user.ts / role.ts 
│   └── index.ts                    
└── composables/hooks/              
    ├── shared.ts                  
    ├── auth.ts / user.ts          
    └── index.ts                   

五、业务场景使用指南

5.1 组件内部调用

推荐使用useXxx系列接口，自动管理加载状态和缓存：

六、新增业务模块标准化流程

新增业务模块只需4步：

1. 同步生成底层代码
2. 编写Service层
3. 编写Hook层
4. 统一导出注册

七、全局TanStack Query配置

针对后台特性优化默认配置：

1. staleTime：60s
2. retry：false
3. 关闭窗口聚焦和网络重连时的自动刷新

八、开发红线与最佳实践

8.1 开发红线

1. 禁止修改generated目录
2. Service层保持纯函数特性
3. 非组件环境禁用useXxx

九、总结

这套API分层方案有效解决了中后台开发的常见痛点，通过标准化架构和统一规范，显著提升了开发效率和代码质量，适用于各类Admin系统项目。