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

作者：袖梨 2026-05-29

在中后台系统开发中，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 核心设计原则

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

三、分层详解（核心）

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

3.1.1 定位

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

3.1.2 核心能力

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

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

3.2.1 定位

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

3.2.2 核心职责

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

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

3.3.1 定位

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

3.3.2 双调用模式

useXxx：组件内部专用，自动管理状态
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