前端API设计最佳实践：让你的API更优雅

优质文章学习记录

— 6 min read

前端API设计最佳实践：让你的API更优雅

毒舌时刻

API设计？听起来就像是后端工程师的事情，关前端什么事？你以为前端只需要调用API就可以了？别天真了！如果API设计得不好，前端开发会变得非常痛苦。

你以为随便设计个API就能用？别做梦了！我见过太多糟糕的API设计，比如返回的数据结构不一致，错误处理不规范，文档不完整，这些都会让前端开发者崩溃。

为什么你需要这个

  1. 提高开发效率：良好的API设计可以减少前端开发的工作量，提高开发效率。
  2. 减少错误：规范的API设计可以减少前端开发中的错误，提高代码的可靠性。
  3. 改善用户体验：合理的API设计可以提高应用的响应速度，改善用户体验。
  4. 便于维护：良好的API设计可以使代码更易于维护，减少后期的维护成本。
  5. 促进团队协作：规范的API设计可以促进前后端团队的协作，减少沟通成本。

反面教材

// 这是一个典型的糟糕API设计 // 1. 不一致的命名规范 // 获取用户列表 fetch('/api/getUsers') .then(response => response.json()) .then(data => console.log(data)); // 获取单个用户 fetch('/api/user/1') .then(response => response.json()) .then(data => console.log(data)); // 2. 不一致的返回格式 // 成功返回 // { "status": "success", "data": { "id": 1, "name": "John" } } // 失败返回 // { "error": "User not found" } // 3. 不规范的错误处理 fetch('/api/users') .then(response => { if (response.status === 200) { return response.json(); } else if (response.status === 404) { throw new Error('Not found'); } else if (response.status === 500) { throw new Error('Server error'); } else { throw new Error('Unknown error'); } }) .then(data => console.log(data)) .catch(error => console.error(error)); // 4. 缺少分页和过滤 fetch('/api/users') .then(response => response.json()) .then(data => { // 当用户数量很多时，会返回大量数据，影响性能 console.log(data); });

问题：

  • 命名规范不一致，有的使用驼峰命名，有的使用下划线命名
  • 返回格式不一致，成功和失败的返回格式不同
  • 错误处理不规范，需要手动处理不同的状态码
  • 缺少分页和过滤功能，返回大量数据时影响性能
  • 缺少版本控制，后续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设计的目的是为了方便使用，而不是为了炫技。如果你的API设计让使用者感到困惑，那你就失败了。

Read more

让 clawdbot（openclaw） 变身超强米家管家：一套通用的 AI Agent 智能家居控制方案

【开源】让 clawdbot（openclaw） 变身超强米家管家：一套通用的 AI Agent 智能家居控制方案 💡 引言 还在用传统的手机 APP 一个个点选开关？或者受限于小爱同学相对固定的指令集？随着 AI Agent（人工智能代理）时代的到来，我们完全可以用更自然、更像“真人”的方式来掌管我们的智能家居。 最近我开发并整理了一套米家控制通用 AI 代理技能包，实测在 Claude (Agent Skills)、GitHub Copilot 以及 Cursor 等 AI 助理中运行非常完美。今天就把这套方案分享给大家。 🔥 核心亮点 1. 真正的自然语言理解：不用死记硬背指令，对 AI 说“我要睡觉了”，它会自动帮你关灯、拉窗帘、开启空气净化器睡眠模式。 2.
AI数据标注平台的选型与实践：效率提升背后的技术逻辑

AI数据标注平台的选型与实践：效率提升背后的技术逻辑

👋 大家好，欢迎来到我的技术博客！ 📚 在这里，我会分享学习笔记、实战经验与技术思考，力求用简单的方式讲清楚复杂的问题。 🎯 本文将围绕人工智能这个话题展开，希望能为你带来一些启发或实用的参考。 🌱 无论你是刚入门的新手，还是正在进阶的开发者，希望你都能有所收获！ 文章目录 * AI数据标注平台的选型与实践：效率提升背后的技术逻辑 🚀 * 引言：为什么标注平台的选型决定了你与竞品的差距？ * 第一部分：选型核心：超越表面的功能清单 * 1. 架构模式：SaaS vs. 私有化部署 ⚖️ * 2. 实时性与并发：WebSocket的魔法 ✨ * 3. 标注格式的“中间态”设计 🎨 * 第二部分：效率提升背后的技术架构 * 数据流转与任务分发架构 * 实战：构建一个智能预标注控制器 (Python示例) * 第三部分：不同数据类型的效率优化技术细节 * 1. 计算机视觉 (CV)：交互方式的降维打击 * 2. 自然语言处理 (NLP)：LLM如何改变标注剧本？ * 第四
从MVP到千万级并发 AI在前后端开发中的差异化落地指南

从MVP到千万级并发 AI在前后端开发中的差异化落地指南

文章目录 * 前言 * 一、技术原理解析 * 1. 核心差异维度对比 * 2. AI 辅助开发的技术架构模型 * 二、按 DAU 规模分层的实战策略与代码实证 * 1. 低 DAU 项目（<1万）：MVP 验证期 * 后端实战：从需求到接口的秒级响应 * 前端实战：快速但粗糙的 UI * 2. 中 DAU 项目（1万–100万）：业务增长期 * 后端：复杂业务逻辑的精准生成 * 前端：C端体验的“陷阱” * 3. 高 DAU 项目（>100万）：高并发架构期 * 后端进阶：AI 驱动的性能优化 * 高并发流程架构图 * 三、
Python 驱动浏览器自动化：Playwright + AI 的 2026 最佳实践

Python 驱动浏览器自动化：Playwright + AI 的 2026 最佳实践

摘要：在 Web 自动化领域，Selenium 曾经的霸主地位已成历史，Playwright 凭其“快、稳、强”的现代特性成为了新标准。而在 2026 年，随着 LLM（大语言模型）和视觉多模态模型的爆发，自动化测试与 RPA（机器人流程自动化）迎来了范式革命。本文将深度解析 Playwright 的核心架构，并手把手教你构建一个具备“自愈能力”的 AI 驱动自动化 Agent。本文超 7000 字，包含大量实战代码与反爬对抗技巧。 第一章：Selenium 已死，Playwright 当立？ 1.1 自动化的“不可能三角” 长期以来，Web 自动化工程师都在速度、稳定性和抗检测性之间做取舍： * Selenium: