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

统一响应结构

无论成功还是失败，外层结构保持一致，方便前端封装通用请求函数。

// 推荐：统一响应结构
// 成功：{ success: true, data: {...}, message: '...' }
// 失败：{ success: false, error: { code: 404, message: '...' } }

配合一个通用的请求封装，可以极大简化业务代码。

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 || 'Unknown error');
    }
    return data.data;
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

完善分页与过滤

大数据量场景下，必须支持分页和筛选参数。

// 推荐：支持分页、排序和过滤
GET /api/v1/users?page=1&limit=10&sort=name&order=asc

做好版本控制

通过 URL 路径或请求头管理版本，确保升级不影响存量用户。

// 推荐：URL 路径版本控制
GET /api/v1/users
// 或者请求头版本控制
Accept: application/vnd.example.v1+json

封装客户端类

将基础逻辑抽离到客户端类中，业务层只关注具体操作。

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 };
    
    try {
      const response = await fetch(url, mergedOptions);
      const data = await response.json();
      if (!data.success) {
        throw new Error(data.error?.message || 'Unknown error');
      }
      return data.data;
    } catch (error) {
      console.error('API Error:', error);
      throw error;
    }
  }

  getUsers(params = {}) {
    const queryString = new URLSearchParams(params).toString();
    return this.request(`/users${queryString ? `?${queryString}` : ''}`);
  }
  
  getUser(id) {
    return this.request(`/users/${id}`);
  }
  
  createUser(user) {
    return this.request('/users', { method: 'POST', body: JSON.stringify(user) });
  }
  
  updateUser(id, user) {
    return this.request(`/users/${id}`, { method: 'PUT', body: JSON.stringify(user) });
  }
  
  deleteUser(id) {
    return this.request(`/users/${id}`, { method: 'DELETE' });
  }
}

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

写在最后

API 设计不是后端单方面的责任，前端开发者应该积极参与其中。毕竟，最了解接口如何被消费的人，往往就是前端自己。

当然，设计也不是越复杂越好。过于繁琐的协议会增加双方的维护成本。记住核心原则：API 是为了方便使用而存在的，而不是为了炫技。如果一个接口让使用者感到困惑，那它的设计就已经失败了。