前端 API 设计最佳实践与规范指南

主要问题：

• 命名规范不一致（驼峰 vs 下划线）
• 返回格式不统一（成功/失败结构不同）
• 错误处理分散，需手动处理状态码
• 缺少分页和过滤功能
• 缺少版本控制，变更影响现有代码

正确的做法

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;
    }
  }

  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(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 设计的目的是方便使用，而非炫技。