前端 API 设计最佳实践

问题：

• 命名规范不一致，有的使用驼峰命名，有的使用下划线命名
• 返回格式不一致，成功和失败的返回格式不同
• 错误处理不规范，需要手动处理不同的状态码
• 缺少分页和过滤功能，返回大量数据时影响性能
• 缺少版本控制，后续 API 变更时会影响现有代码

正确的做法

RESTful API 设计

// 1. 一致的命名规范
// 获取用户列表
fetch('/api/v1/users')
  .then(response => response.json())
  .then(data => console.log(data));
// 获取单个用户
fetch('/api/v1/users/1')
  .then(response => response.json())
  .then(data => console.log(data));
// 创建用户
fetch('/api/v1/users', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'John', email: '[email protected]' })
})
  .then(response => response.json())
  .then(data => console.log(data));
// 更新用户
fetch('/api/v1/users/1', {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'John Doe', email: '[email protected]' })
})
  .then(response => response.json())
  .then(data => console.log(data));
// 删除用户
fetch('/api/v1/users/1', {
  method: 'DELETE'
})
  .then(response => response.json())
  .then(data => console.log(data));

一致的返回格式

// 成功返回
// {
//  "success": true,
//  "data": { "id": 1, "name": "John" },
//  "message": "User retrieved successfully"
// }
// 失败返回
// {
//  "success": false,
//  "error": { "code": 404, "message": "User not found" }
// }
// 统一的错误处理
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;
  }
}
// 使用统一的错误处理
fetchApi('/api/v1/users')
  .then(data => console.log(data))
  .catch(error => console.error(error));

分页和过滤

// 分页
fetch('/api/v1/users?page=1&limit=10')
  .then(response => response.json())
  .then(data => console.log(data));
// 过滤
fetch('/api/v1/users?name=John&email=example.com')
  .then(response => response.json())
  .then(data => console.log(data));
// 排序
fetch('/api/v1/users?sort=name&order=asc')
  .then(response => response.json())
  .then(data => console.log(data));

API 版本控制

// 使用 URL 路径进行版本控制
fetch('/api/v1/users')
  .then(response => response.json())
  .then(data => console.log(data));
// 或使用请求头进行版本控制
fetch('/api/users', {
  headers: { 'Accept': 'application/vnd.example.v1+json' }
})
  .then(response => response.json())
  .then(data => console.log(data));

API 客户端封装

// api.js - 封装 API 客户端
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 }
    };
    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;
    }
  }
  // 用户相关 API
  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'
    });
  }
}
// 使用 API 客户端
const api = new ApiClient('https://api.example.com/v1');
// 获取用户列表
api.getUsers({ page: 1, limit: 10 })
  .then(users => console.log(users))
  .catch(error => console.error(error));
// 创建用户
api.createUser({ name: 'John', email: '[email protected]' })
  .then(user => console.log(user))
  .catch(error => console.error(error));

总结与建议

API 设计确实很重要，但我见过太多前端开发者把 API 设计的责任完全推给后端，自己只负责调用。后端开发者可能不了解前端的需求，设计出来的 API 可能并不适合前端使用。

想象一下，当后端设计了一个返回格式不一致的 API，前端需要写大量的代码来处理不同的返回格式，这会大大增加前端的开发工作量。

还有那些没有分页和过滤功能的 API，当数据量很大时，前端会收到大量数据，导致应用变得很慢。

所以，前端开发者应该积极参与 API 设计，与后端开发者沟通，确保 API 设计符合前端的需求。

当然，API 设计也不是越复杂越好。过于复杂的 API 设计会增加后端的开发成本，也会增加前端的学习成本。

最后，记住一句话：API 设计的目的是为了方便使用，而不是为了炫技。如果你的 API 设计让使用者感到困惑，那你就失败了。