前端视角的 API 设计最佳实践

配合统一的请求封装，可以大幅简化业务代码中的错误处理逻辑。

async function fetchApi(url, options = {}) {
  try {
    const response = await fetch(url, options);
    const data = await response.json();
    if (!data.success) throw new Error(data.error?.message || '未知错误');
    return data.data;
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

分页、过滤与版本控制

对于列表接口，必须支持分页参数（如 page, limit）以及必要的过滤条件。这能有效避免一次性加载过多数据导致的渲染卡顿。

// 支持分页与过滤
GET /api/v1/users?page=1&limit=10&status=active

版本控制建议优先采用 URL 路径方式（如 /v1/），便于缓存策略配置与调试。若需更细粒度控制，也可在 Header 中指定 Accept 版本。

客户端封装

将 API 调用逻辑封装为类，统一管理 BaseURL、默认头信息及错误处理，能让业务层代码更加简洁。

class ApiClient {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
  }

  async request(endpoint, options = {}) {
    const url = `${this.baseUrl}${endpoint}`;
    const defaultOptions = {
      headers: { 'Content-Type': 'application/json' }
    };
    const mergedOptions = {
      ...defaultOptions,
      ...options,
      headers: { ...defaultOptions.headers, ...options.headers }
    };

    const response = await fetch(url, mergedOptions);
    const data = await response.json();
    
    if (!data.success) throw new Error(data.error?.message || '请求失败');
    return data.data;
  }

  getUsers(params = {}) {
    const queryString = new URLSearchParams(params).toString();
    return this.request(`/users${queryString ? `?${queryString}` : ''}`);
  }
}

const api = new ApiClient('https://api.example.com/v1');
api.getUsers({ page: 1 }).then(console.log);

核心建议

前端开发者不应被动等待接口交付。积极参与接口评审，从调用方角度提出需求，能显著减少后期的返工成本。

当然，设计并非越复杂越好。过度设计的接口会增加双方维护负担。核心原则始终是：易用性优于炫技。如果接口让使用者感到困惑，那便是失败的設計。