React应用API层架构设计与最佳实践

1. 项目概述：React数据获取的架构演进

在React应用开发中，数据获取是最基础也最容易被忽视的环节。我最近接手维护一个3年历史的React项目时，惊讶地发现代码库中竟然存在47个不同的fetch实现。每个组件都用自己的方式处理数据获取，导致维护成本呈指数级增长。这种分散的数据获取方式带来了几个严重问题：

1. 一致性缺失：每个fetch实现都有细微差异，错误处理方式各不相同
2. 维护噩梦：添加全局功能（如认证token）需要修改47个地方
3. 性能黑洞：难以实施请求去重、缓存等优化策略
4. 新人门槛：没有统一规范，每个组件都要单独学习

提示：一个中等规模应用（50个API调用点）的维护成本对比：

• 没有API层：维护成本 = 50 × N（每次修改需要改多个地方）
• 有API层：维护成本 = 1 × N（只改一个地方）

2. API层核心设计原理

2.1 中心化请求管理

API层的核心思想是将所有网络请求集中管理，通过统一入口处理。这种架构带来几个关键优势：

1. 单一职责：所有请求逻辑集中在一处，修改影响可控
2. 一致体验：全应用使用相同的错误处理、认证机制
3. 可观测性：便于添加日志、监控等横切关注点
4. 性能优化：易于实现缓存、请求合并等高级功能

javascript复制// 不好的实践：分散在各组件的fetch
function UserProfile() {
  useEffect(() => {
    fetch('/api/user').then(r => r.json()).then(setUser)
  }, [])
}

// 好的实践：通过API层统一管理
function UserProfile() {
  useEffect(() => {
    api.get('/user').then(setUser)
  }, [])
}

2.2 错误处理体系

完善的错误处理是生产级API层的标志。我们需要区分不同类型的错误：

1. 网络错误：连接失败、超时等
2. HTTP错误：4xx、5xx状态码
3. 业务错误：接口返回的业务逻辑错误
4. 数据解析错误：响应数据不符合预期格式

javascript复制// api/errors.js
export class APIError extends Error {
  constructor(message, status, data) {
    super(message)
    this.status = status
    this.data = data
  }
  
  get isNetworkError() {
    return this.message.includes('Failed to fetch')
  }
  
  get isUnauthorized() {
    return this.status === 401
  }
}

3. 生产级API层实现

3.1 基础请求封装

javascript复制// api/client.js
const BASE_URL = process.env.REACT_APP_API_URL

export async function apiRequest(endpoint, options = {}) {
  const url = `${BASE_URL}${endpoint}`
  const controller = new AbortController()
  const timeoutId = setT